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: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/1743>
This commit is contained in:
Sebastian Fricke 2022-02-18 10:47:47 +01:00 committed by GStreamer Marge Bot
parent 0b6bbce012
commit 5a421886b4
2 changed files with 123 additions and 4 deletions

View file

@ -234,6 +234,9 @@ An external script can be run in development environment with:
./gst-env.py external_script.sh ./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 ## Custom subprojects
We also added a meson option, `custom_subprojects`, that allows the user We also added a meson option, `custom_subprojects`, that allows the user

View file

@ -81,7 +81,7 @@ cd gst-build
The repository contains a few notable scripts and directories: The repository contains a few notable scripts and directories:
1. `meson.build` is the top-level build definition which will recursively 1. `meson.build` is the top-level build definition which will recursively
configure all dependencies. It also defines some helper commands allowing you 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. repositories for the GStreamer modules.
2. `subprojects/` is the directory containing GStreamer modules and 2. `subprojects/` is the directory containing GStreamer modules and
a selection of dependencies. 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 setup environment variables accordingly so that you can use all the
build results directly. build results directly.
``` shell For anyone familiar with python and virtualenv, you will feel right at home.
ninja -C <path/to/build_directory> devenv
``` 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
<path/to/build_directory> 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 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`, ...). 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*.
<sub>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`.</sub>
+ **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 ## Working with multiple branches or remotes