diff options
Diffstat (limited to 'docs/markdown')
| -rw-r--r-- | docs/markdown/Adding-new-projects-to-wrapdb.md | 5 | ||||
| -rw-r--r-- | docs/markdown/Compiler-properties.md | 21 | ||||
| -rw-r--r-- | docs/markdown/FAQ.md | 43 | ||||
| -rw-r--r-- | docs/markdown/Gnome-module.md | 16 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 20 | ||||
| -rw-r--r-- | docs/markdown/Reference-tables.md | 3 | ||||
| -rw-r--r-- | docs/markdown/Release-notes-for-0.45.0.md | 26 | ||||
| -rw-r--r-- | docs/markdown/Syntax.md | 20 | ||||
| -rw-r--r-- | docs/markdown/Unit-tests.md | 8 | ||||
| -rw-r--r-- | docs/markdown/snippets/armcc-cross.md | 15 | ||||
| -rw-r--r-- | docs/markdown/snippets/del-old-names.md | 2 | ||||
| -rw-r--r-- | docs/markdown/snippets/find-override.md | 37 | ||||
| -rw-r--r-- | docs/markdown/snippets/lcc.md | 23 | ||||
| -rw-r--r-- | docs/markdown/snippets/more-escape-sequences.md | 17 | ||||
| -rw-r--r-- | docs/markdown/snippets/new-wrap-mode.md | 3 | ||||
| -rw-r--r-- | docs/markdown/snippets/non-unique-target-names.md | 9 | ||||
| -rw-r--r-- | docs/markdown/snippets/openmp-dependency.md | 6 | ||||
| -rw-r--r-- | docs/markdown/snippets/pkg-config-fix-static-only.md | 12 |
18 files changed, 264 insertions, 22 deletions
diff --git a/docs/markdown/Adding-new-projects-to-wrapdb.md b/docs/markdown/Adding-new-projects-to-wrapdb.md index 4420de553..58b27bad3 100644 --- a/docs/markdown/Adding-new-projects-to-wrapdb.md +++ b/docs/markdown/Adding-new-projects-to-wrapdb.md @@ -37,11 +37,10 @@ Each project gets its own repo. It is initialized like this: git init git add readme.txt - git commit -a -m 'Start of project foobar.' - git tag commit_zero -a -m 'A tag that helps get revision ids for releases.' + git add LICENSE.build + git commit -a -m 'Create project foobar' git remote add origin <repo url> git push -u origin master - git push --tags Note that this is the *only* commit that will ever be made to master branch. All other commits are done to branches. diff --git a/docs/markdown/Compiler-properties.md b/docs/markdown/Compiler-properties.md index 579417a79..1228f42dd 100644 --- a/docs/markdown/Compiler-properties.md +++ b/docs/markdown/Compiler-properties.md @@ -160,15 +160,30 @@ Does a function exist? Just having a header doesn't say anything about its contents. Sometimes you need to explicitly check if some function -exists. This is how we would check whether the function `somefunc` -exists in header `someheader.h` +exists. This is how we would check whether the function `open_memstream` +exists in header `stdio.h` ```meson -if compiler.has_function('somefunc', prefix : '#include<someheader.h>') +if compiler.has_function('open_memstream', prefix : '#include <stdio.h>') # function exists, do whatever is required. endif ``` +Note that, on macOS programs can be compiled targeting older macOS +versions than the one that the program is compiled on. It can't be +assumed that the OS version that is compiled on matches the OS +version that the binary will run on. + +Therefore when detecting function availability with `has_function`, it +is important to specify the correct header in the prefix argument. + +In the example above, the function `open_memstream` is detected, which +was introduced in macOS 10.13. When the user builds on macOS 10.13, but +targeting macOS 10.11 (`-mmacosx-version-min=10.11`), this will correctly +report the function as missing. Without the header however, it would lack +the necessary availability information and incorrectly report the function +as available. + Does a structure contain a member? == diff --git a/docs/markdown/FAQ.md b/docs/markdown/FAQ.md index f4cf89bec..ff9321612 100644 --- a/docs/markdown/FAQ.md +++ b/docs/markdown/FAQ.md @@ -288,3 +288,46 @@ has a option called `wrap-mode` which can be used to disable wrap downloads altogether with `--wrap-mode=nodownload`. You can also disable dependency fallbacks altogether with `--wrap-mode=nofallback`, which also implies the `nodownload` option. + +If on the other hand, you want meson to always use the fallback +for dependencies, even when an external dependency exists and could +satisfy the version requirements, for example in order to make +sure your project builds when fallbacks are used, you can use +`--wrap-mode=forcefallback` since 0.46.0. + +## Why is Meson implemented in Python rather than [programming language X]? + +Because build systems are special in ways normal applications aren't. + +Perhaps the biggest limitation is that because Meson is used to build +software at the very lowest levels of the OS, it is part of the core +bootstrap for new systems. Whenever support for a new CPU architecture +is added, Meson must run on the system before software using it can be +compiled natively. This requirement adds two hard limitations. + +The first one is that Meson must have the minimal amount of +dependencies, because they must all be built during the bootstrap to +get Meson to work. + +The second is that Meson must support all CPU architectures, both +existing and future ones. As an example many new programming languages +have only an LLVM based compiler available. LLVM has limited CPU +support compared to, say, GCC, and thus bootstrapping Meson on such +platforms would first require adding new processor support to +LLVM. This is in most cases unfeasible. + +A further limitation is that we want developers on as many platforms +as possible to submit to Meson development using the default tools +provided by their operating system. In practice what this means is +that Windows developers should be able to contribute using nothing but +Visual Studio. + +At the time of writing (April 2018) there are only three languages +that could fullfill these requirements: + + - C + - C++ + - Python + +Out of these we have chosen Python because it is the best fit for our +needs. diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md index ad3715eba..3db6cc035 100644 --- a/docs/markdown/Gnome-module.md +++ b/docs/markdown/Gnome-module.md @@ -235,9 +235,21 @@ files and the second specifies the XML file name. * `object_manager`: *(Added 0.40.0)* if true generates object manager code * `annotations`: *(Added 0.43.0)* list of lists of 3 strings for the annotation for `'ELEMENT', 'KEY', 'VALUE'` * `docbook`: *(Added 0.43.0)* prefix to generate `'PREFIX'-NAME.xml` docbooks +* `build_by_default`: causes, when set to true, to have this target be + built by default, that is, when invoking plain `ninja`, the default + value is true for all built target types +* `install_dir`: (*Added 0.46.0*) location to install the header or + bundle depending on previous options +* `install_header`: (*Added 0.46.0*) if true, install the header file + +Starting *0.46.0*, this function returns a list of at least two custom targets +(in order): one for the source code and one for the header. The list will +contain a third custom target for the generated docbook files if that keyword +argument is passed. -Returns an opaque object containing the source files. Add it to a top -level target's source list. +Earlier versions return a single custom target representing all the outputs. +Generally, you should just add this list of targets to a top level target's +source list. Example: diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index d98fc1989..fad6a3cfa 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -186,7 +186,12 @@ These are all the supported keyword arguments: `output`. Available since v0.41.0. - `command` as explained above, if specified, Meson does not create the file itself but rather runs the specified command, which allows - you to do fully custom file generation + you to do fully custom file generation. +- `format` *(added 0.46.0)* the format of defines. It defaults to `meson`, and so substitutes +`#mesondefine` statements and variables surrounded by `@` characters, you can also use `cmake` +to replace `#cmakedefine` statements and variables with the `${variable}` syntax. Finally you can use +`cmake@` in which case substitutions will apply on `#cmakedefine` statements and variables with +the `@variable@` syntax. - `input` the input file name. If it's not specified in configuration mode, all the variables in the `configuration:` object (see above) are written to the `output:` file. @@ -1238,6 +1243,12 @@ Keyword arguments are the following: - `should_fail` when true the test is considered passed if the executable returns a non-zero return value (i.e. reports an error) +- `suite` `'label'` (or list of labels `['label1', 'label2']`) + attached to this test. The suite name is qualified by a (sub)project + name resulting in `(sub)project_name:label`. In the case of a list + of strings, the suite names will be `(sub)project_name:label1`, + `(sub)project_name:label2`, etc. + - `timeout` the amount of seconds the test is allowed to run, a test that exceeds its time limit is always considered failed, defaults to 30 seconds @@ -1385,6 +1396,13 @@ the following methods. /path/to/meson.py introspect`. The user is responsible for splitting the string to an array if needed. +- `override_find_program(progname, program)` [*(Added + 0.46.0)*](Release-notes-for-0-46-0.html#Can-override-find_program) + specifies that whenever `find_program` is used to find a program + named `progname`, Meson should not not look it up on the system but + instead return `program`, which may either be the result of + `find_program` or `configure_file`. + - `project_version()` returns the version string specified in `project` function call. - `project_license()` returns the array of licenses specified in `project` function call. diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md index 7611232d1..2157e7288 100644 --- a/docs/markdown/Reference-tables.md +++ b/docs/markdown/Reference-tables.md @@ -21,6 +21,8 @@ These are return values of the `get_id` method in a compiler object. | g95 | The G95 Fortran compiler | | open64 | The Open64 Fortran Compiler | | nagfor | The NAG Fortran compiler | +| lcc | Elbrus C/C++/Fortran Compiler | +| arm | ARM compiler | ## Script environment variables @@ -42,6 +44,7 @@ set in the cross file. | x86 | 32 bit x86 processor | | x86_64 | 64 bit x86 processor | | arm | 32 bit ARM processor | +| e2k | MCST Elbrus processor | Any cpu family not listed in the above list is not guaranteed to remain stable in future releases. diff --git a/docs/markdown/Release-notes-for-0.45.0.md b/docs/markdown/Release-notes-for-0.45.0.md index 6b24183a7..19d65b890 100644 --- a/docs/markdown/Release-notes-for-0.45.0.md +++ b/docs/markdown/Release-notes-for-0.45.0.md @@ -18,7 +18,7 @@ ldflags, etc) from. These binaries may now be specified in the `binaries` section of a cross file. -```dosini +```ini [binaries] cc = ... llvm-config = '/usr/bin/llvm-config32' @@ -37,12 +37,16 @@ time. Starting with this version it becomes a hard error. There used to be a keywordless version of `run_target` which looked like this: - run_target('targetname', 'command', 'arg1', 'arg2') +```meson +run_target('targetname', 'command', 'arg1', 'arg2') +``` This is now an error. The correct format for this is now: - run_target('targetname', - command : ['command', 'arg1', 'arg2']) +```meson +run_target('targetname', + command : ['command', 'arg1', 'arg2']) +``` ## Experimental FPGA support @@ -84,7 +88,9 @@ private directory: Hexadecimal integer literals can now be used in build and option files. - int_255 = 0xFF +```meson +int_255 = 0xFF +``` ## b_ndebug : if-release @@ -110,7 +116,9 @@ instead of directory itself, stripping basename of the source directory. There is a new integer option type with optional minimum and maximum values. It can be specified like this in the `meson_options.txt` file: - option('integer_option', type : 'integer', min : 0, max : 5, value : 3) +```meson +option('integer_option', type : 'integer', min : 0, max : 5, value : 3) +``` ## New method meson.project_license() @@ -124,7 +132,7 @@ cross-compilers, the Rust binary must be specified in your cross file. It should specify a `--target` (as installed by `rustup target`) and a custom linker pointing to your C cross-compiler. For example: -``` +```ini [binaries] c = '/usr/bin/arm-linux-gnueabihf-gcc-7' rust = [ @@ -146,9 +154,7 @@ private sysroot. Meson ships with predefined project templates. To start a new project from scratch, simply go to an empty directory and type: -```meson -meson init --name=myproject --type=executable --language=c -``` + meson init --name=myproject --type=executable --language=c ## Improve test setup selection diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index 1005100fe..01c8c6e95 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -90,8 +90,24 @@ single quote do it like this: single quote = 'contains a \' character' ``` -Similarly `\n` gets converted to a newline and `\\` to a single -backslash. +The full list of escape sequences is: + +* `\\` Backslash +* `\'` Single quote +* `\a` Bell +* `\b` Backspace +* `\f` Formfeed +* `\n` Newline +* `\r` Carriage Return +* `\t` Horizontal Tab +* `\v` Vertical Tab +* `\ooo` Character with octal value ooo +* `\xhh` Character with hex value hh +* `\uxxxx` Character with 16-bit hex value xxxx +* `\Uxxxxxxxx` Character with 32-bit hex value xxxxxxxx +* `\N{name}` Character named name in Unicode database + +As in python and C, up to three octal digits are accepted in `\ooo`. #### String concatenation diff --git a/docs/markdown/Unit-tests.md b/docs/markdown/Unit-tests.md index 53ce9ec57..e5e4107f4 100644 --- a/docs/markdown/Unit-tests.md +++ b/docs/markdown/Unit-tests.md @@ -71,6 +71,14 @@ You can also run only a single test by giving its name: $ meson test testname ``` +Tests belonging to a suite `suite` can be run as follows + +```console +$ meson test --suite (sub)project_name:suite +``` + +Since version *0.46*, `(sub)project_name` can be omitted if it is the top-level project. + Sometimes you need to run the tests multiple times, which is done like this: ```console diff --git a/docs/markdown/snippets/armcc-cross.md b/docs/markdown/snippets/armcc-cross.md new file mode 100644 index 000000000..668f0ab98 --- /dev/null +++ b/docs/markdown/snippets/armcc-cross.md @@ -0,0 +1,15 @@ +## ARM compiler for C and CPP + +Cross-compilation is now supported for ARM targets using ARM compiler - ARMCC. +The current implementation does not support shareable libraries. +The default extension of the output is .axf. +The environment path should be set properly for the ARM compiler executables. +The '--cpu' option with the appropriate target type should be mentioned +in the cross file as shown in the snippet below. + +``` +[properties] +c_args = ['--cpu=Cortex-M0plus'] +cpp_args = ['--cpu=Cortex-M0plus'] + +``` diff --git a/docs/markdown/snippets/del-old-names.md b/docs/markdown/snippets/del-old-names.md index c4abc9ad0..5ac5873c2 100644 --- a/docs/markdown/snippets/del-old-names.md +++ b/docs/markdown/snippets/del-old-names.md @@ -2,6 +2,6 @@ Old executable names `mesonintrospect`, `mesonconf`, `mesonrewriter` and `mesontest` have been deprecated for a long time. Starting from -this versino they no longer do anything but instead always error +this version they no longer do anything but instead always error out. All functionality is available as subcommands in the main `meson` binary. diff --git a/docs/markdown/snippets/find-override.md b/docs/markdown/snippets/find-override.md new file mode 100644 index 000000000..ef3a4a2fd --- /dev/null +++ b/docs/markdown/snippets/find-override.md @@ -0,0 +1,37 @@ +## Can override find_program + +It is now possible to override the result of `find_program` to point +to a custom program you want. The overriding is global and applies to +every subproject from there on. Here is how you would use it. + +In master project + +```meson +subproject('mydep') +``` + +In the called subproject: + +```meson +prog = find_program('my_custom_script') +meson.override_find_program('mycodegen', prog) +``` + +In master project (or, in fact, any subproject): + +```meson +genprog = find_program('mycodegen') +``` + +Now `genprog` points to the custom script. If the dependency had come +from the system, then it would point to the system version. + +You can also use the return value of `configure_file()` to override +a program in the same way as above: + +```meson +prog_script = configure_file(input : 'script.sh.in', + output : 'script.sh', + configuration : cdata) +meson.override_find_program('mycodegen', prog_script) +``` diff --git a/docs/markdown/snippets/lcc.md b/docs/markdown/snippets/lcc.md new file mode 100644 index 000000000..2ce300daa --- /dev/null +++ b/docs/markdown/snippets/lcc.md @@ -0,0 +1,23 @@ +## Support for lcc compiler for e2k (Elbrus) architecture + +In this version, a support for lcc compiler for Elbrus processors +based on [e2k microarchitecture](https://en.wikipedia.org/wiki/Elbrus_2000) +has been added. + +Examples of such CPUs: +* [Elbrus-8S](https://en.wikipedia.org/wiki/Elbrus-8S); +* Elbrus-4S; +* [Elbrus-2S+](https://en.wikipedia.org/wiki/Elbrus-2S%2B). + +Such compiler have a similar behavior as gcc (basic option compatibility), +but, in is not strictly compatible with gcc as of current version. + +Major differences as of version 1.21.22: +* it does not support LTO and PCH; +* it suffers from the same dependency file creation error as icc; +* it has minor differences in output, especially version output; +* it differently reacts to lchmod() detection; +* some backend messages are produced in ru_RU.KOI8-R even if LANG=C; +* its preprocessor treats some characters differently. + +So every noted difference is properly handled now in meson.
\ No newline at end of file diff --git a/docs/markdown/snippets/more-escape-sequences.md b/docs/markdown/snippets/more-escape-sequences.md new file mode 100644 index 000000000..2894079d9 --- /dev/null +++ b/docs/markdown/snippets/more-escape-sequences.md @@ -0,0 +1,17 @@ +## String escape character update + +The strings (both single-quoted and triple-quoted) in meson has been taught the +same set of escape sequences as in Python. It is therefore now possible to use +arbitrary bytes in strings, like for example NUL (`\0`) and other ASCII control +characters. See the chapter about *Strings* in *Syntax* for more details. + +Potential backwards compatibility issue: Any valid escape sequence according to +the new rules will be interpreted as an escape sequence instead of the literal +characters. Previously only single-quote strings supported escape sequences and +the supported sequences were `\'`, `\\` and `\n`. + +The most likely breakage is usage of backslash-n in triple-quoted strings. It +is now written in the same way as in single-quoted strings: `\\n` instead of +`\n`. In general it is now recommended to escape any usage of backslash. +However, backslash-c (`\c`), for example, is still backslash-c because it isn't +a valid escape sequence. diff --git a/docs/markdown/snippets/new-wrap-mode.md b/docs/markdown/snippets/new-wrap-mode.md new file mode 100644 index 000000000..e33dd83e6 --- /dev/null +++ b/docs/markdown/snippets/new-wrap-mode.md @@ -0,0 +1,3 @@ +A new wrap mode was added, `--wrap-mode=forcefallback`. When this is set, +dependencies for which a fallback was provided will always use it, even +if an external dependency exists and satisfies the version requirements. diff --git a/docs/markdown/snippets/non-unique-target-names.md b/docs/markdown/snippets/non-unique-target-names.md new file mode 100644 index 000000000..9b3f9173c --- /dev/null +++ b/docs/markdown/snippets/non-unique-target-names.md @@ -0,0 +1,9 @@ +## Relaxing of target name requirements + +In earlier versions of Meson you could only have one target of a given name for each type. +For example you could not have two executables named `foo`. This requirement is now +relaxed so that you can have multiple targets with the same name, as long as they are in +different subdirectories. + +Note that projects that have multiple targets with the same name can not be built with +the `flat` layout or any backend that writes outputs in the same directory. diff --git a/docs/markdown/snippets/openmp-dependency.md b/docs/markdown/snippets/openmp-dependency.md new file mode 100644 index 000000000..ad7001186 --- /dev/null +++ b/docs/markdown/snippets/openmp-dependency.md @@ -0,0 +1,6 @@ +## Addition of OpenMP dependency + +An OpenMP dependency (`openmp`) has been added that encapsulates the various +flags used by compilers to enable OpenMP and checks for the existence of the +`omp.h` header. The `language` keyword may be passed to force the use of a +specific compiler for the checks. diff --git a/docs/markdown/snippets/pkg-config-fix-static-only.md b/docs/markdown/snippets/pkg-config-fix-static-only.md new file mode 100644 index 000000000..31cd38940 --- /dev/null +++ b/docs/markdown/snippets/pkg-config-fix-static-only.md @@ -0,0 +1,12 @@ +## Improved generation of pkg-config files for static only libraries. + +Previously pkg-config files generated by the pkgconfig modules for static libraries +with dependencies could only be used in a dependencies with `static: true`. + +Now the generated file contains the needed dependencies libraries directly within +`Requires` and `Libs` for build static libraries passed via the `libraries` keyword +argument. + +Projects that install both a static and a shared version of a library should use +the result of `both_libraries` to the pkg config file generator or use +configure_file for more complicated setups. |