From 7a159ff1e1e947f20a017bbc8e89c1701a9d7098 Mon Sep 17 00:00:00 2001 From: Jon Turney Date: Wed, 8 May 2019 17:22:56 +0100 Subject: Add add_languages(native:) v2: Retain not using logical-and, to avoid short-circuiting side-effects of add_languages() --- docs/markdown/Reference-manual.md | 24 ++++++++++++++-------- .../snippets/native_compiler_not_required.md | 5 +++++ 2 files changed, 20 insertions(+), 9 deletions(-) create mode 100644 docs/markdown/snippets/native_compiler_not_required.md (limited to 'docs/markdown') diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 510d443..3b07b5f 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -54,9 +54,9 @@ Like `add_global_arguments` but the arguments are passed to the linker. bool add_languages(*langs*) ``` -Add support for new programming languages. Equivalent to having them -in the `project` declaration. This function is usually used to add -languages that are only used on some platforms like this: +Add programming languages used by the project. Equivalent to having them in the +`project` declaration. This function is usually used to add languages that are +only used under some conditions, like this: ```meson project('foobar', 'c') @@ -68,12 +68,18 @@ if add_languages('cpp', required : false) endif ``` -Takes one keyword argument, `required`. It defaults to `true`, which -means that if any of the languages specified is not found, Meson will -halt. Returns true if all languages specified were found and false -otherwise. Since *0.47.0* the value of a -[`feature`](Build-options.md#features) option can also be passed to -the `required` keyword argument. +Takes the following keyword arguments: + +- `required` defaults to `true`, which means that if any of the languages +specified is not found, Meson will halt. Since *0.47.0* the value of a +[`feature`](Build-options.md#features) option can also be passed. + +- `native` if set to `true`, the language will be used to compile for the build + machine, if `false`, for the host machine. If omitted, the language may be + used for either. Since *0.54.0*. The default may change to `false` in a future + meson version. + +Returns `true` if all languages specified were found and `false` otherwise. ### add_project_arguments() diff --git a/docs/markdown/snippets/native_compiler_not_required.md b/docs/markdown/snippets/native_compiler_not_required.md new file mode 100644 index 0000000..0847b2b --- /dev/null +++ b/docs/markdown/snippets/native_compiler_not_required.md @@ -0,0 +1,5 @@ +## Native (build machine) compilers not always required + +`add_languages()` gained a `native:` keyword, indicating if a native or cross +compiler is to be used. Currently, for backwards compatibility, if the keyword +is absent, that means both are used. -- cgit v1.1 From c5a32c2afe843798d714fc9087bf55ad996b4052 Mon Sep 17 00:00:00 2001 From: Jon Turney Date: Sat, 8 Feb 2020 18:33:49 +0000 Subject: Refine behaviour of add_languages() when native: is missing This improves the common case of a simple meson.build which doesn't contain any 'native: true' targets to not require a native compiler when cross-compiling, without needing any changes in the meson.build. v2: Do it the right way around! --- docs/markdown/Reference-manual.md | 10 +++++++--- .../markdown/snippets/native_compiler_not_required.md | 19 +++++++++++++++++-- 2 files changed, 24 insertions(+), 5 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 3b07b5f..3e4cd44 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -75,12 +75,16 @@ specified is not found, Meson will halt. Since *0.47.0* the value of a [`feature`](Build-options.md#features) option can also be passed. - `native` if set to `true`, the language will be used to compile for the build - machine, if `false`, for the host machine. If omitted, the language may be - used for either. Since *0.54.0*. The default may change to `false` in a future - meson version. + machine, if `false`, for the host machine. Since *0.54.0*. Returns `true` if all languages specified were found and `false` otherwise. +If `native` is omitted, the languages may be used for either build or host +machine, but are never required for the build machine. (i.e. it is equivalent +to `add_languages(*langs*, native: false, required: *required*) and +add_languages(*langs*, native: true, required: false)`. This default behaviour +may change to `native: false` in a future meson version. + ### add_project_arguments() ``` meson diff --git a/docs/markdown/snippets/native_compiler_not_required.md b/docs/markdown/snippets/native_compiler_not_required.md index 0847b2b..331b3c7 100644 --- a/docs/markdown/snippets/native_compiler_not_required.md +++ b/docs/markdown/snippets/native_compiler_not_required.md @@ -1,5 +1,20 @@ ## Native (build machine) compilers not always required `add_languages()` gained a `native:` keyword, indicating if a native or cross -compiler is to be used. Currently, for backwards compatibility, if the keyword -is absent, that means both are used. +compiler is to be used. + +For the benefit of existing simple build definitions which don't contain any +`native: true` targets, without breaking backwards compatibility for build +definitions which assume that the native compiler is available after +`add_languages()`, if the `native:` keyword is absent the languages may be used +for either the build or host machine, but are never required for the build +machine. + +This changes the behaviour of the following meson fragment (when cross-compiling +but a native compiler is not available) from reporting an error at +`add_language` to reporting an error at `executable`. + +``` +add_language('c') +executable('main', 'main.c', native: true) +``` -- cgit v1.1