-# gst-build
+# GStreamer
-GStreamer [meson](http://mesonbuild.com/) based repositories aggregrator.
+This is GStreamer, a framework for streaming media.
-Check out this module and run meson on it, and it will git clone the other
-GStreamer modules as [meson subprojects](http://mesonbuild.com/Subprojects.html)
-and build everything in one go. Once that is done you can switch into an
-development environment which allows you to easily develop and test the latest
-version of GStreamer without the need to install anything or touch an existing
-GStreamer system installation.
+## Where to start
+
+We have a website at
+
+ https://gstreamer.freedesktop.org
+
+Our documentation, including tutorials, API reference and FAQ can be found at
+
+ https://gstreamer.freedesktop.org/documentation/
+
+You can subscribe to our mailing lists:
+
+ https://lists.freedesktop.org/mailman/listinfo/gstreamer-announce
+
+ https://lists.freedesktop.org/mailman/listinfo/gstreamer-devel
+
+We track bugs, feature requests and merge requests (patches) in GitLab at
+
+ https://gitlab.freedesktop.org/gstreamer/
+
+You can join us on IRC - #gstreamer on irc.oftc.net
+
+This repository contains all official modules supported by the GStreamer
+community which can be found in the `subprojects/` directory.
## Getting started
### Install meson and ninja
-Meson 0.52 or newer is required.
-
-For cross-compilation Meson 0.54 or newer is required.
+Meson 0.59 or newer is required.
On Linux and macOS you can get meson through your package manager or using:
The plugin will be automatically enabled if possible, but you can ensure it by
passing `-Dbad=enabled -Dgst-plugins-bad:msdk=enabled` to `meson`.
+### Building plugins with (A)GPL-licensed dependencies
+
+Some plugins have GPL- or AGPL-licensed dependencies and will only be built
+if you have explicitly opted in to allow (A)GPL-licensed dependencies by
+passing `-Dgpl=enabled` to Meson.
+
+List of plugins with (A)GPL-licensed dependencies (non-exhaustive) in gst-plugins-bad:
+ - dts (DTS audio decoder plugin)
+ - faad (Free AAC audio decoder plugin)
+ - iqa (Image quality assessment plugin based on dssim-c)
+ - mpeg2enc (MPEG-2 video encoder plugin)
+ - mplex (audio/video multiplexer plugin)
+ - ofa (Open Fingerprint Architecture library plugin)
+ - resindvd (Resin DVD playback plugin)
+ - x265 (HEVC/H.265 video encoder plugin)
+
+List of plugins with (A)GPL-licensed dependencies (non-exhaustive) in gst-plugins-ugly:
+ - a52dec (Dolby Digital (AC-3) audio decoder plugin)
+ - cdio (CD audio source plugin based on libcdio)
+ - dvdread (DVD video source plugin based on libdvdread)
+ - mpeg2dec (MPEG-2 video decoder plugin based on libmpeg2)
+ - sidplay (Commodore 64 audio decoder plugin based on libsidplay)
+ - x264 (H.264 video encoder plugin based on libx264)
+
+### Static build
+
+Since *1.18.0* when doing a static build using `--default-library=static`, a
+shared library `gstreamer-full-1.0` will be produced and includes all enabled
+GStreamer plugins and libraries. A list of libraries that needs to be exposed in
+`gstreamer-full-1.0` ABI can be set using `gst-full-libraries` option. glib-2.0,
+gobject-2.0 and gstreamer-1.0 are always included.
+
+```
+meson --default-library=static -Dgst-full-libraries=app,video builddir
+```
+
+GStreamer *1.18* requires applications using gstreamer-full-1.0 to initialize
+static plugins by calling `gst_init_static_plugins()` after `gst_init()`. That
+function is defined in `gst/gstinitstaticplugins.h` header file.
+
+Since *1.20.0* `gst_init_static_plugins()` is called automatically by
+`gst_init()` and applications must not call it manually any more. The header
+file has been removed from public API.
+
+One can use the `gst-full-version-script` option to pass a
+[version script](https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html)
+to the linker. This can be used to control the exact symbols that are exported by
+the gstreamer-full library, allowing the linker to garbage collect unused code
+and so reduce the total library size. A default script `gstreamer-full-default.map`
+declares only glib/gstreamer symbols as public.
+
+One can use the `gst-full-plugins` option to pass a list of plugins to be registered
+in the gstreamer-full library. The default value is '*' which means that all the plugins selected
+during the build process will be registered statically. An empty value will prevent any plugins to
+be registered.
+
+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.
+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`.
+
+The user must insure that all selected plugins and features (element, typefind, etc.) have been
+enabled during the build configuration.
+
+To register features, the syntax is the following:
+plugins are separated by ';' and features from a plugin starts after ':' and are ',' separated.
+
+As an example:
+ * `-Dgst-full-plugins=coreelements;playback;typefindfunctions;alsa;pbtypes`: enable only `coreelements`, `playback`, `typefindfunctions`, `alsa`, `pbtypes` plugins.
+ * `-Dgst-full-elements=coreelements:filesrc,fakesink,identity;alsa:alsasrc`: enable only `filesrc`, `identity` and `fakesink` elements from `coreelements` and `alsasrc` element from `alsa` plugin.
+ * `-Dgst-full-typefind-functions=typefindfunctions:wav,flv`: enable only typefind func `wav` and `flv` from `typefindfunctions`
+ * `-Dgst-full-device-providers=alsa:alsadeviceprovider`: enable `alsadeviceprovider` from `alsa`.
+ * `-Dgst-full-dynamic-types=pbtypes:video_multiview_flagset`: enable `video_multiview_flagset` from `pbtypes
+
+All features from the `playback` plugin will be enabled and the other plugins will be restricted to the specific features requested.
+
+All the selected features will be registered into a dedicated `NULL` plugin name.
+
+This will cause the features/plugins that are not registered to not be included in the final gstreamer-full library.
+
+This is an experimental feature, backward uncompatible changes could still be
+made in the future.
+
# Development environment
## Development environment target
-gst-build also contains a special `devenv` target that lets you enter an
+GStreamer also contains a special `devenv` target that lets you enter an
development environment where you will be able to work on GStreamer
easily. You can get into that environment running:
```
If your operating system handles symlinks, built modules source code will be
-available at the root of `gst-build/` for example GStreamer core will be in
+available at the root for example GStreamer core will be in
`gstreamer/`. Otherwise they will be present in `subprojects/`. You can simply
hack in there and to rebuild you just need to rerun `ninja -C builddir`.
NOTE: In the development environment, a fully usable prefix is also configured
-in `gst-build/prefix` where you can install any extra dependency/project.
+in `gstreamer/prefix` where you can install any extra dependency/project.
An external script can be run in development environment with:
./gst-env.py external_script.sh
```
-## Update git subprojects
-
-We added a special `update` target to update subprojects (it uses `git pull
---rebase` meaning you should always make sure the branches you work on are
-following the right upstream branch, you can set it with `git branch
---set-upstream-to origin/master` if you are working on `gst-build` master
-branch).
-
-Update all GStreamer modules and rebuild:
-
-```
-ninja -C builddir update
-```
-
-Update all GStreamer modules without rebuilding:
-
-```
-ninja -C builddir git-update
-```
-
## Custom subprojects
We also added a meson option, `custom_subprojects`, that allows the user
## Optional Installation
-`gst-build` has been created primarily for [development usage](#development-environment-target),
-but you can also install everything that is built into a predetermined prefix like so:
+You can also install everything that is built into a predetermined prefix like
+so:
```
meson --prefix=/path/to/install/prefix builddir
`LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, or `PATH` as appropriate for your
platform for things to work.
-## Checkout another branch using worktrees
-
-If you need to have several versions of GStreamer coexisting (eg. `master` and `1.16`),
-you can use the `gst-worktree.py` script provided by `gst-build`. It allows you
-to create a new `gst-build` environment with new checkout of all the GStreamer modules as
-[git worktrees](https://git-scm.com/docs/git-worktree).
-
-For example to get a fresh checkout of `gst-1.16` from a `gst-build` repository
-that is checked out at master, you can run:
-
-```
-./gst-worktree.py add gst-build-1.16 origin/1.16
-```
-
-This will create a new ``gst-build-1.16`` directory pointing to the given branch `1.16`
-for all the subprojects (gstreamer, gst-plugins-base, etc.)
-
## Add information about GStreamer development environment in your prompt line
We automatically handle `bash` and set `$PS1` accordingly.
-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:
+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:
```bash
...
### Meson on Windows
**IMPORTANT**: Do not use the Meson MSI installer since it is experimental and known to not
-work with `gst-build`.
+work with `GStreamer`.
You can use `pip3` to install Meson, same as Ninja above:
from the [git repository](https://github.com/mesonbuild/meson/) if you want to
use the latest master branch for some reason.
-**ARM64 native only**: You might need
-[native upstream ARM64 support fix](https://github.com/mesonbuild/meson/pull/7432)
-which is expected to be a part of Meson 0.55.1.
-If your Meson package version which was installed via `pip3` is lower than 0.55.1,
-then you need to use [the latest master branch](https://github.com/mesonbuild/meson/).
-
### Running Meson on Windows
At present, to build with Visual Studio, you need to run Meson from inside the
projects / platform / upstream / gstreamer.git / blobdiff