From 5a421886b43e4dda13eb3c8cfbb6292442741dfb Mon Sep 17 00:00:00 2001 From: Sebastian Fricke Date: Fri, 18 Feb 2022 10:47:47 +0100 Subject: [PATCH] docs: Extend documentation for the GStreamer development environment Add more extensive documentation for the development environment. Document how the tool works, how to use it and common use cases. Part-of: --- README.md | 3 + .../installing/building-from-source-using-meson.md | 124 ++++++++++++++++++++- 2 files changed, 123 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4130d25..b6d306f 100644 --- a/README.md +++ b/README.md @@ -234,6 +234,9 @@ An external script can be run in development environment with: ./gst-env.py external_script.sh ``` +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 We also added a meson option, `custom_subprojects`, that allows the user diff --git a/subprojects/gst-docs/markdown/installing/building-from-source-using-meson.md b/subprojects/gst-docs/markdown/installing/building-from-source-using-meson.md index d9a785b..7d5d00c 100644 --- a/subprojects/gst-docs/markdown/installing/building-from-source-using-meson.md +++ b/subprojects/gst-docs/markdown/installing/building-from-source-using-meson.md @@ -81,7 +81,7 @@ cd gst-build The repository contains a few notable scripts and directories: 1. `meson.build` is the top-level build definition which will recursively configure all dependencies. It also defines some helper commands allowing you - to have an uninstalled development environment or easily update git + to have a development environment or easily update git repositories for the GStreamer modules. 2. `subprojects/` is the directory containing GStreamer modules and a selection of dependencies. @@ -140,13 +140,129 @@ or the mono repository, and in future directly by `meson` itself) which will setup environment variables accordingly so that you can use all the build results directly. -``` shell -ninja -C devenv -``` +For anyone familiar with python and virtualenv, you will feel right at home. + +The script is called **`gst-env.py`**, it is located in the root of the +GStreamer mono-repository. + +Another way to enter the virtual environment is to execute **`ninja -C + devenv`**. This option has less options and is +therefore not compatible with some workflows. + +*NOTE*: you cannot use `meson` or reconfigure with `ninja` within the virtual +environment, therefore build before entering the environment or build from +another terminal/terminal-tab. + +### How does it work? + +Start a new shell session with a specific set of environment variables, that +tell GStreamer where to find plugins or libraries. + +The most important options are: + ++ **Shell context related variables** + * *PATH* - System path used to search for executable files, `gst-env` will + append folders containing executables from the build directory. + * *GST_PLUGIN_PATH* - List of paths to search for plugins (`.so`/`.dll` + files), `gst-env` will add all plugins found within the + `GstPluginsPath.json` file and from a few other locations. + * *GST_PLUGIN_SYSTEM_PATH* - When set this will make GStreamer check for + plugins in system wide paths, this is kept blank on purpose by `gst-env` to + avoid using plugins installed outside the environment. + * *GST_REGISTRY* - Use a custom file as plugin cache / registry. `gst-env` + utilizes the one found in the given build directory. ++ **Meson (build environment) related variables** + * *GST_VERSION* - Sets the build version in meson. + * *GST_ENV* - Makes sure that neither meson or ninja are run from within the + `gst-env`. Can be used to identify if the environment is active. ++ **Validation (test runners) related variables** + * *GST_VALIDATE_SCENARIOS_PATH* - List of paths to search for validation + scenario files (list of actions to be executed by the pipeline). By default + `gst-env` will use all scenarious found in the + `prefix/share/gstreamer-1.0/validate/scenarios` directory within the parent + directory of `gst-env.py`. + * *GST_VALIDATE_PLUGIN_PATH* - List of paths to search for plugin files to + add to the plugin registry. The default search path is in the given build + directory under `subprojects/gst-devtools/validate/plugins`. + +The general idea is to set up the meson build directory, build the project and +the switch to the development environment with `gst-env`. This creates a +development environment in your shell, that provides a separate set of plugins +and tools. +To check if you are in the development environment run: `echo +$GST_ENV`, which will be set by `gst_env` to `gst-$GST_VERSION`. You will notice the prompt changed accordingly. You can then run any GStreamer tool you just built directly (like `gst-inspect-1.0`, `gst-launch-1.0`, ...). +### Options `gst-env` + ++ **builddir** + - By default, the script will try to find the build directory within the + `build` or `builddir` directory within the same folder where + `gst-env.py` are located. This option allows to specify + a different location. This might be useful when you have multiple different + builds but you don't want to jump between folders. ++ **srcdir** + - The parent folder of `gst-env.py` is used by default. + This option is used to get the current branch of the repository, to fetch + GstValidate plugins and for gdb. ++ **sysroot** + - Useful if the project was cross-compiled on another machine and mounted via + a network file system/ssh file system/etc. Adjusts the paths (e.g. the + paths found in *GST_PLUGIN_PATH*) by removing the front part of the path + which matches *sysroot*. + + For example if your rootfs is at /srv/rootfs, then the v4l2codecs plugin + might be built at + `/srv/rootfs/home/user/gstreamer/build/subprojects/gst-plugins-bad/sys/v4l2codecs`. + By executing `gst-env.py --sysroot /srv/rootfs` the path will be stored + within *GST_PLUGIN_PATH* as: + `/home/user/gstreamer/build/subprojects/gst-plugins-bad/sys/v4l2codecs`. + ++ **wine** + - Extend the GST_VERSION environment variable with a specific wine command ++ **winepath** + - Add additional elements to the WINEPATH variable for wine environments. ++ **only-environment** + - Instead of opening a new shell environment, print the environment variables + that would be used. + +### Use cases + +#### Setting up a development environment while keeping the distribution package + +This case is very simple all you have to do is either: + +- `./gst-env.py` from the project root +- `ninja -C build devenv` (build is the generated meson build directory) +- `meson devenv` from the meson build directory (e.g. `build`) within the + project root + +#### Using GStreamer as sub project to another project + +This case is very similar to the previous, the only important deviation is that +the file system structure is important. **`gst-env`** will look for a +`GstPluginPaths.json` file either within the meson build directory (e.g. +`build`) or within `build/subprojects/gstreamer`. + +#### Cross-compiling in combination with a network share + +For cross compiling in general take a look at the [meson +documentation](https://mesonbuild.com/Cross-compilation.html) or at projects +like [gst-build-sdk](https://gitlab.collabora.com/collabora/gst-build-sdk). + +The basic idea is to prepare a rootfs on the cross compile host, that is +similar to that of target machine, prepare a +[cross-file.txt](https://mesonbuild.com/Cross-compilation.html#defining-the-environment), +build the project and export it via a [NFS mount/NFS +rootfs](https://wiki.archlinux.org/title/NFS)/[SSHFS](https://wiki.archlinux.org/title/SSHFS)/[Syncthing](https://wiki.archlinux.org/title/Syncthing) +etc. + +On the target machine you then have to remove the path to the rootfs on the +build machine from the GStreamer paths: + +- `./gst-env.py --sysroot /path/to/rootfs-on-cross-compile-host` ## Working with multiple branches or remotes -- 2.7.4