diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Custom-build-targets.md | 9 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 24 | ||||
| -rw-r--r-- | docs/markdown/Tutorial.md | 15 | ||||
| -rw-r--r-- | docs/markdown/snippets/deprecate_source_build_root.md | 10 |
4 files changed, 45 insertions, 13 deletions
diff --git a/docs/markdown/Custom-build-targets.md b/docs/markdown/Custom-build-targets.md index f0b50d8..76bf939 100644 --- a/docs/markdown/Custom-build-targets.md +++ b/docs/markdown/Custom-build-targets.md @@ -29,14 +29,15 @@ it does for source generation. See [Generating Sources](Generating-sources.md) for more information on this topic. -## Details on compiler invocations +## Details on command invocation Meson only permits you to specify one command to run. This is by design as writing shell pipelines into build definition files leads to -code that is very hard to maintain. If your compilation requires +code that is very hard to maintain. If your command requires multiple steps you need to write a wrapper script that does all the -necessary work. When doing this you need to be mindful of the -following issues: +necessary work. + +When doing this you need to be mindful of the following issues: * do not assume that the command is invoked in any specific directory * a target called `target` file `outfile` defined in subdir `subdir` diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index c289397..d315b53 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -397,6 +397,10 @@ the following special string substitutions: The returned object also has methods that are documented in the [object methods section](#custom-target-object) below. +**Note:** Assuming that `command:` is executed by a POSIX `sh` shell is not +portable, notably to Windows. Instead, consider using a `native: true` +[executable()](#executable), or a python script. + ### declare_dependency() ``` meson @@ -1804,17 +1808,23 @@ the following methods. or `xcode`. - `build_root()`: returns a string with the absolute path to the build - root directory. Note: this function will return the build root of - the parent project if called from a subproject, which is usually - not what you want. Try using `current_build_dir()`. + root directory. *(deprecated since 0.56.0)*: this function will return the + build root of the parent project if called from a subproject, which is usually + not what you want. Try using `current_build_dir()` or `project_build_root()`. - `source_root()`: returns a string with the absolute path to the source root directory. Note: you should use the `files()` function to refer to files in the root source directory instead of - constructing paths manually with `meson.source_root()`. This - function will return the source root of the parent project if called - from a subproject, which is usually not what you want. Try using - `current_source_dir()`. + constructing paths manually with `meson.source_root()`. + *(deprecated since 0.56.0)*: This function will return the source root of the + parent project if called from a subproject, which is usually not what you want. + Try using `current_source_dir()` or `project_source_root()`. + +- `project_build_root()` *(since 0.56.0)*: returns a string with the absolute path + to the build root directory of the current (sub)project. + +- `project_source_root()` *(since 0.56.0)*: returns a string with the absolute path + to the source root directory of the current (sub)project. - `current_build_dir()`: returns a string with the absolute path to the current build directory. diff --git a/docs/markdown/Tutorial.md b/docs/markdown/Tutorial.md index f108c0c..bf337ba 100644 --- a/docs/markdown/Tutorial.md +++ b/docs/markdown/Tutorial.md @@ -75,12 +75,23 @@ When Meson is run it prints the following output. Now we are ready to build our code. + +```console +$ cd builddir +$ ninja ``` + +If your Meson version is newer than 0.55.0, you can use the new +backend-agnostic build command: + +```console $ cd builddir $ meson compile ``` -Once that is done we can run the resulting binary. +For the rest of this document we are going to use the latter form. + +Once the executable is built we can run it. ```console $ ./demo @@ -135,7 +146,7 @@ need to recreate our build directory, run any sort of magical commands or the like. Instead we just type the exact same command as if we were rebuilding our code without any build system changes. -``` +```console $ meson compile ``` diff --git a/docs/markdown/snippets/deprecate_source_build_root.md b/docs/markdown/snippets/deprecate_source_build_root.md new file mode 100644 index 0000000..1cebef4 --- /dev/null +++ b/docs/markdown/snippets/deprecate_source_build_root.md @@ -0,0 +1,10 @@ +## `meson.build_root()` and `meson.source_root()` are deprecated + +Those function are common source of issue when used in a subproject because they +point to the parent project root which is rarely what is expected and is a +violation of subproject isolation. + +`meson.current_source_dir()` and `meson.current_build_dir()` should be used instead +and have been available in all Meson versions. New functions `meson.project_source_root()` +and `meson.project_build_root()` have been added in Meson 0.56.0 to get the root +of the current (sub)project. |