From c6431fe47e93f2d9dabeb4890842fd45ee983c56 Mon Sep 17 00:00:00 2001 From: Jussi Pakkanen Date: Mon, 18 Jun 2018 22:36:54 +0300 Subject: Added documentation. --- docs/markdown/Installing.md | 45 +++++++++++++++++++++++++------ docs/markdown/snippets/install_command.md | 12 +++++++++ 2 files changed, 49 insertions(+), 8 deletions(-) create mode 100644 docs/markdown/snippets/install_command.md diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md index b8e6a81..8348d4a 100644 --- a/docs/markdown/Installing.md +++ b/docs/markdown/Installing.md @@ -4,7 +4,8 @@ short-description: Installing targets # Installing -By default Meson will not install anything. Build targets can be installed by tagging them as installable in the definition. +By default Meson will not install anything. Build targets can be +installed by tagging them as installable in the definition. ```meson project('install', 'c') @@ -14,8 +15,8 @@ shared_library('mylib', 'libfile.c', install : true) There is usually no need to specify install paths or the like. Meson will automatically install it to the standards-conforming location. In this particular case the executable is installed to the `bin` -subdirectory of the install prefix. However if you wish to override the -install dir, you can do that with the `install_dir` argument. +subdirectory of the install prefix. However if you wish to override +the install dir, you can do that with the `install_dir` argument. ```meson executable('prog', 'prog.c', install : true, install_dir : 'my/special/dir') @@ -42,7 +43,9 @@ install_data(['file1.txt', 'file2.txt'], install_dir : 'share/myapp') ``` -Sometimes you want to copy an entire subtree directly. For this use case there is the `install_subdir` command, which can be used like this. +Sometimes you want to copy an entire subtree directly. For this use +case there is the `install_subdir` command, which can be used like +this. ```meson install_subdir('mydir', install_dir : 'include') # mydir subtree -> include/mydir @@ -59,7 +62,10 @@ install_data(sources : 'foo.dat', install_dir : '/etc') # -> /etc/foo.dat ## Custom install behavior -Sometimes you need to do more than just install basic targets. Meson makes this easy by allowing you to specify a custom script to execute at install time. As an example, here is a script that generates an empty file in a custom directory. +Sometimes you need to do more than just install basic targets. Meson +makes this easy by allowing you to specify a custom script to execute +at install time. As an example, here is a script that generates an +empty file in a custom directory. ```bash #!/bin/sh @@ -68,7 +74,10 @@ mkdir "${DESTDIR}/${MESON_INSTALL_PREFIX}/mydir" touch "${DESTDIR}/${MESON_INSTALL_PREFIX}/mydir/file.dat" ``` -As you can see, Meson sets up some environment variables to help you write your script (`DESTDIR` is not set by Meson, it is inherited from the outside environment). In addition to the install prefix, Meson also sets the variables `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`. +As you can see, Meson sets up some environment variables to help you +write your script (`DESTDIR` is not set by Meson, it is inherited from +the outside environment). In addition to the install prefix, Meson +also sets the variables `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`. Telling Meson to run this script at install time is a one-liner. @@ -76,12 +85,32 @@ Telling Meson to run this script at install time is a one-liner. meson.add_install_script('myscript.sh') ``` -The argument is the name of the script file relative to the current subdirectory. +The argument is the name of the script file relative to the current +subdirectory. ## DESTDIR support -Sometimes you need to install to a different directory than the install prefix. This is most common when building rpm or deb packages. This is done with the `DESTDIR` environment variable and it is used just like with other build systems: +Sometimes you need to install to a different directory than the +install prefix. This is most common when building rpm or deb +packages. This is done with the `DESTDIR` environment variable and it +is used just like with other build systems: ```console $ DESTDIR=/path/to/staging/area ninja install ``` + +## Custom install behaviour + +The default install target (executed via, e.g., `ninja install`) does +installing with reasonable default options. More control over the +install behaviour can be achieved with the `meson install` command, +that has been available since 0.47.0. + +For example, if you wish to install the current setup without +rebuilding the code (which the default install target always does) and +only installing those files that have changed, you would run this +command in the build tree: + +```console +$ meson install --no-rebuild --only-changed +``` diff --git a/docs/markdown/snippets/install_command.md b/docs/markdown/snippets/install_command.md new file mode 100644 index 0000000..68866c9 --- /dev/null +++ b/docs/markdown/snippets/install_command.md @@ -0,0 +1,12 @@ +## Made install a top level Meson command + +You can now run `meson install` in your build directory and it will do +the install. It has several command line options you can toggle the +behaviour that is not in the default `ninja install` invocation. This +is similar to how `meson test` already works. + +For example, to install only the files that have changed, you can do: + +```console +meson install --only-changed +``` -- cgit v1.1