X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=README.md;h=f55555a0c4ca505a7bfc2c1f21dbeb283e2db1d1;hb=1197e6dfe49ea4df9f32db4432cf845b7b3f70e3;hp=815c2efb662d9df00a047da90296c05be48bf4d1;hpb=64029b1461da186627c8a4e16f1d1fa65bb22ac9;p=platform%2Fupstream%2Fgstreamer.git diff --git a/README.md b/README.md index 815c2ef..f55555a 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,31 @@ -# 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 @@ -20,9 +38,7 @@ You can find [instructions for Windows below](#windows-prerequisites-setup). ### 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: @@ -111,11 +127,92 @@ the build files to find `libmfx`. 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: @@ -124,12 +221,12 @@ ninja -C builddir devenv ``` 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: @@ -137,26 +234,6 @@ 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 @@ -207,8 +284,8 @@ GST_CHECKS=test_subbuffer meson test -C builddir --suite gstreamer gst_gstbuffer ## 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 @@ -220,23 +297,6 @@ Note that the installed files have `RPATH` stripped, so you will need to set `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 @@ -244,7 +304,10 @@ for all the subprojects (gstreamer, gst-plugins-base, etc.) 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 ... @@ -309,7 +372,7 @@ and place it into `PATH`. ### 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: @@ -321,12 +384,6 @@ Note that Meson is written entirely in Python, so you can also run it as-is 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