mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-09 05:38:58 +00:00
In building-from-source-using-meson.md: s/implicitely/implicitly/ In README.md: s/uncompatible/incompatible/ Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/1743>
364 lines
15 KiB
Markdown
364 lines
15 KiB
Markdown
---
|
|
short-description: Setting up a development environment the modern way
|
|
authors:
|
|
- name: Edward Hervey
|
|
email: edward@centricular.com
|
|
years: [2020]
|
|
...
|
|
|
|
|
|
# Building from source using Meson
|
|
|
|
**If you just want to use GStreamer, please visit [the download page](https://gstreamer.freedesktop.org/download/).
|
|
We provide pre-built binaries for Windows, macOS, Android, and iOS**.
|
|
|
|
This is the recommended setup for developers who want to work on the GStreamer
|
|
code itself and/or modify it, or application developers who wish to quickly try a
|
|
feature which isn't yet in a released version of GStreamer.
|
|
|
|
Note: This only applies for doing GStreamer development on Linux, Windows and
|
|
macOS. If you:
|
|
|
|
1. Want to do GStreamer development for Android, iOS, or UWP, or
|
|
1. Have to build GStreamer packages for distribution or deployment, or
|
|
1. Need plugins with external dependencies without Meson ports
|
|
|
|
Please refer to [Building using Cerbero](installing/building-from-source-using-cerbero.md),
|
|
which can be used to build a specific GStreamer release or to build unreleased
|
|
GStreamer code.
|
|
|
|
## What are Meson, gst-build and the GStreamer monorepo?
|
|
|
|
The [Meson build system][meson] is a portable build system which is fast and
|
|
meant to be more user friendly than alternatives. It generates build
|
|
instructions which can then be executed by [`ninja`][ninja]. The GStreamer
|
|
project uses it for all subprojects.
|
|
|
|
In September 2021 all of the main GStreamer modules were merged into a
|
|
single code repository, the GStreamer [mono repo][monorepo-faq] which lives
|
|
in the main [GStreamer git repository][gstreamer], and this is where all
|
|
GStreamer development happens nowadays for GStreamer version 1.19/1.20 and later.
|
|
|
|
Before the mono repository merge the different GStreamer modules lived in
|
|
separate git repositories and there was a separate meta-builder project
|
|
called [`gst-build`][gst-build] to download and build all the subprojects.
|
|
This is what you should use if you want to build or develop against older
|
|
stable branches such as GStreamer 1.16 or 1.18.
|
|
|
|
If you want to build or develop against upcoming development or stable branches
|
|
you should use the `main` branch of the GStreamer module containing the mono
|
|
repository.
|
|
|
|
In the following sections we will only talk about the GStreamer mono repo,
|
|
but `gst-build` works pretty much the same way, the only difference being
|
|
that it would download the various GStreamer submodules as well.
|
|
|
|
[monorepo-faq]: https://gstreamer.freedesktop.org/documentation/frequently-asked-questions/mono-repository.html
|
|
|
|
## Setting up the build with Meson
|
|
|
|
In order to build the current GStreamer development version, which will become
|
|
the 1.20 stable branch in the near future, clone the GStreamer mono repository:
|
|
``` shell
|
|
git clone https://gitlab.freedesktop.org/gstreamer/gstreamer.git
|
|
cd gstreamer
|
|
```
|
|
|
|
Or if you have developer access to the repositories:
|
|
``` shell
|
|
git clone git@gitlab.freedesktop.org:gstreamer/gstreamer.git
|
|
cd gstreamer
|
|
```
|
|
If you want to build the stable 1.18 or 1.16 branches, clone `gst-build`:
|
|
|
|
``` shell
|
|
git clone https://gitlab.freedesktop.org/gstreamer/gst-build.git
|
|
cd gst-build
|
|
```
|
|
|
|
### Repository layout
|
|
|
|
The repository contains a few notable scripts and directories:
|
|
1. `meson.build` is the top-level build definition which will recursively
|
|
configure all dependencies. It also defines some helper commands allowing you
|
|
to have a development environment or easily update git
|
|
repositories for the GStreamer modules.
|
|
2. `subprojects/` is the directory containing GStreamer modules and
|
|
a selection of dependencies.
|
|
|
|
|
|
## Basic meson and ninja usage
|
|
|
|
Configuring a module (or several in one go when in gst-build) is done by
|
|
executing:
|
|
|
|
``` shell
|
|
meson <build_directory>
|
|
```
|
|
|
|
The `build_directory` is where all the build instructions and output will be
|
|
located (This is also called *"out of directory"* building). If the directory is
|
|
not created it will be done so at this point. Note that calling `meson` without
|
|
any *command* argument is implicitly calling the `meson setup` command (i.e. to
|
|
do the initial configuration of a project).
|
|
|
|
There is only one restriction regarding the location of the `build_directory`:
|
|
it can't be the same as the source directory (i.e. where you cloned your module).
|
|
It can be outside of that directory or below/within that directory though.
|
|
|
|
Once meson is done configuring, you can either:
|
|
|
|
1. enter the specified build directory and run ninja.
|
|
|
|
``` shell
|
|
cd <build_directory>
|
|
ninja
|
|
```
|
|
2. *or* instead of switching to the build directory every time you wish to
|
|
execute `ninja` commands, you can just specify the build directory as an
|
|
argument. The advantage of this option is that you can run it from anywhere
|
|
(instead of changing to the ninja directory)
|
|
|
|
``` shell
|
|
ninja -C </path/to/build_directory>
|
|
```
|
|
|
|
This will build everything from that module (and subprojects if building
|
|
gst-build or the mono repository).
|
|
|
|
Note: You do not need to re-run `meson` when you modify source files, you just
|
|
need to re-run `ninja`. If you build/configuration files changed, `ninja` will
|
|
figure out on its own that `meson` needs to be re-run and will do that
|
|
automatically.
|
|
|
|
|
|
## Entering the development environment
|
|
|
|
GStreamer is made of several tools, plugins and components. In order to make it
|
|
easier for development and testing, there is a target (provided by `gst-build`
|
|
or the mono repository, and in future directly by `meson` itself) which will
|
|
setup environment variables accordingly so that you can use all the
|
|
build results directly.
|
|
|
|
For anyone familiar with python and virtualenv, you will feel right at home.
|
|
|
|
The script is called **`gst-env.py`**, it is located in the root of the
|
|
GStreamer mono-repository.
|
|
|
|
Another way to enter the virtual environment is to execute **`ninja -C
|
|
<path/to/build_directory> devenv`**. This option has less options and is
|
|
therefore not compatible with some workflows.
|
|
|
|
*NOTE*: you cannot use `meson` or reconfigure with `ninja` within the virtual
|
|
environment, therefore build before entering the environment or build from
|
|
another terminal/terminal-tab.
|
|
|
|
### How does it work?
|
|
|
|
Start a new shell session with a specific set of environment variables, that
|
|
tell GStreamer where to find plugins or libraries.
|
|
|
|
The most important options are:
|
|
|
|
+ **Shell context related variables**
|
|
* *PATH* - System path used to search for executable files, `gst-env` will
|
|
append folders containing executables from the build directory.
|
|
* *GST_PLUGIN_PATH* - List of paths to search for plugins (`.so`/`.dll`
|
|
files), `gst-env` will add all plugins found within the
|
|
`GstPluginsPath.json` file and from a few other locations.
|
|
* *GST_PLUGIN_SYSTEM_PATH* - When set this will make GStreamer check for
|
|
plugins in system wide paths, this is kept blank on purpose by `gst-env` to
|
|
avoid using plugins installed outside the environment.
|
|
* *GST_REGISTRY* - Use a custom file as plugin cache / registry. `gst-env`
|
|
utilizes the one found in the given build directory.
|
|
+ **Meson (build environment) related variables**
|
|
* *GST_VERSION* - Sets the build version in meson.
|
|
* *GST_ENV* - Makes sure that neither meson or ninja are run from within the
|
|
`gst-env`. Can be used to identify if the environment is active.
|
|
+ **Validation (test runners) related variables**
|
|
* *GST_VALIDATE_SCENARIOS_PATH* - List of paths to search for validation
|
|
scenario files (list of actions to be executed by the pipeline). By default
|
|
`gst-env` will use all scenarious found in the
|
|
`prefix/share/gstreamer-1.0/validate/scenarios` directory within the parent
|
|
directory of `gst-env.py`.
|
|
* *GST_VALIDATE_PLUGIN_PATH* - List of paths to search for plugin files to
|
|
add to the plugin registry. The default search path is in the given build
|
|
directory under `subprojects/gst-devtools/validate/plugins`.
|
|
|
|
The general idea is to set up the meson build directory, build the project and
|
|
the switch to the development environment with `gst-env`. This creates a
|
|
development environment in your shell, that provides a separate set of plugins
|
|
and tools.
|
|
To check if you are in the development environment run: `echo
|
|
$GST_ENV`, which will be set by `gst_env` to `gst-$GST_VERSION`.
|
|
|
|
You will notice the prompt changed accordingly. You can then run any GStreamer
|
|
tool you just built directly (like `gst-inspect-1.0`, `gst-launch-1.0`, ...).
|
|
|
|
### Options `gst-env`
|
|
|
|
+ **builddir**
|
|
- By default, the script will try to find the build directory within the
|
|
`build` or `builddir` directory within the same folder where
|
|
`gst-env.py` are located. This option allows to specify
|
|
a different location. This might be useful when you have multiple different
|
|
builds but you don't want to jump between folders.
|
|
+ **srcdir**
|
|
- The parent folder of `gst-env.py` is used by default.
|
|
This option is used to get the current branch of the repository, to fetch
|
|
GstValidate plugins and for gdb.
|
|
+ **sysroot**
|
|
- Useful if the project was cross-compiled on another machine and mounted via
|
|
a network file system/ssh file system/etc. Adjusts the paths (e.g. the
|
|
paths found in *GST_PLUGIN_PATH*) by removing the front part of the path
|
|
which matches *sysroot*.
|
|
|
|
<sub>For example if your rootfs is at /srv/rootfs, then the v4l2codecs plugin
|
|
might be built at
|
|
`/srv/rootfs/home/user/gstreamer/build/subprojects/gst-plugins-bad/sys/v4l2codecs`.
|
|
By executing `gst-env.py --sysroot /srv/rootfs` the path will be stored
|
|
within *GST_PLUGIN_PATH* as:
|
|
`/home/user/gstreamer/build/subprojects/gst-plugins-bad/sys/v4l2codecs`.</sub>
|
|
|
|
+ **wine**
|
|
- Extend the GST_VERSION environment variable with a specific wine command
|
|
+ **winepath**
|
|
- Add additional elements to the WINEPATH variable for wine environments.
|
|
+ **only-environment**
|
|
- Instead of opening a new shell environment, print the environment variables
|
|
that would be used.
|
|
|
|
### Use cases
|
|
|
|
#### Setting up a development environment while keeping the distribution package
|
|
|
|
This case is very simple all you have to do is either:
|
|
|
|
- `./gst-env.py` from the project root
|
|
- `ninja -C build devenv` (build is the generated meson build directory)
|
|
- `meson devenv` from the meson build directory (e.g. `build`) within the
|
|
project root
|
|
|
|
#### Using GStreamer as sub project to another project
|
|
|
|
This case is very similar to the previous, the only important deviation is that
|
|
the file system structure is important. **`gst-env`** will look for a
|
|
`GstPluginPaths.json` file either within the meson build directory (e.g.
|
|
`build`) or within `build/subprojects/gstreamer`.
|
|
|
|
#### Cross-compiling in combination with a network share
|
|
|
|
For cross compiling in general take a look at the [meson
|
|
documentation](https://mesonbuild.com/Cross-compilation.html) or at projects
|
|
like [gst-build-sdk](https://gitlab.collabora.com/collabora/gst-build-sdk).
|
|
|
|
The basic idea is to prepare a rootfs on the cross compile host, that is
|
|
similar to that of target machine, prepare a
|
|
[cross-file.txt](https://mesonbuild.com/Cross-compilation.html#defining-the-environment),
|
|
build the project and export it via a [NFS mount/NFS
|
|
rootfs](https://wiki.archlinux.org/title/NFS)/[SSHFS](https://wiki.archlinux.org/title/SSHFS)/[Syncthing](https://wiki.archlinux.org/title/Syncthing)
|
|
etc.
|
|
|
|
On the target machine you then have to remove the path to the rootfs on the
|
|
build machine from the GStreamer paths:
|
|
|
|
- `./gst-env.py --sysroot /path/to/rootfs-on-cross-compile-host`
|
|
|
|
## Working with multiple branches or remotes
|
|
|
|
It is not uncommon to track multiple git remote repositories (such as the
|
|
official upstream repositories and your personal clone on gitlab).
|
|
|
|
In the gstreamer mono repository, just add your personal git remotes as you
|
|
would do with any other git repository, e.g.:
|
|
|
|
``` shell
|
|
git remote add personal git@gitlab.freedesktop.org:awesomehacker/gstreamer.git
|
|
git fetch
|
|
```
|
|
|
|
In gst-build (for 1.16/1.18 branches), you can add your personal
|
|
git remotes in the relevant subproject directory (and that would have to be
|
|
done for each subproject of interest, since the old 1.16/1.18 branches live in
|
|
separate git repositories), e.g.:
|
|
|
|
``` shell
|
|
cd subprojects/gstreamer/
|
|
git remote add personal git@gitlab.freedesktop.org:awesomehacker/gstreamer.git
|
|
git fetch
|
|
```
|
|
|
|
|
|
## Configuration
|
|
|
|
You can list all the available options of a `meson` project by using the
|
|
configure command:
|
|
|
|
``` shell
|
|
meson configure
|
|
```
|
|
|
|
If you have an already configured build directory, you can provide that and you
|
|
will additionally get the configured values for that build:
|
|
|
|
``` shell
|
|
meson configure <build-directory>
|
|
```
|
|
|
|
That command will list for each option:
|
|
* The name of the option
|
|
* The default (or configured) value of the option
|
|
* The possible values
|
|
* The description of that option
|
|
|
|
> The values with `auto` mean that `meson` will figure out at configuration time
|
|
> the proper value (for example, if you have the available development packages
|
|
> to build a certain plugin).
|
|
>
|
|
> You will also see values with `<inherited from main project>`. This is mostly
|
|
> used for options which are generic options. For example the `doc` option is
|
|
> present at the top-level, and also on every submodules (ex:
|
|
> `gstreamer:doc`). Generally you only want to set the value of that option
|
|
> once, and all submodules will inherit from that.
|
|
|
|
You can then provide those options to `meson` when configuring the build with
|
|
`-D<option_name>=<option_value>`. For example, if one does not want to build the
|
|
rust plugins in `gst-build` (`rs` option), you would do:
|
|
|
|
``` shell
|
|
meson -Drs=disabled <build-directory>
|
|
```
|
|
|
|
You can also peek at the `meson_options.txt` files and `subproject/xyz/meson_options.txt`
|
|
files which is where the various project specific build options are listed.
|
|
These do not include all the standard Meson options however.
|
|
|
|
## Running tests
|
|
|
|
Running the unit tests is done by calling `meson test` from the build directory,
|
|
or `meson test -C <path/to/build_directory>`. If there are any failures you can
|
|
have a look at the file specified at the end or you can run `meson test
|
|
--print-errorlogs` which will show you the logs of the failing test after
|
|
execution.
|
|
|
|
You can also execute just a subset of tests by specifying the name name. For
|
|
example `meson test gst_gstpad`. The complete list of tests is available with
|
|
`meson test --list`.
|
|
|
|
If the `gst-devtools` submodule is built, you can also use
|
|
`gst-validate-launcher`[gst-validate] for running tests.
|
|
|
|
``` shell
|
|
gst-validate-launcher check.gst*
|
|
```
|
|
|
|
## Going further
|
|
|
|
More details are available in the [GStreamer mono repo README](https://gitlab.freedesktop.org/gstreamer/gstreamer/-/blob/main/README.md)
|
|
or (for the older 1.16/1.18 branches) in the [gst-build documentation](https://gitlab.freedesktop.org/gstreamer/gst-build/blob/master/README.md).
|
|
|
|
[meson]: https://mesonbuild.com/
|
|
[ninja]: https://ninja-build.org/
|
|
[gstreamer]: https://gitlab.freedesktop.org/gstreamer/gstreamer/
|
|
[gst-build]: https://gitlab.freedesktop.org/gstreamer/gst-build/
|
|
[gst-validate]: https://gstreamer.freedesktop.org/documentation/gst-devtools/
|