docs: explicitly declare gir build dependencies
[platform/upstream/gstreamer.git] / README.md
1 # GStreamer
2
3 This is GStreamer, a framework for streaming media.
4
5 ## Where to start
6
7 We have a website at
8
9   https://gstreamer.freedesktop.org
10
11 Our documentation, including tutorials, API reference and FAQ can be found at
12
13   https://gstreamer.freedesktop.org/documentation/
14
15 You can subscribe to our mailing lists:
16
17   https://lists.freedesktop.org/mailman/listinfo/gstreamer-announce
18
19   https://lists.freedesktop.org/mailman/listinfo/gstreamer-devel
20
21 We track bugs, feature requests and merge requests (patches) in GitLab at
22
23   https://gitlab.freedesktop.org/gstreamer/
24
25 You can join us on IRC - #gstreamer on irc.oftc.net
26
27 This repository contains all official modules supported by the GStreamer
28 community which can be found in the `subprojects/` directory.
29
30 ## Getting started
31
32 ### Install git and python 3.8+
33
34 If you're on Linux, you probably already have these. On macOS, new versions of
35 Xcode ship Python 3 already. If you're on an older Xcode, you can use the
36 [official Python installer](https://www.python.org/downloads/mac-osx/).
37
38 You can find [instructions for Windows below](#windows-prerequisites-setup).
39
40 ### Install meson and ninja
41
42 Meson 0.62 or newer is required.
43
44 On Linux and macOS you can get meson through your package manager or using:
45
46   $ pip3 install --user meson
47
48 This will install meson into `~/.local/bin` which may or may not be included
49 automatically in your PATH by default.
50
51 You should get `ninja` using your package manager or download the [official
52 release](https://github.com/ninja-build/ninja/releases) and put the `ninja`
53 binary in your PATH.
54
55 You can find [instructions for Windows below](#windows-prerequisites-setup).
56
57
58 If you used the official Python installer on macOS instead of the Python
59 3 shipped with Xcode, you might need to execute "Install Certificates.command"
60 from the Python folder in the user Applications folder:
61
62 ```
63 $ /Applications/Python\ 3.*/Install\ Certificates.command
64 ```
65
66 Otherwise you will get this error when downloading meson wraps:
67
68 ```
69 urllib.error.URLError: urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
70 ```
71
72 ### Build GStreamer and its modules
73
74 You can get all GStreamer built running:
75
76 ```
77 meson setup builddir
78 meson compile -C builddir
79 ```
80
81 This will automatically create the `builddir` directory and build everything
82 inside it.
83
84 NOTE: On Windows, meson will automatically detect and use the latest Visual
85 Studio if GCC, clang, etc are not available in `PATH`. Use the `--vsenv`
86 argument to force the use of Visual Studio.
87
88 ### External dependencies
89
90 All mandatory dependencies of GStreamer are included as [meson subprojects](https://mesonbuild.com/Subprojects.html):
91 libintl, zlib, libffi, glib. Some optional dependencies are also included as
92 subprojects, such as ffmpeg, x264, json-glib, graphene, openh264, orc, etc.
93
94 Mandatory dependencies will be automatically built if meson cannot find them on
95 your system using pkg-config. The same is true for optional dependencies that
96 are included as subprojects. You can find a full list by looking at the
97 `subprojects` directory.
98
99 Plugins that need optional dependencies that aren't included can only be built
100 if they are provided by the system. Instructions on how to build some common
101 ones such as Qt5/QML are listed below. If you do not know how to provide an
102 optional dependency needed by a plugin, you should use [Cerbero](https://gitlab.freedesktop.org/gstreamer/cerbero/#description)
103 which handles this for you automatically.
104
105 Plugins will be automatically enabled if possible, but you can ensure that
106 a particular plugin (especially if it has external dependencies) is built by
107 enabling the gstreamer repository that ships it and the plugin inside it. For
108 example, to enable the Qt5 plugin in the gst-plugins-good repository, you need
109 to run meson as follows:
110
111 ```
112 meson -Dgood=enabled -Dgst-plugins-good:qt5=enabled builddir
113 ```
114
115 This will cause Meson to error out if the plugin could not be enabled. You can
116 also flip the default and disable all plugins except those explicitly enabled
117 like so:
118
119 ```
120 meson -Dauto_features=disabled -Dgstreamer:tools=enabled -Dbad=enabled -Dgst-plugins-bad:openh264=enabled
121 ```
122
123 This will disable all optional features and then enable the `openh264` plugin
124 and the tools that ship with the core gstreamer repository: `gst-inspect-1.0`,
125 `gst-launch-1.0`, etc. As usual, you can change these values on a builddir that
126 has already been setup with `meson configure -Doption=value`.
127
128 ### Building the Qt5 QML plugin
129
130 If `qmake` is not in `PATH` and pkgconfig files are not available, you can
131 point the `QMAKE` env var to the Qt5 installation of your choosing before
132 running `meson` as shown above.
133
134 The plugin will be automatically enabled if possible, but you can ensure that
135 it is built by passing `-Dgood=enabled -Dgst-plugins-good:qt5=enabled` to `meson`.
136
137 ### Building the Intel MSDK plugin
138
139 On Linux, you need to have development files for `libmfx` installed. On
140 Windows, if you have the [Intel Media SDK](https://software.intel.com/en-us/media-sdk),
141 it will set the `INTELMEDIASDKROOT` environment variable, which will be used by
142 the build files to find `libmfx`.
143
144 The plugin will be automatically enabled if possible, but you can ensure it by
145 passing `-Dbad=enabled -Dgst-plugins-bad:msdk=enabled` to `meson`.
146
147 ### Building plugins with (A)GPL-licensed dependencies
148
149 Some plugins have GPL- or AGPL-licensed dependencies and will only be built
150 if you have explicitly opted in to allow (A)GPL-licensed dependencies by
151 passing `-Dgpl=enabled` to Meson.
152
153 List of plugins with (A)GPL-licensed dependencies (non-exhaustive) in gst-plugins-bad:
154  - dts (DTS audio decoder plugin)
155  - faad (Free AAC audio decoder plugin)
156  - iqa (Image quality assessment plugin based on dssim-c)
157  - mpeg2enc (MPEG-2 video encoder plugin)
158  - mplex (audio/video multiplexer plugin)
159  - ofa (Open Fingerprint Architecture library plugin)
160  - resindvd (Resin DVD playback plugin)
161  - x265 (HEVC/H.265 video encoder plugin)
162
163 List of plugins with (A)GPL-licensed dependencies (non-exhaustive) in gst-plugins-ugly:
164  - a52dec (Dolby Digital (AC-3) audio decoder plugin)
165  - cdio (CD audio source plugin based on libcdio)
166  - dvdread (DVD video source plugin based on libdvdread)
167  - mpeg2dec (MPEG-2 video decoder plugin based on libmpeg2)
168  - sidplay (Commodore 64 audio decoder plugin based on libsidplay)
169  - x264 (H.264 video encoder plugin based on libx264)
170
171 ### Static build
172
173 Since *1.18.0* when doing a static build using `--default-library=static`, a
174 shared library `gstreamer-full-1.0` will be produced and includes all enabled
175 GStreamer plugins and libraries. A list of libraries that needs to be exposed in
176 `gstreamer-full-1.0` ABI can be set using `gst-full-libraries` option. glib-2.0,
177 gobject-2.0 and gstreamer-1.0 are always included.
178
179 ```
180 meson --default-library=static -Dgst-full-libraries=app,video builddir
181 ```
182
183 GStreamer *1.18* requires applications using gstreamer-full-1.0 to initialize
184 static plugins by calling `gst_init_static_plugins()` after `gst_init()`. That
185 function is defined in `gst/gstinitstaticplugins.h` header file.
186
187 Since *1.20.0* `gst_init_static_plugins()` is called automatically by
188 `gst_init()` and applications must not call it manually any more. The header
189 file has been removed from public API.
190
191 One can use the `gst-full-version-script` option to pass a
192 [version script](https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html)
193 to the linker. This can be used to control the exact symbols that are exported by
194 the gstreamer-full library, allowing the linker to garbage collect unused code
195 and so reduce the total library size. A default script `gstreamer-full-default.map`
196 declares only glib/gstreamer symbols as public.
197
198 One can use the `gst-full-plugins` option to pass a list of plugins to be registered
199 in the gstreamer-full library. The default value is '*' which means that all the plugins selected
200 during the build process will be registered statically. An empty value will prevent any plugins to
201 be registered.
202
203 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.
204 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`.
205
206 The user must insure that all selected plugins and features (element, typefind, etc.) have been
207 enabled during the build configuration.
208
209 To register features, the syntax is the following:
210 plugins are separated by ';' and features from a plugin starts after ':' and are ',' separated.
211
212 As an example:
213  * `-Dgst-full-plugins=coreelements;playback;typefindfunctions;alsa;pbtypes`: enable only `coreelements`, `playback`, `typefindfunctions`, `alsa`, `pbtypes` plugins.
214  * `-Dgst-full-elements=coreelements:filesrc,fakesink,identity;alsa:alsasrc`: enable only `filesrc`, `identity` and `fakesink` elements from `coreelements` and `alsasrc` element from `alsa` plugin.
215  * `-Dgst-full-typefind-functions=typefindfunctions:wav,flv`: enable only typefind func `wav` and `flv` from `typefindfunctions`
216  * `-Dgst-full-device-providers=alsa:alsadeviceprovider`: enable `alsadeviceprovider` from `alsa`.
217  * `-Dgst-full-dynamic-types=pbtypes:video_multiview_flagset`:  enable `video_multiview_flagset` from `pbtypes
218
219 All features from the `playback` plugin will be enabled and the other plugins will be restricted to the specific features requested.
220
221 All the selected features will be registered into a dedicated `NULL` plugin name.
222
223 This will cause the features/plugins that are not registered to not be included in the final gstreamer-full library.
224
225 This is an experimental feature, backward incompatible changes could still be
226 made in the future.
227
228 ### Building documentation
229
230 Documentation is not built by default because it is slow to generate. To build
231 the documentation, first ensure that `hotdoc` is installed and `doc` option is
232 enabled. For API documentation, gobject introspection must also be enabled.
233 The special target `gst-doc` can then be used to (re)generate the documentation.
234
235 ```sh
236 $ pip install hotdoc
237 $ meson setup -Ddoc=enabled -Dintrospection=enabled builddir
238 $ meson compile -C builddir gst-doc
239 ```
240
241 NOTE: To visualize the documentation, `devhelp` can be run inside the development
242 environment (see below).
243
244 # Development environment
245
246 ## Development environment target
247
248 GStreamer ships a script that drops you into a development environment where
249 all the plugins, libraries, and tools you just built are available:
250
251 ```
252 ./gst-env.py
253 ```
254
255 Or with a custom builddir (i.e., not `build`, `_build` or `builddir`):
256
257 ```
258 ./gst-env.py --builddir <BUILDDIR>
259 ```
260
261 You can also use `ninja devenv` inside your build directory to achieve the same
262 effect. However, this may not work on Windows if meson has auto-detected the
263 visual studio environment.
264
265 Alternatively, if you'd rather not start a shell in your workflow, you
266 can mutate the current environment into a suitable state like so:
267
268 ```
269 ./gst-env.py --only-environment
270 ```
271
272 This will print output suitable for an sh-compatible `eval` function,
273 just like `ssh-agent -s`.
274
275 An external script can be run in development environment with:
276
277 ```
278 ./gst-env.py external_script.sh
279 ```
280
281 NOTE: In the development environment, a fully usable prefix is also configured
282 in `gstreamer/prefix` where you can install any extra dependency/project.
283
284 For more extensive documentation about the development environment go to [the
285 documentation](https://gstreamer.freedesktop.org/documentation/installing/building-from-source-using-meson.html).
286
287 ## Custom subprojects
288
289 We also added a meson option, `custom_subprojects`, that allows the user
290 to provide a comma-separated list of meson subprojects that should be built
291 alongside the default ones.
292
293 To use it:
294
295 ```sh
296 # Clone into the subprojects directory
297 $ git -C subprojects clone my_subproject
298 # Wipe dependency detection state, in case you have an existing build dir
299 $ meson setup --wipe builddir -Dcustom_subprojects=my_subproject
300 $ meson compile -C builddir
301 ```
302
303 ## Run tests
304
305 You can easily run the test of all the components:
306
307 ```
308 meson test -C build
309 ```
310
311 To list all available tests:
312
313 ```
314 meson test -C builddir --list
315 ```
316
317 To run all the tests of a specific component:
318
319 ```
320 meson test -C builddir --suite gst-plugins-base
321 ```
322
323 Or to run a specific test file:
324
325 ```
326 meson test -C builddir --suite gstreamer gst_gstbuffer
327 ```
328
329 Run a specific test from a specific test file:
330
331 ```
332 GST_CHECKS=test_subbuffer meson test -C builddir --suite gstreamer gst_gstbuffer
333 ```
334
335 ## Optional Installation
336
337 You can also install everything that is built into a predetermined prefix like
338 so:
339
340 ```
341 meson setup --prefix=/path/to/install/prefix builddir
342 meson compile -C builddir
343 meson install -C builddir
344 ```
345
346 Note that the installed files have `RPATH` stripped, so you will need to set
347 `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, or `PATH` as appropriate for your
348 platform for things to work.
349
350
351 ## Add information about GStreamer development environment in your prompt line
352
353 ### Bash prompt
354
355 We automatically handle `bash` and set `$PS1` accordingly.
356
357 If the automatic `$PS1` override is not desired (maybe you have a fancy custom
358 prompt), set the `$GST_BUILD_DISABLE_PS1_OVERRIDE` environment variable to
359 `TRUE` and use `$GST_ENV` when setting the custom prompt, for example with a
360 snippet like the following:
361
362 ```bash
363 ...
364 if [[ -n "${GST_ENV-}" ]];
365 then
366   PS1+="[ ${GST_ENV} ]"
367 fi
368 ...
369 ```
370
371 ### Using powerline
372
373 In your powerline theme configuration file (by default in
374 `{POWERLINE INSTALLATION DIR}/config_files/themes/shell/default.json`)
375 you should add a new environment segment as follow:
376
377 ```
378 {
379   "function": "powerline.segments.common.env.environment",
380   "args": { "variable": "GST_ENV" },
381   "priority": 50
382 },
383 ```
384
385 ## Windows Prerequisites Setup
386
387 On Windows, some of the components may require special care.
388
389 ### Git for Windows
390
391 Use the [Git for Windows](https://gitforwindows.org/) installer. It will
392 install a `bash` prompt with basic shell utils and up-to-date git binaries.
393
394 During installation, when prompted about `PATH`, you should select the
395 following option:
396
397 ![Select "Git from the command line and also from 3rd-party software"](/data/images/git-installer-PATH.png)
398
399 ### Python 3.8+ on Windows
400
401 Use the [official Python installer](https://www.python.org/downloads/windows/).
402 You must ensure that Python is installed into `PATH`:
403
404 ![Enable Add Python to PATH, then click Customize Installation](/data/images/py-installer-page1.png)
405
406 You may also want to customize the installation and install it into
407 a system-wide location such as `C:\PythonXY`, but this is not required.
408
409 ### Ninja on Windows
410
411 If you are using Visual Studio 2019 or newer, Ninja is already provided.
412
413 In other cases, the easiest way to install Ninja on Windows is with `pip3`,
414 which will download the compiled binary and place it into the `Scripts`
415 directory inside your Python installation:
416
417 ```
418 pip3 install ninja
419 ```
420
421 You can also download the [official release](https://github.com/ninja-build/ninja/releases)
422 and place it into `PATH`, or use MSYS2.
423
424 ### Meson on Windows
425
426 **IMPORTANT**: Do not use the Meson MSI installer since it is experimental and known to not
427 work with `GStreamer`.
428
429 You can use `pip3` to install Meson, same as Ninja above:
430
431 ```
432 pip3 install meson
433 ```
434
435 Note that Meson is written entirely in Python, so you can also run it as-is
436 from the [git repository](https://github.com/mesonbuild/meson/) if you want to
437 use the latest master branch for some reason.
438
439 ### Running Meson on Windows
440
441 Since version 0.59.0, Meson automatically activates the Visual Studio
442 environment on Windows if no other compilers (gcc, clang, etc) are found. To
443 force the use of Visual Studio in such cases, you can use:
444
445 ```
446 meson setup --vsenv builddir
447 ```
448
449 ### Setup a mingw/wine based development environment on linux
450
451 #### Install wine and mingw
452
453 ##### On fedora x64
454
455 ``` sh
456 sudo dnf install mingw64-gcc mingw64-gcc-c++ mingw64-pkg-config mingw64-winpthreads wine
457 ```
458
459 FIXME: Figure out what needs to be installed on other distros
460
461 #### Get meson from git
462
463 This simplifies the process and allows us to use the cross files
464 defined in meson itself.
465
466 ``` sh
467 git clone https://github.com/mesonbuild/meson.git
468 ```
469
470 #### Build and install
471
472 ```
473 BUILDDIR=$PWD/winebuild/
474 export WINEPREFIX=$BUILDDIR/wine-prefix/ && mkdir -p $WINEPREFIX
475 # Setting the prefix is mandatory as it is used to setup symlinks within the development environment
476 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
477 meson/meson.py install -C $BUILDDIR/
478 ```
479
480 > __NOTE__: You should use `meson install -C $BUILDDIR`  each time you make a change
481 > instead of the usual `meson compile -C $BUILDDIR` as this is not in the
482 > development environment.
483
484 Alternatively, you can also use `mingw64-meson` on Fedora, which is a wrapper
485 script that sets things up to use Fedora's cross files and settings. However,
486 the wrapper script can be buggy in some cases.
487
488 #### cross-mingw development environment
489
490 You can get into the development environment as usual with the gst-env.py
491 script:
492
493 ```
494 ./gst-env.py
495 ```
496
497 See [above](#development-environment) for more details.
498
499 After setting up [binfmt] to use wine for windows binaries,
500 you can run GStreamer tools under wine by running:
501
502 ```
503 gst-launch-1.0.exe videotestsrc ! glimagesink
504 ```
505
506 [binfmt]: http://man7.org/linux/man-pages/man5/binfmt.d.5.html