X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=README.md;h=d34b2c024f75522f900f304e25f4bda53cd8d447;hb=a95a3ca8075c12c2c91e3e66e9b9157f42c1bcb0;hp=c9ca05158e0e6015b526bfdf53c751e96c22efca;hpb=89faf739c92e0e9ec72eb06cc224e1d64173b537;p=platform%2Fupstream%2Fgstreamer.git diff --git a/README.md b/README.md index c9ca051..d34b2c0 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,6 +127,30 @@ 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 @@ -135,16 +175,44 @@ 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. +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. -This is an experimental feature, backward uncompatible changes could still be +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 incompatible 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: @@ -153,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: @@ -166,25 +234,8 @@ 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 -``` +For more extensive documentation about the development environment go to [the +documentation](https://gstreamer.freedesktop.org/documentation/installing/building-from-source-using-meson.html). ## Custom subprojects @@ -236,8 +287,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 @@ -249,23 +300,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 @@ -273,7 +307,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 ... @@ -338,7 +375,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: @@ -350,12 +387,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 @@ -395,13 +426,13 @@ git clone https://github.com/mesonbuild/meson.git ``` BUILDDIR=$PWD/winebuild/ export WINEPREFIX=$BUILDDIR/wine-prefix/ && mkdir -p $WINEPREFIX -# Setting the prefix is mandatory as it is used to setup symlinks during uninstalled development +# Setting the prefix is mandatory as it is used to setup symlinks within the development environment 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 meson/meson.py install -C $BUILDDIR/ ``` > __NOTE__: You should use `meson install -C $BUILDDIR` each time you make a change -> instead of the usual `ninja -C build` as the environment is not uninstalled. +> instead of the usual `ninja -C build` as this is not in the development environment. #### The development environment