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>

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

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 <path/to/build_directory> 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
+<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
 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