3 GStreamer [meson](http://mesonbuild.com/) based repositories aggregrator.
5 Check out this module and run meson on it, and it will git clone the other
6 GStreamer modules as [meson subprojects](http://mesonbuild.com/Subprojects.html)
7 and build everything in one go. Once that is done you can switch into an
8 development environment which allows you to easily develop and test the latest
9 version of GStreamer without the need to install anything or touch an existing
10 GStreamer system installation.
14 ### Install git and python 3.5+
16 If you're on Linux, you probably already have these. On macOS, you can use the
17 [official Python installer](https://www.python.org/downloads/mac-osx/).
19 You can find [instructions for Windows below](#windows-prerequisites-setup).
21 ### Install meson and ninja
23 Meson 0.52 or newer is required.
25 For cross-compilation Meson 0.54 or newer is required.
27 On Linux and macOS you can get meson through your package manager or using:
29 $ pip3 install --user meson
31 This will install meson into `~/.local/bin` which may or may not be included
32 automatically in your PATH by default.
34 You should get `ninja` using your package manager or download the [official
35 release](https://github.com/ninja-build/ninja/releases) and put the `ninja`
38 You can find [instructions for Windows below](#windows-prerequisites-setup).
40 ### Build GStreamer and its modules
42 You can get all GStreamer built running:
49 This will automatically create the `build` directory and build everything
52 NOTE: On Windows, you *must* run this from [inside the Visual Studio command
53 prompt](#running-meson-on-windows) of the appropriate architecture and version.
55 ### External dependencies
57 All mandatory dependencies of GStreamer are included as [meson subprojects](https://mesonbuild.com/Subprojects.html):
58 libintl, zlib, libffi, glib. Some optional dependencies are also included as
59 subprojects, such as ffmpeg, x264, json-glib, graphene, openh264, orc, etc.
61 Mandatory dependencies will be automatically built if meson cannot find them on
62 your system using pkg-config. The same is true for optional dependencies that
63 are included as subprojects. You can find a full list by looking at the
64 `subprojects` directory.
66 Plugins that need optional dependencies that aren't included can only be built
67 if they are provided by the system. Instructions on how to build some common
68 ones such as Qt5/QML are listed below. If you do not know how to provide an
69 optional dependency needed by a plugin, you should use [Cerbero](https://gitlab.freedesktop.org/gstreamer/cerbero/#description)
70 which handles this for you automatically.
72 Plugins will be automatically enabled if possible, but you can ensure that
73 a particular plugin (especially if it has external dependencies) is built by
74 enabling the gstreamer repository that ships it and the plugin inside it. For
75 example, to enable the Qt5 plugin in the gst-plugins-good repository, you need
76 to run meson as follows:
79 meson -Dgood=enabled -Dgst-plugins-good:qt5=enabled builddir
82 This will cause Meson to error out if the plugin could not be enabled. You can
83 also flip the default and disable all plugins except those explicitly enabled
87 meson -Dauto_features=disabled -Dgstreamer:tools=enabled -Dbad=enabled -Dgst-plugins-bad:openh264=enabled
90 This will disable all optional features and then enable the `openh264` plugin
91 and the tools that ship with the core gstreamer repository: `gst-inspect-1.0`,
92 `gst-launch-1.0`, etc. As usual, you can change these values on a builddir that
93 has already been setup with `meson configure -Doption=value`.
95 ### Building the Qt5 QML plugin
97 If `qmake` is not in `PATH` and pkgconfig files are not available, you can
98 point the `QMAKE` env var to the Qt5 installation of your choosing before
99 running `meson` as shown above.
101 The plugin will be automatically enabled if possible, but you can ensure that
102 it is built by passing `-Dgood=enabled -Dgst-plugins-good:qt5=enabled` to `meson`.
104 ### Building the Intel MSDK plugin
106 On Linux, you need to have development files for `libmfx` installed. On
107 Windows, if you have the [Intel Media SDK](https://software.intel.com/en-us/media-sdk),
108 it will set the `INTELMEDIASDKROOT` environment variable, which will be used by
109 the build files to find `libmfx`.
111 The plugin will be automatically enabled if possible, but you can ensure it by
112 passing `-Dbad=enabled -Dgst-plugins-bad:msdk=enabled` to `meson`.
116 Since *1.18.0* when doing a static build using `--default-library=static`, a
117 shared library `gstreamer-full-1.0` will be produced and includes all enabled
118 GStreamer plugins and libraries. A list of libraries that needs to be exposed in
119 `gstreamer-full-1.0` ABI can be set using `gst-full-libraries` option. glib-2.0,
120 gobject-2.0 and gstreamer-1.0 are always included.
123 meson --default-library=static -Dgst-full-libraries=app,video builddir
126 GStreamer *1.18* requires applications using gstreamer-full-1.0 to initialize
127 static plugins by calling `gst_init_static_plugins()` after `gst_init()`. That
128 function is defined in `gst/gstinitstaticplugins.h` header file.
130 Since *1.20.0* `gst_init_static_plugins()` is called automatically by
131 `gst_init()` and applications must not call it manually any more. The header
132 file has been removed from public API.
134 One can use the `gst-full-version-script` option to pass a
135 [version script](https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html)
136 to the linker. This can be used to control the exact symbols that are exported by
137 the gstreamer-full library, allowing the linker to garbage collect unused code
138 and so reduce the total library size. A default script `gstreamer-full-default.map`
139 declares only glib/gstreamer symbols as public.
141 One can use the `gst-full-plugins` option to pass a list of plugins to be registered
142 in the gstreamer-full library. The default value is '*' which means that all the plugins selected
143 during the build process will be registered statically. An empty value will prevent any plugins to
146 One can select a specific set of features with `gst-full-elements`, `gst-full-typefind-functions`, `gst-full-device-providers` or `gst-full-dynamic-types` to select specific feature from a plugin.
147 When a feature has been listed in one of those options, the other features from its plugin will no longer be automatically included, even if the plugin is listed in `gst-full-plugins`.
149 The user must insure that all selected plugins and features (element, typefind, etc.) have been
150 enabled during the build configuration.
152 To register features, the syntax is the following:
153 plugins are separated by ';' and features from a plugin starts after ':' and are ',' separated.
156 * `-Dgst-full-plugins=coreelements;playback;typefindfunctions;alsa;pbtypes`: enable only `coreelements`, `playback`, `typefindfunctions`, `alsa`, `pbtypes` plugins.
157 * `-Dgst-full-elements=coreelements:filesrc,fakesink,identity;alsa:alsasrc`: enable only `filesrc`, `identity` and `fakesink` elements from `coreelements` and `alsasrc` element from `alsa` plugin.
158 * `-Dgst-full-typefind-functions=typefindfunctions:wav,flv`: enable only typefind func `wav` and `flv` from `typefindfunctions`
159 * `-Dgst-full-device-providers=alsa:alsadeviceprovider`: enable `alsadeviceprovider` from `alsa`.
160 * `-Dgst-full-dynamic-types=pbtypes:video_multiview_flagset`: enable `video_multiview_flagset` from `pbtypes
162 All features from the `playback` plugin will be enabled and the other plugins will be restricted to the specific features requested.
164 All the selected features will be registered into a dedicated `NULL` plugin name.
166 This will cause the features/plugins that are not registered to not be included in the final gstreamer-full library.
168 This is an experimental feature, backward uncompatible changes could still be
171 # Development environment
173 ## Development environment target
175 gst-build also contains a special `devenv` target that lets you enter an
176 development environment where you will be able to work on GStreamer
177 easily. You can get into that environment running:
180 ninja -C builddir devenv
183 If your operating system handles symlinks, built modules source code will be
184 available at the root of `gst-build/` for example GStreamer core will be in
185 `gstreamer/`. Otherwise they will be present in `subprojects/`. You can simply
186 hack in there and to rebuild you just need to rerun `ninja -C builddir`.
188 NOTE: In the development environment, a fully usable prefix is also configured
189 in `gst-build/prefix` where you can install any extra dependency/project.
191 An external script can be run in development environment with:
194 ./gst-env.py external_script.sh
197 ## Update git subprojects
199 We added a special `update` target to update subprojects (it uses `git pull
200 --rebase` meaning you should always make sure the branches you work on are
201 following the right upstream branch, you can set it with `git branch
202 --set-upstream-to origin/master` if you are working on `gst-build` master
205 Update all GStreamer modules and rebuild:
208 ninja -C builddir update
211 Update all GStreamer modules without rebuilding:
214 ninja -C builddir git-update
217 ## Custom subprojects
219 We also added a meson option, `custom_subprojects`, that allows the user
220 to provide a comma-separated list of subprojects that should be built
221 alongside the default ones.
227 git clone my_subproject
229 rm -rf * && meson .. -Dcustom_subprojects=my_subproject
235 You can easily run the test of all the components:
241 To list all available tests:
244 meson test -C builddir --list
247 To run all the tests of a specific component:
250 meson test -C builddir --suite gst-plugins-base
253 Or to run a specific test file:
256 meson test -C builddir --suite gstreamer gst_gstbuffer
259 Run a specific test from a specific test file:
262 GST_CHECKS=test_subbuffer meson test -C builddir --suite gstreamer gst_gstbuffer
265 ## Optional Installation
267 `gst-build` has been created primarily for [development usage](#development-environment-target),
268 but you can also install everything that is built into a predetermined prefix like so:
271 meson --prefix=/path/to/install/prefix builddir
273 meson install -C builddir
276 Note that the installed files have `RPATH` stripped, so you will need to set
277 `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, or `PATH` as appropriate for your
278 platform for things to work.
280 ## Checkout another branch using worktrees
282 If you need to have several versions of GStreamer coexisting (eg. `master` and `1.16`),
283 you can use the `gst-worktree.py` script provided by `gst-build`. It allows you
284 to create a new `gst-build` environment with new checkout of all the GStreamer modules as
285 [git worktrees](https://git-scm.com/docs/git-worktree).
287 For example to get a fresh checkout of `gst-1.16` from a `gst-build` repository
288 that is checked out at master, you can run:
291 ./gst-worktree.py add gst-build-1.16 origin/1.16
294 This will create a new ``gst-build-1.16`` directory pointing to the given branch `1.16`
295 for all the subprojects (gstreamer, gst-plugins-base, etc.)
298 ## Add information about GStreamer development environment in your prompt line
302 We automatically handle `bash` and set `$PS1` accordingly.
304 If the automatic `$PS1` override is not desired (maybe you have a fancy custom prompt), set the `$GST_BUILD_DISABLE_PS1_OVERRIDE` environment variable to `TRUE` and use `$GST_ENV` when setting the custom prompt, for example with a snippet like the following:
308 if [[ -n "${GST_ENV-}" ]];
310 PS1+="[ ${GST_ENV} ]"
317 In your powerline theme configuration file (by default in
318 `{POWERLINE INSTALLATION DIR}/config_files/themes/shell/default.json`)
319 you should add a new environment segment as follow:
323 "function": "powerline.segments.common.env.environment",
324 "args": { "variable": "GST_ENV" },
329 ## Windows Prerequisites Setup
331 On Windows, some of the components may require special care.
335 Use the [Git for Windows](https://gitforwindows.org/) installer. It will
336 install a `bash` prompt with basic shell utils and up-to-date git binaries.
338 During installation, when prompted about `PATH`, you should select the
341 ![Select "Git from the command line and also from 3rd-party software"](/data/images/git-installer-PATH.png)
343 ### Python 3.5+ on Windows
345 Use the [official Python installer](https://www.python.org/downloads/windows/).
346 You must ensure that Python is installed into `PATH`:
348 ![Enable Add Python to PATH, then click Customize Installation](/data/images/py-installer-page1.png)
350 You may also want to customize the installation and install it into
351 a system-wide location such as `C:\PythonXY`, but this is not required.
355 The easiest way to install Ninja on Windows is with `pip3`, which will download
356 the compiled binary and place it into the `Scripts` directory inside your
363 You can also download the [official release](https://github.com/ninja-build/ninja/releases)
364 and place it into `PATH`.
368 **IMPORTANT**: Do not use the Meson MSI installer since it is experimental and known to not
369 work with `gst-build`.
371 You can use `pip3` to install Meson, same as Ninja above:
377 Note that Meson is written entirely in Python, so you can also run it as-is
378 from the [git repository](https://github.com/mesonbuild/meson/) if you want to
379 use the latest master branch for some reason.
381 **ARM64 native only**: You might need
382 [native upstream ARM64 support fix](https://github.com/mesonbuild/meson/pull/7432)
383 which is expected to be a part of Meson 0.55.1.
384 If your Meson package version which was installed via `pip3` is lower than 0.55.1,
385 then you need to use [the latest master branch](https://github.com/mesonbuild/meson/).
387 ### Running Meson on Windows
389 At present, to build with Visual Studio, you need to run Meson from inside the
390 VS 2019 command prompt. Press `Start`, and search for `VS 2019`, and click on
391 `x64 Native Tools Command Prompt for VS 2019`, or a prompt named similar to
394 ![x64 Native Tools Command Prompt for VS 2019](/data/images/vs-2019-dev-prompt.png)
396 **ARM64 native only**: Since Visual Studio might not install dedicated command
397 prompt for native ARM64 build, you might need to run `vcvarsx86_arm64.bat` on CMD.
398 Please refer to [this document](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#developer_command_file_locations)
400 ### Setup a mingw/wine based development environment on linux
402 #### Install wine and mingw
407 sudo dnf install mingw64-gcc mingw64-gcc-c++ mingw64-pkg-config mingw64-winpthreads wine
410 FIXME: Figure out what needs to be installed on other distros
412 #### Get meson from git
414 This simplifies the process and allows us to use the cross files
415 defined in meson itself.
418 git clone https://github.com/mesonbuild/meson.git
421 #### Build and install
424 BUILDDIR=$PWD/winebuild/
425 export WINEPREFIX=$BUILDDIR/wine-prefix/ && mkdir -p $WINEPREFIX
426 # Setting the prefix is mandatory as it is used to setup symlinks during uninstalled development
427 meson/meson.py $BUILDDIR --cross-file meson/cross/linux-mingw-w64-64bit.txt -Dgst-plugins-bad:vulkan=disabled -Dorc:gtk_doc=disabled --prefix=$BUILDDIR/wininstall/ -Djson-glib:gtk_doc=disabled
428 meson/meson.py install -C $BUILDDIR/
431 > __NOTE__: You should use `meson install -C $BUILDDIR` each time you make a change
432 > instead of the usual `ninja -C build` as the environment is not uninstalled.
434 #### The development environment
436 You can get into the development environment the usual way:
439 ninja -C $BUILDDIR/ devenv
442 Alternatively, if you'd rather not start a shell in your workflow, you
443 can mutate the current environment into a suitable state like so:
446 gst-env.py --only-environment
449 This will print output suitable for an sh-compatible `eval` function,
450 just like `ssh-agent -s`.
452 After setting up [binfmt] to use wine for windows binaries,
453 you can run GStreamer tools under wine by running:
456 gst-launch-1.0.exe videotestsrc ! glimagesink
459 [binfmt]: http://man7.org/linux/man-pages/man5/binfmt.d.5.html