diff --git a/markdown/installing/building-from-source-using-meson.md b/markdown/installing/building-from-source-using-meson.md new file mode 100644 index 0000000000..629ac8da57 --- /dev/null +++ b/markdown/installing/building-from-source-using-meson.md @@ -0,0 +1,200 @@ +--- +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 + +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 try a +feature which isn't yet in a released version of GStreamer. + +Note: This only applies to linux, Windows and MacOS development. For Android and +iOS development, please refer to [Building using +Cerbero](installing/building-from-source-using-cerbero.md). + + +## What are meson and gst-build ? + +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. + +Since GStreamer has many components and has many dependencies, the +[`gst-build`][gst-build] module contains multiple python3 scripts to simplify +downloading and configuring everything using Meson. It uses a feature from meson +which allows defining subprojects and you can therefore configure and build the +GStreamer modules and certain dependencies in one go. + + +## Setting up gst-build + +First clone `gst-build`: + +``` shell +git clone https://gitlab.freedesktop.org:gstreamer/gst-build.git +cd gst-build +``` + +Or if you have developer access to the repositories: +``` shell +git clone git@gitlab.freedesktop.org:gstreamer/gst-build.git +cd gst-build +``` + +### Layout of gst-build + +gst-build 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 an uninstalled environment or easily update all git modules. +2. `submodules` is the location of the submodules. + + +## Basic meson and ninja usage + +Configuring a module (or several in one go when in gst-build) is done by +executing: + +``` shell +meson +``` + +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 implicitely 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 +or gst-build). 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 + 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 + ``` + +This will build everything from that module (and subprojects if within +gst-build). + +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 "uninstalled" 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`) +which will setup environment variables accordingly so that you can use all the +build results directly. + +``` shell +ninja -C devenv +``` + +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`, ...). + + +## 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). + +You can do so by adding your personal git remotes in the subproject directory: + +``` shell +cd subprojects/gstreamer/ +git remote add personal git@gitlab.freedesktop.org:awesomehacker/gstreamer.git +git fetch +``` + +## Configuration of gst-build + +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 +``` + +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 ``. 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=`. For example, if one does not want to build the +rust plugins in `gst-build` (`rs` option), you would do: + +``` shell +meson -Drs=disabled +``` + +## Running tests + +Running the unit tests is done by calling `meson test` from the build directory, +or `meson test -C `. 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 [gst-build +documentation](https://gitlab.freedesktop.org/gstreamer/gst-build/blob/master/README.md). + + [meson]: https://mesonbuild.com/ + [ninja]: https://ninja-build.org/ + [gst-build]: https://gitlab.freedesktop.org/gstreamer/gst-build/ + [gst-validate]: https://gstreamer.freedesktop.org/documentation/gst-devtools/ diff --git a/sitemap.txt b/sitemap.txt index fae510f768..a4b31d19cd 100644 --- a/sitemap.txt +++ b/sitemap.txt @@ -5,6 +5,7 @@ installing/on-windows.md installing/on-linux.md installing/building-from-source-using-cerbero.md + installing/building-from-source-using-meson.md tutorials/index.md tutorials/basic/index.md tutorials/basic/hello-world.md