From 58c2aeb5e433ae7652488d53021c40db1712dea5 Mon Sep 17 00:00:00 2001 From: John Ericson Date: Tue, 9 Jun 2020 20:38:46 -0400 Subject: [PATCH] [skip ci] docs: Bring up to date on options per machine I tried to fix the docs when the stuff was added, but it turns out I missed things, as noted in https://github.com/mesonbuild/meson/issues/7284#issuecomment-641641177 --- docs/markdown/Builtin-options.md | 41 +++++++++++++++++++++---------- docs/markdown/Reference-tables.md | 37 +++++++++++++++++++++++++++- 2 files changed, 64 insertions(+), 14 deletions(-) diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md index aa7d5001feb8..0fa127ab20fd 100644 --- a/docs/markdown/Builtin-options.md +++ b/docs/markdown/Builtin-options.md @@ -55,16 +55,9 @@ particularly the paths section may be necessary. ### Core options -Options that are labeled "per machine" in the table are set per machine. -Prefixing the option with `build.` just affects the build machine configuration, -while unprefixed just affects the host machine configuration, respectively. -Using the option as-is with no prefix affects all machines. For example: - - - `build.pkg_config_path` controls the paths pkg-config will search for just - `native: true` dependencies (build machine). - - - `pkg_config_path` controls the paths pkg-config will search for just - `native: false` dependencies (host machine). +Options that are labeled "per machine" in the table are set per machine. See +the [specifying options per machine](#Specifying-options-per-machine) section +for details. | Option | Default value | Description | Is per machine | | ------ | ------------- | ----------- | -------------- | @@ -186,9 +179,9 @@ The default values of `c_winlibs` and `cpp_winlibs` are in compiler-specific argument forms, but the libraries are: kernel32, user32, gdi32, winspool, shell32, ole32, oleaut32, uuid, comdlg32, advapi32. -c_args, cpp_args, c_link_args, and cpp_link_args only affect native builds, -when cross compiling they will not be applied to binaries or libraries -targeting the host system, only those being run on the build system. +All these `_*` options are specified per machine. See below in the +[specifying options per machine](#Specifying-options-per-machine) section on +how to do this in cross builds. When using MSVC, `cpp_eh=none` will result in no exception flags being passed, while the `cpp_eh=[value]` will result in `/EH[value]`. @@ -199,3 +192,25 @@ gcc-style compilers, nothing is passed (allowing exceptions to work), while Since *0.54.0* The `_thread_count` option can be used to control the value passed to `-s PTHREAD_POOL_SIZE` when using emcc. No other c/c++ compiler supports this option. + +## Specifying options per machine + +Since *0.51.0*, some options are specified per machine rather than globally for +all machine configurations. Prefixing the option with `build.` just affects the +build machine configuration, while unprefixed just affects the host machine +configuration, respectively. For example: + + - `build.pkg_config_path` controls the paths pkg-config will search for just + `native: true` dependencies (build machine). + + - `pkg_config_path` controls the paths pkg-config will search for just + `native: false` dependencies (host machine). + +This is useful for cross builds. In the native builds, build = host, and the +unprefixed option alone will suffice. + +Prior to *0.51.0*, these options just effected native builds when specified on +the command line, as there was no `build.` prefix. Similarly named fields in +the `[properties]` section of the cross file would effect cross compilers, but +the code paths were fairly different allowing differences in behavior to crop +out. diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md index 60a972084513..81ce9216c5c8 100644 --- a/docs/markdown/Reference-tables.md +++ b/docs/markdown/Reference-tables.md @@ -155,6 +155,10 @@ These are the parameter names for passing language specific arguments to your bu | Rust | rust_args | rust_link_args | | Vala | vala_args | vala_link_args | +All these `_*` options are specified per machine. See in [specifying +options per machine](Builtin-options.md#Specifying-options-per-machine) for on +how to do this in cross builds. + ## Compiler and linker flag environment variables These environment variables will be used to modify the compiler and @@ -177,6 +181,10 @@ instead. | RUSTFLAGS | Flags for the Rust compiler | | LDFLAGS | The linker flags, used for all languages | +N.B. these settings are specified per machine, and so the environment varibles +actually come in pairs. See the [environment variables per +machine](#Environment-variables-per-machine) section for details. + ## Function Attributes These are the parameters names that are supported using @@ -267,6 +275,10 @@ These are the values that can be passed to `dependency` function's ## Compiler and Linker selection variables +N.B. these settings are specified per machine, and so the environment varibles +actually come in pairs. See the [environment variables per +machine](#Environment-variables-per-machine) section for details. + | Language | Compiler | Linker | Note | |---------------|----------|-----------|---------------------------------------------| | C | CC | CC_LD | | @@ -280,5 +292,28 @@ These are the values that can be passed to `dependency` function's | C# | CSC | CSC | The linker is the compiler | *The old environment variales are still supported, but are deprecated and will -be removed in a future version of meson. +be removed in a future version of meson.* + +## Environment variables per machine + +Since *0.54.0*, Following Autotool and other legacy build systems, environment +variables that affect machine-specific settings come in pairs: for every bare +environment variable `FOO`, there is a suffixed `FOO_FOR_BUILD`, where `FOO` +just affects the host machine configuration, while `FOO_FOR_BUILD` just affects +the build machine configuration. For example: + + - `PKG_CONFIG_PATH_FOR_BUILD` controls the paths pkg-config will search for + just `native: true` dependencies (build machine). + + - `PKG_CONFIG_PATH` controls the paths pkg-config will search for just + `native: false` dependencies (host machine). + +This mirrors the `build.` prefix used for (built-in) meson options, which has +the same meaning. + +This is useful for cross builds. In the native builds, build = host, and the +unsuffixed environment variables alone will suffice. +Prior to *0.54.0*, there was no `_FOR_BUILD`-suffixed variables, and most +environment variables only effected native machine configurations, though this +wasn't consistent (e.g. `PKG_CONFIG_PATH` still affected cross builds).