| 1 |
--- |
| 2 |
short-description: Installing targets |
| 3 |
... |
| 4 |
|
| 5 |
# Installing |
| 6 |
|
| 7 |
Invoked via the [following command](Commands.md#install) *(available |
| 8 |
since 0.47.0)*: |
| 9 |
|
| 10 |
```sh |
| 11 |
meson install |
| 12 |
``` |
| 13 |
|
| 14 |
or alternatively (on older Meson versions with `ninja` backend): |
| 15 |
|
| 16 |
```sh |
| 17 |
ninja install |
| 18 |
``` |
| 19 |
|
| 20 |
By default Meson will not install anything. Build targets can be |
| 21 |
installed by tagging them as installable in the definition. |
| 22 |
|
| 23 |
```meson |
| 24 |
project('install', 'c') |
| 25 |
shared_library('mylib', 'libfile.c', install : true) |
| 26 |
``` |
| 27 |
|
| 28 |
There is usually no need to specify install paths or the like. Meson |
| 29 |
will automatically install it to the standards-conforming location. In |
| 30 |
this particular case the executable is installed to the `bin` |
| 31 |
subdirectory of the install prefix. However if you wish to override |
| 32 |
the install dir, you can do that with the `install_dir` argument. |
| 33 |
|
| 34 |
```meson |
| 35 |
executable('prog', 'prog.c', install : true, install_dir : 'my/special/dir') |
| 36 |
``` |
| 37 |
|
| 38 |
Other install commands are the following. |
| 39 |
|
| 40 |
```meson |
| 41 |
install_headers('header.h', subdir : 'projname') # -> include/projname/header.h |
| 42 |
install_man('foo.1') # -> share/man/man1/foo.1 |
| 43 |
install_data('datafile.dat', install_dir : get_option('datadir') / 'progname') |
| 44 |
# -> share/progname/datafile.dat |
| 45 |
``` |
| 46 |
|
| 47 |
`install_data()` supports rename of the file *since 0.46.0*. |
| 48 |
|
| 49 |
```meson |
| 50 |
# file.txt -> {datadir}/{projectname}/new-name.txt |
| 51 |
install_data('file.txt', rename : 'new-name.txt') |
| 52 |
|
| 53 |
# file1.txt -> share/myapp/dir1/data.txt |
| 54 |
# file2.txt -> share/myapp/dir2/data.txt |
| 55 |
install_data(['file1.txt', 'file2.txt'], |
| 56 |
rename : ['dir1/data.txt', 'dir2/data.txt'], |
| 57 |
install_dir : 'share/myapp') |
| 58 |
``` |
| 59 |
|
| 60 |
Sometimes you want to copy an entire subtree directly. For this use |
| 61 |
case there is the `install_subdir` command, which can be used like |
| 62 |
this. |
| 63 |
|
| 64 |
```meson |
| 65 |
install_subdir('mydir', install_dir : 'include') # mydir subtree -> include/mydir |
| 66 |
``` |
| 67 |
|
| 68 |
Most of the time you want to install files relative to the install |
| 69 |
prefix. Sometimes you need to go outside of the prefix (such as writing |
| 70 |
files to `/etc` instead of `/usr/etc`. This can be accomplished by |
| 71 |
giving an absolute install path. |
| 72 |
|
| 73 |
```meson |
| 74 |
install_data(sources : 'foo.dat', install_dir : '/etc') # -> /etc/foo.dat |
| 75 |
``` |
| 76 |
|
| 77 |
## Custom install script |
| 78 |
|
| 79 |
Sometimes you need to do more than just install basic targets. Meson |
| 80 |
makes this easy by allowing you to specify a custom script to execute |
| 81 |
at install time. As an example, here is a script that generates an |
| 82 |
empty file in a custom directory. |
| 83 |
|
| 84 |
```bash |
| 85 |
#!/bin/sh |
| 86 |
|
| 87 |
mkdir "${DESTDIR}/${MESON_INSTALL_PREFIX}/mydir" |
| 88 |
touch "${DESTDIR}/${MESON_INSTALL_PREFIX}/mydir/file.dat" |
| 89 |
``` |
| 90 |
|
| 91 |
As you can see, Meson sets up some environment variables to help you |
| 92 |
write your script (`DESTDIR` is not set by Meson, it is inherited from |
| 93 |
the outside environment). In addition to the install prefix, Meson |
| 94 |
also sets the variables `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`. |
| 95 |
|
| 96 |
Telling Meson to run this script at install time is a one-liner. |
| 97 |
|
| 98 |
```meson |
| 99 |
[[#meson.add_install_script]]('myscript.sh') |
| 100 |
``` |
| 101 |
|
| 102 |
The argument is the name of the script file relative to the current |
| 103 |
subdirectory. |
| 104 |
|
| 105 |
## Installing as the superuser |
| 106 |
|
| 107 |
When building as a non-root user, but installing to root-owned locations via |
| 108 |
e.g. `sudo ninja install`, ninja will attempt to rebuild any out of date |
| 109 |
targets as root. This results in various bad behaviors due to build outputs and |
| 110 |
ninja internal files being owned by root. |
| 111 |
|
| 112 |
Running `meson install` is preferred for several reasons. It can rebuild out of |
| 113 |
date targets and then re-invoke itself as root. *(since 1.1.0)* Additionally, |
| 114 |
running `sudo meson install` will drop permissions and rebuild out of date |
| 115 |
targets as the original user, not as root. |
| 116 |
|
| 117 |
*(since 1.1.0)* Re-invoking as root will try to guess the user's preferred method for |
| 118 |
re-running commands as root. The order of precedence is: sudo, doas, run0, pkexec |
| 119 |
(polkit). An elevation tool can be forced by setting `$MESON_ROOT_CMD`. |
| 120 |
|
| 121 |
## DESTDIR support |
| 122 |
|
| 123 |
Sometimes you need to install to a different directory than the |
| 124 |
install prefix. This is most common when building rpm or deb |
| 125 |
packages. This is done with the `DESTDIR` environment variable and it |
| 126 |
is used just like with other build systems: |
| 127 |
|
| 128 |
```console |
| 129 |
$ DESTDIR=/path/to/staging/area meson install |
| 130 |
``` |
| 131 |
|
| 132 |
Since *0.57.0* `--destdir` argument can be used instead of environment. In that |
| 133 |
case Meson will set `DESTDIR` into environment when running install scripts. |
| 134 |
|
| 135 |
Since *0.60.0* `DESTDIR` and `--destdir` can be a path relative to build |
| 136 |
directory. An absolute path will be set into environment when executing scripts. |
| 137 |
|
| 138 |
## Custom install behaviour |
| 139 |
|
| 140 |
Installation behaviour can be further customized using additional |
| 141 |
arguments. |
| 142 |
|
| 143 |
For example, if you wish to install the current setup without |
| 144 |
rebuilding the code (which the default install target always does) and |
| 145 |
only installing those files that have changed, you would run this |
| 146 |
command in the build tree: |
| 147 |
|
| 148 |
```console |
| 149 |
$ meson install --no-rebuild --only-changed |
| 150 |
``` |
| 151 |
|
| 152 |
## Installation tags |
| 153 |
|
| 154 |
*Since 0.60.0* |
| 155 |
|
| 156 |
It is possible to install only a subset of the installable files using |
| 157 |
`meson install --tags tag1,tag2` command line. When `--tags` is specified, only |
| 158 |
files that have been tagged with one of the tags are going to be installed. |
| 159 |
|
| 160 |
This is intended to be used by packagers (e.g. distributions) who typically |
| 161 |
want to split `libfoo`, `libfoo-dev` and `libfoo-doc` packages. Instead of |
| 162 |
duplicating the list of installed files per category in each packaging system, |
| 163 |
it can be maintained in a single place, directly in upstream `meson.build` files. |
| 164 |
|
| 165 |
Meson sets predefined tags on some files. More tags are likely to be added over |
| 166 |
time, please help extending the list of well known categories. |
| 167 |
- `devel`: |
| 168 |
* [[static_library]], |
| 169 |
* [[install_headers]], |
| 170 |
* `pkgconfig.generate()`, |
| 171 |
* `gnome.generate_gir()` - `.gir` file, |
| 172 |
* `gnome.generate_vapi()` - `.vapi` file (*Since 0.64.0*), |
| 173 |
* Files installed into `libdir` and with `.a` or `.pc` extension, |
| 174 |
* File installed into `includedir`, |
| 175 |
* Generated header files installed with `gnome.compile_resources()`, |
| 176 |
`gnome.genmarshal()`, `gnome.mkenums()`, `gnome.mkenums_simple()` |
| 177 |
and `gnome.gdbus_codegen()` (*Since 0.64.0*). |
| 178 |
- `runtime`: |
| 179 |
* [[executable]], |
| 180 |
* [[shared_library]], |
| 181 |
* [[shared_module]], |
| 182 |
* [[jar]], |
| 183 |
* `gnome.compile_resources()` - `.gresource` file (*Since 0.64.0*), |
| 184 |
* Files installed into `bindir`, |
| 185 |
* Files installed into `libdir` and with `.so` or `.dll` extension. |
| 186 |
- `python-runtime`: |
| 187 |
* `python.install_sources()`. |
| 188 |
- `man`: |
| 189 |
* [[install_man]]. |
| 190 |
- `doc`: |
| 191 |
* `gnome.gtkdoc()`, |
| 192 |
* `gnome.yelp()`, |
| 193 |
* `hotdoc.generate_doc()`. |
| 194 |
- `i18n`: |
| 195 |
* `i18n.gettext()`, |
| 196 |
* `qt.compile_translations()`, |
| 197 |
* Files installed into `localedir`. |
| 198 |
- `typelib`: |
| 199 |
* `gnome.generate_gir()` - `.typelib` file. |
| 200 |
- `bin`: |
| 201 |
* Scripts and executables bundled with a library meant to be used by end |
| 202 |
users. |
| 203 |
- `bin-devel`: |
| 204 |
* Scripts and executables bundled with a library meant to be used by |
| 205 |
developers (i.e. build tools). |
| 206 |
- `tests`: |
| 207 |
* Files installed into `installed-tests` subdir (*Since 0.64.0*). |
| 208 |
- `systemtap`: |
| 209 |
* Files installed into `systemtap` subdir (*Since 0.64.0*). |
| 210 |
|
| 211 |
Custom installation tag can be set using the `install_tag` keyword argument |
| 212 |
on various functions such as [[custom_target]], [[configure_file]], |
| 213 |
[[install_subdir]] and [[install_data]]. See their respective documentation |
| 214 |
in the reference manual for details. It is recommended to use one of the |
| 215 |
predefined tags above when possible. |
| 216 |
|
| 217 |
Installable files that have not been tagged either automatically by Meson, or |
| 218 |
manually using `install_tag` keyword argument won't be installed when `--tags` |
| 219 |
is used. They are reported at the end of `<builddir>/meson-logs/meson-log.txt`, |
| 220 |
it is recommended to add missing `install_tag` to have a tag on each installable |
| 221 |
files. |