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.48 or newer is required.
25 On Linux and macOS you can get meson through your package manager or using:
27 $ pip3 install --user meson
29 This will install meson into `~/.local/bin` which may or may not be included
30 automatically in your PATH by default.
32 You should get `ninja` using your package manager or download the [official
33 release](https://github.com/ninja-build/ninja/releases) and put the `ninja`
36 You can find [instructions for Windows below](#windows-prerequisites-setup).
38 ### Build GStreamer and its modules
40 You can get all GStreamer built running:
47 This will automatically create the `build` directory and build everything
50 NOTE: On Windows, you *must* run this from [inside the Visual Studio command
51 prompt](#running-meson-on-windows) of the appropriate architecture and version.
53 ### External dependencies
55 All mandatory dependencies of GStreamer are included as [meson subprojects](https://mesonbuild.com/Subprojects.html):
56 libintl, zlib, libffi, glib. Some optional dependencies are also included as
57 subprojects, such as ffmpeg, x264, json-glib, graphene, openh264, orc, etc.
59 Mandatory dependencies will be automatically built if meson cannot find them on
60 your system using pkg-config. The same is true for optional dependencies that
61 are included as subprojects. You can find a full list by looking at the
62 `subprojects` directory.
64 Plugins that need optional dependencies that aren't included can only be built
65 if they are provided by the system. Instructions on how to build some common
66 ones such as Qt5/QML are listed below. If you do not know how to provide an
67 optional dependency needed by a plugin, you should use [Cerbero](https://gitlab.freedesktop.org/gstreamer/cerbero/#description)
68 which handles this for you automatically.
70 Plugins will be automatically enabled if possible, but you can ensure that
71 a particular plugin (especially if it has external dependencies) is built by
72 enabling the gstreamer repository that ships it and the plugin inside it. For
73 example, to enable the Qt5 plugin in the gst-plugins-good repository, you need
74 to run meson as follows:
77 meson -Dgood=enabled -Dgst-plugins-good:qt5=enabled builddir
80 This will cause Meson to error out if the plugin could not be enabled. You can
81 also flip the default and disable all plugins except those explicitly enabled
85 meson -Dauto_features=disabled -Dgstreamer:tools=enabled -Dbad=enabled -Dgst-plugins-bad:openh264=enabled
88 This will disable all optional features and then enable the `openh264` plugin
89 and the tools that ship with the core gstreamer repository: `gst-inspect-1.0`,
90 `gst-launch-1.0`, etc. As usual, you can change these values on a builddir that
91 has already been setup with `meson configure -Doption=value`.
93 ### Building the Qt5 QML plugin
95 If `qmake` is not in `PATH` and pkgconfig files are not available, you can
96 point the `QMAKE` env var to the Qt5 installation of your choosing before
97 running `meson` as shown above.
99 The plugin will be automatically enabled if possible, but you can ensure that
100 it is built by passing `-Dgood=enabled -Dgst-plugins-good:qt5=enabled` to `meson`.
102 ### Building the Intel MSDK plugin
104 On Linux, you need to have development files for `libmfx` installed. On
105 Windows, if you have the [Intel Media SDK](https://software.intel.com/en-us/media-sdk),
106 it will set the `INTELMEDIASDKROOT` environment variable, which will be used by
107 the build files to find `libmfx`.
109 The plugin will be automatically enabled if possible, but you can ensure it by
110 passing `-Dbad=enabled -Dgst-plugins-bad:msdk=enabled` to `meson`.
112 # Development environment
114 ## Development environment target
116 gst-build also contains a special `devenv` target that lets you enter an
117 development environment where you will be able to work on GStreamer
118 easily. You can get into that environment running:
121 ninja -C builddir devenv
124 If your operating system handles symlinks, built modules source code will be
125 available at the root of `gst-build/` for example GStreamer core will be in
126 `gstreamer/`. Otherwise they will be present in `subprojects/`. You can simply
127 hack in there and to rebuild you just need to rerun `ninja -C builddir`.
129 NOTE: In the development environment, a fully usable prefix is also configured
130 in `gst-build/prefix` where you can install any extra dependency/project.
132 An external script can be run in development environment with:
135 ./gst-env.py external_script.sh
138 ## Update git subprojects
140 We added a special `update` target to update subprojects (it uses `git pull
141 --rebase` meaning you should always make sure the branches you work on are
142 following the right upstream branch, you can set it with `git branch
143 --set-upstream-to origin/master` if you are working on `gst-build` master
146 Update all GStreamer modules and rebuild:
149 ninja -C builddir update
152 Update all GStreamer modules without rebuilding:
155 ninja -C builddir git-update
158 ## Custom subprojects
160 We also added a meson option, `custom_subprojects`, that allows the user
161 to provide a comma-separated list of subprojects that should be built
162 alongside the default ones.
168 git clone my_subproject
170 rm -rf * && meson .. -Dcustom_subprojects=my_subproject
176 You can easily run the test of all the components:
182 To list all available tests:
185 meson test -C builddir --list
188 To run all the tests of a specific component:
191 meson test -C builddir --suite gst-plugins-base
194 Or to run a specific test file:
197 meson test -C builddir --suite gstreamer gst_gstbuffer
200 Run a specific test from a specific test file:
203 GST_CHECKS=test_subbuffer meson test -C builddir --suite gstreamer gst_gstbuffer
206 ## Optional Installation
208 `gst-build` has been created primarily for [development usage](#development-environment-target),
209 but you can also install everything that is built into a predetermined prefix like so:
212 meson --prefix=/path/to/install/prefix builddir
214 meson install -C builddir
217 Note that the installed files have `RPATH` stripped, so you will need to set
218 `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, or `PATH` as appropriate for your
219 platform for things to work.
221 ## Checkout another branch using worktrees
223 If you need to have several versions of GStreamer coexisting (eg. `master` and `1.16`),
224 you can use the `gst-worktree.py` script provided by `gst-build`. It allows you
225 to create a new `gst-build` environment with new checkout of all the GStreamer modules as
226 [git worktrees](https://git-scm.com/docs/git-worktree).
228 For example to get a fresh checkout of `gst-1.16` from a `gst-build` repository
229 that is checked out at master, you can run:
232 ./gst-worktree.py add gst-build-1.16 origin/1.16
235 This will create a new ``gst-build-1.16`` directory pointing to the given branch `1.16`
236 for all the subprojects (gstreamer, gst-plugins-base, etc.)
239 ## Add information about GStreamer development environment in your prompt line
243 We automatically handle `bash` and set `$PS1` accordingly.
245 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:
249 if [[ -n "${GST_ENV-}" ]];
251 PS1+="[ ${GST_ENV} ]"
258 In your powerline theme configuration file (by default in
259 `{POWERLINE INSTALLATION DIR}/config_files/themes/shell/default.json`)
260 you should add a new environment segment as follow:
264 "function": "powerline.segments.common.env.environment",
265 "args": { "variable": "GST_ENV" },
270 ## Windows Prerequisites Setup
272 On Windows, some of the components may require special care.
276 Use the [Git for Windows](https://gitforwindows.org/) installer. It will
277 install a `bash` prompt with basic shell utils and up-to-date git binaries.
279 During installation, when prompted about `PATH`, you should select the
282 ![Select "Git from the command line and also from 3rd-party software"](/data/images/git-installer-PATH.png)
284 ### Python 3.5+ on Windows
286 Use the [official Python installer](https://www.python.org/downloads/windows/).
287 You must ensure that Python is installed into `PATH`:
289 ![Enable Add Python to PATH, then click Customize Installation](/data/images/py-installer-page1.png)
291 You may also want to customize the installation and install it into
292 a system-wide location such as `C:\PythonXY`, but this is not required.
296 The easiest way to install Ninja on Windows is with `pip3`, which will download
297 the compiled binary and place it into the `Scripts` directory inside your
304 You can also download the [official release](https://github.com/ninja-build/ninja/releases)
305 and place it into `PATH`.
309 **IMPORTANT**: Do not use the Meson MSI installer since it is experimental and known to not
310 work with `gst-build`.
312 You can use `pip3` to install Meson, same as Ninja above:
318 Note that Meson is written entirely in Python, so you can also run it as-is
319 from the [git repository](https://github.com/mesonbuild/meson/) if you want to
320 use the latest master branch for some reason.
322 ### Running Meson on Windows
324 At present, to build with Visual Studio, you need to run Meson from inside the
325 VS 2019 command prompt. Press `Start`, and search for `VS 2019`, and click on
326 `x64 Native Tools Command Prompt for VS 2019`, or a prompt named similar to
329 ![x64 Native Tools Command Prompt for VS 2019](/data/images/vs-2019-dev-prompt.png)
332 ### Setup a mingw/wine based development environment on linux
334 #### Install wine and mingw
339 sudo dnf install mingw64-gcc mingw64-gcc-c++ mingw64-pkg-config mingw64-winpthreads wine
342 FIXME: Figure out what needs to be installed on other distros
344 #### Get meson from git
346 This simplifies the process and allows us to use the cross files
347 defined in meson itself.
350 git clone https://github.com/mesonbuild/meson.git
353 #### Build and install
356 BUILDDIR=$PWD/winebuild/
357 export WINEPREFIX=$BUILDDIR/wine-prefix/ && mkdir -p $WINEPREFIX
358 # Setting the prefix is mandatory as it is used to setup symlinks during uninstalled development
359 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
360 meson/meson.py install -C $BUILDDIR/
363 > __NOTE__: You should use `meson install -C $BUILDDIR` each time you make a change
364 > instead of the usual `ninja -C build` as the environment is not uninstalled.
366 #### The development environment
368 You can get into the development environment the usual way:
371 ninja -C $BUILDDIR/ devenv
374 Alternatively, if you'd rather not start a shell in your workflow, you
375 can mutate the current environment into a suitable state like so:
378 gst-env.py --only-environment
381 This will print output suitable for an sh-compatible `eval` function,
382 just like `ssh-agent -s`.
384 After setting up [binfmt] to use wine for windows binaries,
385 you can run GStreamer tools under wine by running:
388 gst-launch-1.0.exe videotestsrc ! glimagesink
391 [binfmt]: http://man7.org/linux/man-pages/man5/binfmt.d.5.html