Add `meson devenv` command and meson.add_devenv()

3 files changed, 76 insertions, 0 deletions

diff --git a/docs/markdown/Commands.md b/docs/markdown/Commands.md
index 8989165..0751aed 100644
--- a/docs/markdown/Commands.md
+++ b/docs/markdown/Commands.md
@@ -263,3 +263,37 @@ An utility to manage WrapDB dependencies.
 {{ wrap_arguments.inc }}
 
 See [the WrapDB tool documentation](Using-wraptool.md) for more info.
+
+### devenv
+
+*(since 0.58.0)*
+
+{{ devenv_usage.inc }}
+
+Runs a command, or open interactive shell if no command is provided, with
+environment setup to run project from the build directory, without installation.
+
+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
+`$MESON_DISABLE_PS1_OVERRIDE` environment variable and use `$MESON_PROJECT_NAME`
+when setting the custom prompt, for example with a snippet like the following:
+
+```bash
+...
+if [[ -n "${MESON_PROJECT_NAME-}" ]];
+then
+  PS1+="[ ${MESON_PROJECT_NAME} ]"
+fi
+...
+```
+
+These variables are set in environment in addition to those set using `meson.add_devenv()`:
+- `MESON_DEVENV` is defined to `'1'`.
+- `MESON_PROJECT_NAME` is defined to the main project's name.
+- `PKG_CONFIG_PATH` includes the directory where Meson generates `-uninstalled.pc`
+  files.
+- `PATH` includes every directory where there is an executable that would be
+  installed into `bindir`. On windows it also includes every directory where there
+  is a DLL needed to run those executables.
+
+{{ devenv_arguments.inc }}
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 47e1afd..3af00c4 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -2055,6 +2055,19 @@ the following methods.
 
 - `version()`: return a string with the version of Meson.
 
+- `add_devenv()`: *(Since 0.58.0)* add an [`environment()`](#environment) object
+  to the list of environments that will be applied when using [`meson devenv`](Commands.md#devenv)
+  command line. This is useful for developpers who wish to use the project without
+  installing it, it is often needed to set for example the path to plugins
+  directory, etc. Alternatively, a list or dictionary can be passed as first
+  argument.
+  ``` meson
+  devenv = environment()
+  devenv.set('PLUGINS_PATH', meson.current_build_dir())
+  ...
+  meson.add_devenv(devenv)
+  ```
+
 ### `build_machine` object
 
 Provides information about the build machine — the machine that is
diff --git a/docs/markdown/snippets/devenv.md b/docs/markdown/snippets/devenv.md
new file mode 100644
index 0000000..c3bac10
--- /dev/null
+++ b/docs/markdown/snippets/devenv.md
@@ -0,0 +1,29 @@
+## Developer environment
+
+New method `meson.add_devenv()` adds an [`environment()`](#environment) object
+to the list of environments that will be applied when using `meson devenv`
+command line. This is useful for developpers who wish to use the project without
+installing it, it is often needed to set for example the path to plugins
+directory, etc. Alternatively, a list or dictionary can be passed as first
+argument.
+
+``` meson
+devenv = environment()
+devenv.set('PLUGINS_PATH', meson.current_build_dir())
+...
+meson.add_devenv(devenv)
+```
+
+New command line has been added: `meson devenv -C builddir [<command>]`.
+It runs a command, or open interactive shell if no command is provided, with
+environment setup to run project from the build directory, without installation.
+
+These variables are set in environment in addition to those set using `meson.add_devenv()`:
+- `MESON_DEVENV` is defined to `'1'`.
+- `MESON_PROJECT_NAME` is defined to the main project's name.
+- `PKG_CONFIG_PATH` includes the directory where Meson generates `-uninstalled.pc`
+  files.
+- `PATH` includes every directory where there is an executable that would be
+  installed into `bindir`. On windows it also includes every directory where there
+  is a DLL needed to run those executables.
+