diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Contributing.md | 39 | ||||
| -rw-r--r-- | docs/markdown/Cross-compilation.md | 41 | ||||
| -rw-r--r-- | docs/markdown/FAQ.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Installing.md | 13 | ||||
| -rw-r--r-- | docs/markdown/Pkg-config-files.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Pkgconfig-module.md | 7 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 56 | ||||
| -rw-r--r-- | docs/markdown/Release-notes-for-0.46.0.md | 7 | ||||
| -rw-r--r-- | docs/markdown/Users.md | 3 | ||||
| -rw-r--r-- | docs/markdown/howtox.md | 4 | ||||
| -rw-r--r-- | docs/markdown/snippets/install_data-rename.md | 11 | ||||
| -rw-r--r-- | docs/markdown/snippets/pkgconfig-generator.md | 14 |
12 files changed, 177 insertions, 22 deletions
diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md index 8e9847a..7b5fe73 100644 --- a/docs/markdown/Contributing.md +++ b/docs/markdown/Contributing.md @@ -18,6 +18,45 @@ Github](https://github.com/mesonbuild/meson/pulls). This causes them to be run through the CI system. All submissions must pass a full CI test run before they are even considered for submission. +## Acceptance and merging + +The kind of review and acceptance any merge proposal gets depends on +the changes it contains. All pull requests must be reviewed and +accepted by someone with commit rights who is not the original +submitter. Merge requests can be roughly split into three different +categories. + +The first one consists of MRs that only change the markdown +documentation under `docs/markdown`. Anyone with access rights can +push changes to these directly to master. For major changes it is +still recommended to create a MR so other people can comment on it. + +The second group consists of merges that don't change any +functionality, fixes to the CI system and bug fixes that have added +regression tests (see below) and don't change existing +functionality. Once successfully reviewed anyone with merge rights can +merge these to master. + +The final kind of merges are those that add new functionality or +change existing functionality in a backwards incompatible way. These +require the approval of the project lead. + +In a simplified list form the split would look like the following: + + - members with commit access can do: + - documentation changes (directly to master if warranted) + - bug fixes that don't change functionality + - refactorings + - new dependency types + - new tool support (e.g. a new Doxygen-kind of tool) + - support for new compilers to existing languages + - project leader decision is needed for: + - new modules + - new functions in the Meson language + - syntax changes for Meson files + - changes breaking backwards compatibility + - support for new languages + ## Tests All new features must come with automatic tests that thoroughly prove diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md index 520a081..7d316ed 100644 --- a/docs/markdown/Cross-compilation.md +++ b/docs/markdown/Cross-compilation.md @@ -10,17 +10,23 @@ nomenclature. The three most important definitions are traditionally called *build*, *host* and *target*. This is confusing because those terms are used for quite many different things. To simplify the issue, we are going to call these the *build machine*, *host machine* and -*target machine*. Their definitions are the following +*target machine*. Their definitions are the following: -* *build machine* is the computer that is doing the actual compiling -* *host machine* is the machine on which the compiled binary will run -* *target machine* is the machine on which the compiled binary's output will run (this is only meaningful for programs such as compilers that, when run, produce object code for a different CPU than what the program is being run on) +* *build machine* is the computer that is doing the actual compiling. +* *host machine* is the machine on which the compiled binary will run. +* *target machine* is the machine on which the compiled binary's + output will run, *only meaningful* if the program produces + machine-specific output. The `tl/dr` summary is the following: if you are doing regular cross -compilation, you only care about *build_machine* and -*host_machine*. Just ignore *target_machine* altogether and you will -be correct 99% of the time. If your needs are more complex or you are -interested in the actual details, do read on. +compilation, you only care about `build_machine` and +`host_machine`. Just ignore `target_machine` altogether and you will +be correct 99% of the time. Only compilers and similar tools care +about the target machine. In fact, for so-called "multi-target" tools +the target machine need not be fixed at build-time like the others but +chosen at runtime, so `target_machine` *still* doesn't matter. If your +needs are more complex or you are interested in the actual details, do +read on. This might be easier to understand through examples. Let's start with the regular, not cross-compiling case. In these cases all of these @@ -50,6 +56,20 @@ Wikipedia or the net in general. It is very common for them to get build, host and target mixed up, even in consecutive sentences, which can leave you puzzled until you figure it out. +A lot of confusion stems from the fact that when you cross-compile +something, the 3 systems (*build*, *host*, and *target*) used when +building the cross compiler don't align with the ones used when +building something with that newly-built cross compiler. To take our +Canadian Cross scenario from above (for full generality), since its +*host machine* is x86 Windows, the *build machine* of anything we +build with it is *x86 Windows*. And since its *target machine* is MIPS +Linux, the *host machine* of anything we build with it is *MIPS +Linux*. Only the *target machine* of whatever we build with it can be +freely chosen by us, say if we want to build another cross compiler +that runs on MIPS Linux and targets Aarch64 iOS. As this example +hopefully makes clear to you, the platforms are shifted over to the +left by one position. + If you did not understand all of the details, don't worry. For most people it takes a while to wrap their head around these concepts. Don't panic, it might take a while to click, but you will @@ -82,8 +102,9 @@ of a wrapper, these lines are all you need to write. Meson will automatically use the given wrapper when it needs to run host binaries. This happens e.g. when running the project's test suite. -The next section lists properties of the cross compiler and thus of -the target system. It looks like this: +The next section lists properties of the cross compiler and its target +system, and thus properties of host system of what we're building. It +looks like this: ```ini [properties] diff --git a/docs/markdown/FAQ.md b/docs/markdown/FAQ.md index 1dbc80a..f4cf89b 100644 --- a/docs/markdown/FAQ.md +++ b/docs/markdown/FAQ.md @@ -263,7 +263,7 @@ changed the value and from which value to which other value. Since people don't remember their own actions that far back, toggling between states based on long history would be confusing. -Because of this we do the simple an understandable thing: default +Because of this we do the simple and understandable thing: default values are only defaults and will never affect the value of an option once set. diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md index 4670544..b8e6a81 100644 --- a/docs/markdown/Installing.md +++ b/docs/markdown/Installing.md @@ -29,6 +29,19 @@ install_man('foo.1') # -> share/man/man1/foo.1.gz install_data('datafile.dat', install_dir : join_paths(get_option('datadir'), 'progname')) # -> share/progname/datafile.dat ``` +`install_data()` supports rename of the file *since 0.46.0*. + +```meson +# file.txt -> {datadir}/{projectname}/new-name.txt +install_data('file.txt', rename : 'new-name.txt') + +# file1.txt -> share/myapp/dir1/data.txt +# file2.txt -> share/myapp/dir2/data.txt +install_data(['file1.txt', 'file2.txt'], + rename : ['dir1/data.txt', 'dir2/data.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. ```meson diff --git a/docs/markdown/Pkg-config-files.md b/docs/markdown/Pkg-config-files.md index dde4ac9..ddb8bab 100644 --- a/docs/markdown/Pkg-config-files.md +++ b/docs/markdown/Pkg-config-files.md @@ -1,6 +1,6 @@ # Pkg config files -[Pkg-config](https://en.wikipedia.org/wiki/Pkg-config) is a way for shared libraries to declare the compiler flags needed to use them. There are two different ways of generating Pkg-config files in Meson. The first way is to build them manually with the `configure_files` command. The second way is to use Meson's built in Pkg-config file generator. The difference between the two is that the latter is very simple and meant for basic use cases. The former should be used when you need to provide a more customized solution. +[Pkg-config](https://en.wikipedia.org/wiki/Pkg-config) is a way for shared libraries to declare the compiler flags needed to use them. There are two different ways of generating Pkg-config files in Meson. The first way is to build them manually with the `configure_file` command. The second way is to use Meson's built in Pkg-config file generator. The difference between the two is that the latter is very simple and meant for basic use cases. The former should be used when you need to provide a more customized solution. In this document we describe the simple generator approach. It is used in the following way. diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md index 853cf50..77db809 100644 --- a/docs/markdown/Pkgconfig-module.md +++ b/docs/markdown/Pkgconfig-module.md @@ -51,3 +51,10 @@ keyword arguments. - `version` a string describing the version of this library - `d_module_versions` a list of module version flags used when compiling D sources referred to by this pkg-config file + +Since 0.46 a `StaticLibrary` or `SharedLibrary` object can optionally be passed +as first positional argument. If one is provided a default value will be +provided for all required fields of the pc file: +- `install_dir` is set to `pkgconfig` folder in the same location than the provided library. +- `description` is set to the project's name followed by the library's name. +- `name` is set to the library's name. diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 589baf1..5109b25 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -173,7 +173,8 @@ These are all the supported keyword arguments: mode, all the variables in the `configuration:` object (see above) are written to the `output:` file. - `install_dir` the subdirectory to install the generated file to - (e.g. `share/myproject`), if omitted the file is not installed. + (e.g. `share/myproject`), if omitted or given the value of empty + string, the file is not installed. - `output` the output file name (since v0.41.0, may contain `@PLAINNAME@` or `@BASENAME@` substitutions). In configuration mode, the permissions of the input file (if it is specified) are copied to @@ -368,9 +369,8 @@ can be of the following types: These input files can be sources, objects, libraries, or any other file. Meson will automatically categorize them based on the extension and use them accordingly. For instance, sources (`.c`, `.cpp`, -`.vala`, `.rs`, etc) will be compiled, objects (`.o`, `.obj`) and -libraries (`.so`, `.dll`, etc) will be linked, and all other files -(headers, unknown extensions, etc) will be ignored. +`.vala`, `.rs`, etc) will be compiled and objects (`.o`, `.obj`) and +libraries (`.so`, `.dll`, etc) will be linked. With the Ninja backend, Meson will create a build-time [order-only dependency](https://ninja-build.org/manual.html#ref_dependencies) on @@ -737,6 +737,13 @@ arguments. The following keyword arguments are supported: To leave any of these three as the default, specify `false`. +- `rename` if specified renames each source file into corresponding file + from `rename` list. Nested paths are allowed and they are joined with + `install_dir`. Length of `rename` list must be equal to the number of sources. + *(added 0.46.0)* + +See [Installing](Installing.md) for more examples. + ### install_headers() ``` meson @@ -1122,6 +1129,33 @@ This function has one keyword argument. recurse in the subdir if they all return `true` when queried with `.found()` +### subdir_done() + +``` meson + subdir_done() +``` + +Stops further interpretation of the meson script file from the point of +the invocation. All steps executed up to this point are valid and will +be executed by meson. This means that all targets defined before the call +of `subdir_done` will be build. + +If the current script was called by `subdir` the execution returns to the +calling directory and continues as if the script had reached the end. +If the current script is the top level script meson configures the project +as defined up to this point. + +Example: +```meson +project('example exit', 'cpp') +executable('exe1', 'exe1.cpp') +subdir_done() +executable('exe2', 'exe2.cpp') +``` + +The executable `exe1` will be build, while the executable `exe2` is not +build. + ### subproject() ``` meson @@ -1159,9 +1193,17 @@ argument to [`dependency()`](#dependency). void test(name, executable, ...) ``` -Defines a unit test. Takes two positional arguments, the first is the -name of this test and the second is the executable to run. Keyword -arguments are the following. +Defines a test to run with the test harness. Takes two positional arguments, +the first is the name of the test and the second is the executable to run. +The executable can be an [executable build target object](#build-target-object) +returned by [`executable()`](#executable) or an +[external program object](#external-program-object) returned by +[`find_program()`](#find_program). The executable's exit code is used by the +test harness to record the outcome of the test, for example exit code zero +indicates success. For more on the Meson test harness protocol read +[Unit Tests](Unit-tests.md). + +Keyword arguments are the following: - `args` arguments to pass to the executable diff --git a/docs/markdown/Release-notes-for-0.46.0.md b/docs/markdown/Release-notes-for-0.46.0.md index 395a94d..e062459 100644 --- a/docs/markdown/Release-notes-for-0.46.0.md +++ b/docs/markdown/Release-notes-for-0.46.0.md @@ -14,3 +14,10 @@ whose contents should look like this: ## Feature name A short description explaining the new feature and how it should be used. + +## Allow early return from a script + +Added the function `subdir_done()`. Its invocation exits the current script at +the point of invocation. All previously invoked build targets and commands are +build/executed. All following ones are ignored. If the current script was +invoked via `subdir()` the parent script continues normally. diff --git a/docs/markdown/Users.md b/docs/markdown/Users.md index e152555..558378c 100644 --- a/docs/markdown/Users.md +++ b/docs/markdown/Users.md @@ -4,7 +4,8 @@ title: Users # List of projects using Meson -If you have a project that uses Meson that you want to add to this list, please [file a pull-request](https://github.com/mesonbuild/meson/edit/master/docs/markdown/Users.md) for it. All the software on this list is tested for regressions before release, so it's highly recommended that projects add themselves here. +If you have a project that uses Meson that you want to add to this list, please [file a pull-request](https://github.com/mesonbuild/meson/edit/master/docs/markdown/Users.md) for it. All the software on this list is tested for regressions before release, so it's highly recommended that projects add themselves here. Some additional projects are +listed in the [`meson` GitHub topic](https://github.com/topics/meson). - [AQEMU](https://github.com/tobimensch/aqemu), a Qt GUI for QEMU virtual machines, since version 0.9.3 - [Arduino sample project](https://github.com/jpakkane/mesonarduino) diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md index 4e7e220..acc18d7 100644 --- a/docs/markdown/howtox.md +++ b/docs/markdown/howtox.md @@ -125,9 +125,9 @@ Install scan-build and configure your project. Then do this: $ ninja scan-build ``` -You can use the `SCAN_BUILD` environment variable to choose the scan-build executable. +You can use the `SCANBUILD` environment variable to choose the scan-build executable. ```console -$ SCAN_BUILD=<your exe> ninja scan-build +$ SCANBUILD=<your exe> ninja scan-build ``` diff --git a/docs/markdown/snippets/install_data-rename.md b/docs/markdown/snippets/install_data-rename.md new file mode 100644 index 0000000..6378d0f --- /dev/null +++ b/docs/markdown/snippets/install_data-rename.md @@ -0,0 +1,11 @@ +## install_data() supports rename + +`rename` parameter is used to change names of the installed files. +In order to install +- `file1.txt` into `share/myapp/dir1/data.txt` +- `file2.txt` into `share/myapp/dir2/data.txt` +```meson +install_data(['file1.txt', 'file2.txt'], + rename : ['dir1/data.txt', 'dir2/data.txt'], + install_dir : 'share/myapp') +``` diff --git a/docs/markdown/snippets/pkgconfig-generator.md b/docs/markdown/snippets/pkgconfig-generator.md new file mode 100644 index 0000000..93920d3 --- /dev/null +++ b/docs/markdown/snippets/pkgconfig-generator.md @@ -0,0 +1,14 @@ +## Improvements to pkgconfig module + +A `StaticLibrary` or `SharedLibrary` object can optionally be passed +as first positional argument of the `generate()` method. If one is provided a +default value will be provided for all required fields of the pc file: +- `install_dir` is set to `pkgconfig` folder in the same location than the provided library. +- `description` is set to the project's name followed by the library's name. +- `name` is set to the library's name. + +Generating a .pc file is now as simple as: + +``` +pkgconfig.generate(mylib) +``` |