diff options
35 files changed, 476 insertions, 234 deletions
diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index 74a918a..b084451 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -206,8 +206,8 @@ subparts of Qt the program uses. ## Dependencies using config tools -CUPS, LLVM, PCAP, WxWidgets, libwmf, and GnuStep either do not provide -pkg-config modules or additionally can be detected via a config tool +CUPS, LLVM, PCAP, [WxWidgets](#wxwidgets), libwmf, and GnuStep either do not +provide pkg-config modules or additionally can be detected via a config tool (cups-config, llvm-config, etc). Meson has native support for these tools, and then can be found like other dependencies: @@ -224,6 +224,30 @@ tools support. You can force one or another via the method keyword: wmf_dep = dependency('wmf', method : 'config-tool') ``` +## WxWidgets + +Similar to [Boost](#boost), WxWidgets is not a single library but rather +a collection of modules. WxWidgets is supported via `wx-config`. +Meson substitutes `modules` to `wx-config` invocation, it generates +- `compile_args` using `wx-config --cxxflags $modules...` +- `link_args` using `wx-config --libs $modules...` + +### Example + +```meson +wx_dep = dependency( + 'wxwidgets', version : '>=3.0.0', modules : ['std', 'stc'], +) +``` + +```shell +# compile_args: +$ wx-config --cxxflags std stc + +# link_args: +$ wx-config --libs std stc +``` + ## LLVM Meson has native support for LLVM going back to version LLVM version 3.5. diff --git a/docs/markdown/FAQ.md b/docs/markdown/FAQ.md index 441cd69..1dbc80a 100644 --- a/docs/markdown/FAQ.md +++ b/docs/markdown/FAQ.md @@ -7,9 +7,16 @@ See also [How do I do X in Meson](howtox.md). ## Why is it called Meson? -When the name was originally chosen, there were two main limitations: there must not exist either a Debian package or a Sourceforge project of the given name. This ruled out tens of potential project names. At some point the name Gluon was considered. Gluons are elementary particles that hold protons and neutrons together, much like a build system's job is to take pieces of source code and a compiler and bind them to a complete whole. +When the name was originally chosen, there were two main limitations: +there must not exist either a Debian package or a Sourceforge project +of the given name. This ruled out tens of potential project names. At +some point the name Gluon was considered. Gluons are elementary +particles that hold protons and neutrons together, much like a build +system's job is to take pieces of source code and a compiler and bind +them to a complete whole. -Unfortunately this name was taken, too. Then the rest of subatomic particles were examined and Meson was found to be available. +Unfortunately this name was taken, too. Then the rest of subatomic +particles were examined and Meson was found to be available. ## What is the correct way to use threads (such as pthreads)? @@ -17,23 +24,34 @@ Unfortunately this name was taken, too. Then the rest of subatomic particles wer thread_dep = dependency('threads') ``` -This will set up everything on your behalf. People coming from Autotools or CMake want to do this by looking for `libpthread.so` manually. Don't do that, it has tricky corner cases especially when cross compiling. +This will set up everything on your behalf. People coming from +Autotools or CMake want to do this by looking for `libpthread.so` +manually. Don't do that, it has tricky corner cases especially when +cross compiling. ## How to use Meson on a host where it is not available in system packages? -Starting from version 0.29.0, Meson is available from the [Python Package Index](https://pypi.python.org/pypi/meson/), so installing it simply a matter of running this command: +Starting from version 0.29.0, Meson is available from the [Python +Package Index](https://pypi.python.org/pypi/meson/), so installing it +simply a matter of running this command: ```console $ pip3 install <your options here> meson ``` -If you don't have access to PyPI, that is not a problem either. Meson has been designed to be easily runnable from an extracted source tarball or even a git checkout. First you need to download Meson. Then use this command to set up you build instead of plain `meson`. +If you don't have access to PyPI, that is not a problem either. Meson +has been designed to be easily runnable from an extracted source +tarball or even a git checkout. First you need to download Meson. Then +use this command to set up you build instead of plain `meson`. ```console $ /path/to/meson.py <options> ``` -After this you don't have to care about invoking Meson any more. It remembers where it was originally invoked from and calls itself appropriately. As a user the only thing you need to do is to `cd` into your build directory and invoke `ninja`. +After this you don't have to care about invoking Meson any more. It +remembers where it was originally invoked from and calls itself +appropriately. As a user the only thing you need to do is to `cd` into +your build directory and invoke `ninja`. ## Why can't I specify target files with a wildcard? @@ -43,17 +61,34 @@ Instead of specifying files explicitly, people seem to want to do this: executable('myprog', sources : '*.cpp') # This does NOT work! ``` -Meson does not support this syntax and the reason for this is simple. This can not be made both reliable and fast. By reliable we mean that if the user adds a new source file to the subdirectory, Meson should detect that and make it part of the build automatically. +Meson does not support this syntax and the reason for this is +simple. This can not be made both reliable and fast. By reliable we +mean that if the user adds a new source file to the subdirectory, +Meson should detect that and make it part of the build automatically. -One of the main requirements of Meson is that it must be fast. This means that a no-op build in a tree of 10 000 source files must take no more than a fraction of a second. This is only possible because Meson knows the exact list of files to check. If any target is specified as a wildcard glob, this is no longer possible. Meson would need to re-evaluate the glob every time and compare the list of files produced against the previous list. This means inspecting the entire source tree (because the glob pattern could be `src/\*/\*/\*/\*.cpp` or something like that). This is impossible to do efficiently. +One of the main requirements of Meson is that it must be fast. This +means that a no-op build in a tree of 10 000 source files must take no +more than a fraction of a second. This is only possible because Meson +knows the exact list of files to check. If any target is specified as +a wildcard glob, this is no longer possible. Meson would need to +re-evaluate the glob every time and compare the list of files produced +against the previous list. This means inspecting the entire source +tree (because the glob pattern could be `src/\*/\*/\*/\*.cpp` or +something like that). This is impossible to do efficiently. -The main backend of Meson is Ninja, which does not support wildcard matches either, and for the same reasons. +The main backend of Meson is Ninja, which does not support wildcard +matches either, and for the same reasons. Because of this, all source files must be specified explicitly. ## But I really want to use wildcards! -If the tradeoff between reliability and convenience is acceptable to you, then Meson gives you all the tools necessary to do wildcard globbing. You are allowed to run arbitrary commands during configuration. First you need to write a script that locates the files to compile. Here's a simple shell script that writes all `.c` files in the current directory, one per line. +If the tradeoff between reliability and convenience is acceptable to +you, then Meson gives you all the tools necessary to do wildcard +globbing. You are allowed to run arbitrary commands during +configuration. First you need to write a script that locates the files +to compile. Here's a simple shell script that writes all `.c` files in +the current directory, one per line. ```bash @@ -72,17 +107,37 @@ sources = c.stdout().strip().split('\n') e = executable('prog', sources) ``` -The script can be any executable, so it can be written in shell, Python, Lua, Perl or whatever you wish. +The script can be any executable, so it can be written in shell, +Python, Lua, Perl or whatever you wish. -As mentioned above, the tradeoff is that just adding new files to the source directory does *not* add them to the build automatically. To add them you need to tell Meson to reinitialize itself. The simplest way is to touch the `meson.build` file in your source root. Then Meson will reconfigure itself next time the build command is run. Advanced users can even write a small background script that utilizes a filesystem event queue, such as [inotify](https://en.wikipedia.org/wiki/Inotify), to do this automatically. +As mentioned above, the tradeoff is that just adding new files to the +source directory does *not* add them to the build automatically. To +add them you need to tell Meson to reinitialize itself. The simplest +way is to touch the `meson.build` file in your source root. Then Meson +will reconfigure itself next time the build command is run. Advanced +users can even write a small background script that utilizes a +filesystem event queue, such as +[inotify](https://en.wikipedia.org/wiki/Inotify), to do this +automatically. ## Should I use `subdir` or `subproject`? -The answer is almost always `subdir`. Subproject exists for a very specific use case: embedding external dependencies into your build process. As an example, suppose we are writing a game and wish to use SDL. Let us further suppose that SDL comes with a Meson build definition. Let us suppose even further that we don't want to use prebuilt binaries but want to compile SDL for ourselves. +The answer is almost always `subdir`. Subproject exists for a very +specific use case: embedding external dependencies into your build +process. As an example, suppose we are writing a game and wish to use +SDL. Let us further suppose that SDL comes with a Meson build +definition. Let us suppose even further that we don't want to use +prebuilt binaries but want to compile SDL for ourselves. -In this case you would use `subproject`. The way to do it would be to grab the source code of SDL and put it inside your own source tree. Then you would do `sdl = subproject('sdl')`, which would cause Meson to build SDL as part of your build and would then allow you to link against it or do whatever else you may prefer. +In this case you would use `subproject`. The way to do it would be to +grab the source code of SDL and put it inside your own source +tree. Then you would do `sdl = subproject('sdl')`, which would cause +Meson to build SDL as part of your build and would then allow you to +link against it or do whatever else you may prefer. -For every other use you would use `subdir`. As an example, if you wanted to build a shared library in one dir and link tests against it in another dir, you would do something like this: +For every other use you would use `subdir`. As an example, if you +wanted to build a shared library in one dir and link tests against it +in another dir, you would do something like this: ```meson project('simple', 'c') @@ -92,27 +147,53 @@ subdir('tests') # test binaries would link against the library here ## Why is there not a Make backend? -Because Make is slow. This is not an implementation issue, Make simply can not be made fast. For further info we recommend you read [this post](http://neugierig.org/software/chromium/notes/2011/02/ninja.html) by Evan Martin, the author of Ninja. Makefiles also have a syntax that is very unpleasant to write which makes them a big maintenance burden. +Because Make is slow. This is not an implementation issue, Make simply +can not be made fast. For further info we recommend you read [this +post](http://neugierig.org/software/chromium/notes/2011/02/ninja.html) +by Evan Martin, the author of Ninja. Makefiles also have a syntax that +is very unpleasant to write which makes them a big maintenance burden. -The only reason why one would use Make instead of Ninja is working on a platform that does not have a Ninja port. Even in this case it is an order of magnitude less work to port Ninja than it is to write a Make backend for Meson. +The only reason why one would use Make instead of Ninja is working on +a platform that does not have a Ninja port. Even in this case it is an +order of magnitude less work to port Ninja than it is to write a Make +backend for Meson. Just use Ninja, you'll be happier that way. I guarantee it. ## Why is Meson not just a Python module so I could code my build setup in Python? -A related question to this is *Why is Meson's configuration language not Turing-complete?* +A related question to this is *Why is Meson's configuration language +not Turing-complete?* -There are many good reasons for this, most of which are summarized on this web page: [Against The Use Of Programming Languages in Configuration Files](https://taint.org/2011/02/18/001527a.html). +There are many good reasons for this, most of which are summarized on +this web page: [Against The Use Of Programming Languages in +Configuration Files](https://taint.org/2011/02/18/001527a.html). -In addition to those reasons, not exposing Python or any other "real" programming language makes it possible to port Meson's implementation to a different language. This might become necessary if, for example, Python turns out to be a performance bottleneck. This is an actual problem that has caused complications for GNU Autotools and SCons. +In addition to those reasons, not exposing Python or any other "real" +programming language makes it possible to port Meson's implementation +to a different language. This might become necessary if, for example, +Python turns out to be a performance bottleneck. This is an actual +problem that has caused complications for GNU Autotools and SCons. ## How do I do the equivalent of Libtools export-symbol and export-regex? -Either by using [GCC symbol visibility](https://gcc.gnu.org/wiki/Visibility) or by writing a [linker script](https://ftp.gnu.org/old-gnu/Manuals/ld-2.9.1/html_mono/ld.html). This has the added benefit that your symbol definitions are in a standalone file instead of being buried inside your build definitions. An example can be found [here](https://github.com/jpakkane/meson/tree/master/test%20cases/linuxlike/3%20linker%20script). +Either by using [GCC symbol +visibility](https://gcc.gnu.org/wiki/Visibility) or by writing a +[linker +script](https://ftp.gnu.org/old-gnu/Manuals/ld-2.9.1/html_mono/ld.html). This +has the added benefit that your symbol definitions are in a standalone +file instead of being buried inside your build definitions. An example +can be found +[here](https://github.com/jpakkane/meson/tree/master/test%20cases/linuxlike/3%20linker%20script). ## My project works fine on Linux and MinGW but fails with MSVC due to a missing .lib file -With GCC, all symbols on shared libraries are exported automatically unless you specify otherwise. With MSVC no symbols are exported by default. If your shared library exports no symbols, MSVC will silently not produce an import library file leading to failures. The solution is to add symbol visibility definitions [as specified in GCC wiki](https://gcc.gnu.org/wiki/Visibility). +With GCC, all symbols on shared libraries are exported automatically +unless you specify otherwise. With MSVC no symbols are exported by +default. If your shared library exports no symbols, MSVC will silently +not produce an import library file leading to failures. The solution +is to add symbol visibility definitions [as specified in GCC +wiki](https://gcc.gnu.org/wiki/Visibility). ## I added some compiler flags and now the build fails with weird errors. What is happening? @@ -123,7 +204,13 @@ executable('foobar', ... c_args : '-some_arg -other_arg') ``` -Meson is *explicit*. In this particular case it will **not** automatically split your strings at whitespaces, instead it will take it as is and work extra hard to pass it to the compiler unchanged, including quoting it properly over shell invocations. This is mandatory to make e.g. files with spaces in them work flawlessly. To pass multiple command line arguments, you need to explicitly put them in an array like this: +Meson is *explicit*. In this particular case it will **not** +automatically split your strings at whitespaces, instead it will take +it as is and work extra hard to pass it to the compiler unchanged, +including quoting it properly over shell invocations. This is +mandatory to make e.g. files with spaces in them work flawlessly. To +pass multiple command line arguments, you need to explicitly put them +in an array like this: ```meson executable('foobar', ... @@ -138,20 +225,66 @@ You probably had a project that looked something like this: project('foobar', 'cpp') ``` -This defaults to `c++11` on GCC compilers. Suppose you want to use `c++14` instead, so you change the definition to this: +This defaults to `c++11` on GCC compilers. Suppose you want to use +`c++14` instead, so you change the definition to this: ```meson project('foobar', 'cpp', default_options : ['cpp_std=c++14']) ``` -But when you recompile, it still uses `c++11`. The reason for this is that default options are only looked at when you are setting up a build directory for the very first time. After that the setting is considered to have a value and thus the default value is ignored. To change an existing build dir to `c++14`, either reconfigure your build dir with `meson configure` or delete the build dir and recreate it from scratch. +But when you recompile, it still uses `c++11`. The reason for this is +that default options are only looked at when you are setting up a +build directory for the very first time. After that the setting is +considered to have a value and thus the default value is ignored. To +change an existing build dir to `c++14`, either reconfigure your build +dir with `meson configure` or delete the build dir and recreate it +from scratch. + +The reason we don't automatically change the option value when the +default is changed is that it is impossible to know to do that +reliably. The actual question that we need to solve is "if the +option's value is foo and the default value is bar, should we change +the option value to bar also". There are many choices: + + - if the user has changed the value themselves from the default, then + we must not change it back + + - if the user has not changed the value, but changes the default + value, then this section's premise would seem to indicate that the + value should be changed + + - suppose the user changes the value from the default to foo, then + back to bar and then changes the default value to bar, the correct + step to take is ambiguous by itself + +In order to solve the latter question we would need to remember not +only the current and old value, but also all the times the user has +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 +values are only defaults and will never affect the value of an option +once set. ## Does wrap download sources behind my back? -It does not. In order for Meson to download anything from the net while building, two conditions must be met. - -First of all there needs to be a `.wrap` file with a download URL in the `subprojects` directory. If one does not exist, Meson will not download anything. - -The second requirement is that there needs to be an explicit subproject invocation in your `meson.build` files. Either `subproject('foobar')` or `dependency('foobar', fallback : ['foobar', 'foo_dep'])`. If these declarations either are not in any build file or they are not called (due to e.g. `if/else`) then nothing is downloaded. - -If this is not sufficient for you, starting from release 0.40.0 Meson 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. +It does not. In order for Meson to download anything from the net +while building, two conditions must be met. + +First of all there needs to be a `.wrap` file with a download URL in +the `subprojects` directory. If one does not exist, Meson will not +download anything. + +The second requirement is that there needs to be an explicit +subproject invocation in your `meson.build` files. Either +`subproject('foobar')` or `dependency('foobar', fallback : ['foobar', +'foo_dep'])`. If these declarations either are not in any build file +or they are not called (due to e.g. `if/else`) then nothing is +downloaded. + +If this is not sufficient for you, starting from release 0.40.0 Meson +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. diff --git a/docs/markdown/Generating-sources.md b/docs/markdown/Generating-sources.md index a160095..1c3225b 100644 --- a/docs/markdown/Generating-sources.md +++ b/docs/markdown/Generating-sources.md @@ -4,23 +4,32 @@ short-description: Generation of source files before compilation # Generating sources - Sometimes source files need to be preprocessed before they are passed to the actual compiler. As an example you might want build an IDL compiler and then run some files through that to generate actual source files. In Meson this is done with [`generator()`](Reference-manual.md#generator) or [`custom_target()`](Reference-manual.md#custom_target). +Sometimes source files need to be preprocessed before they are passed +to the actual compiler. As an example you might want build an IDL +compiler and then run some files through that to generate actual +source files. In Meson this is done with +[`generator()`](Reference-manual.md#generator) or +[`custom_target()`](Reference-manual.md#custom_target). ## Using custom_target() -Let's say you have a build target that must be built using sources generated by a compiler. The compiler can either be a built target: +Let's say you have a build target that must be built using sources +generated by a compiler. The compiler can either be a built target: ```meson mycomp = executable('mycompiler', 'compiler.c') ``` -Or an external program provided by the system, or script inside the source tree: +Or an external program provided by the system, or script inside the +source tree: ```meson mycomp = find_program('mycompiler') ``` -Custom targets can take zero or more input files and use them to generate one or more output files. Using a custom target, you can run this compiler at build time to generate the sources: +Custom targets can take zero or more input files and use them to +generate one or more output files. Using a custom target, you can run +this compiler at build time to generate the sources: ```meson gen_src = custom_target('gen-output', @@ -31,7 +40,9 @@ gen_src = custom_target('gen-output', '--h-out', '@OUTPUT1@']) ``` -The `@INPUT@` there will be transformed to `'somefile1.c' 'file2.c'`. Just like the output, you can also refer to each input file individually by index. +The `@INPUT@` there will be transformed to `'somefile1.c' +'file2.c'`. Just like the output, you can also refer to each input +file individually by index. Then you just put that in your program and you're done. @@ -41,11 +52,21 @@ executable('program', 'main.c', gen_src) ## Using generator() -Generators are similar to custom targets, except that we define a *generator*, which defines how to transform an input file into one or more output files, and then use that on as many input files as we want. +Generators are similar to custom targets, except that we define a +*generator*, which defines how to transform an input file into one or +more output files, and then use that on as many input files as we +want. -Note that generators should only be used for outputs that will only be used as inputs for a build target or a custom target. When you use the processed output of a generator in multiple targets, the generator will be run multiple times to create outputs for each target. Each output will be created in a target-private directory `@BUILD_DIR@`. +Note that generators should only be used for outputs that will only be +used as inputs for a build target or a custom target. When you use the +processed output of a generator in multiple targets, the generator +will be run multiple times to create outputs for each target. Each +output will be created in a target-private directory `@BUILD_DIR@`. -If you want to generate files for general purposes such as for generating headers to be used by several sources, or data that will be installed, and so on, use a [`custom_target()`](Reference-manual.md#custom_target) instead. +If you want to generate files for general purposes such as for +generating headers to be used by several sources, or data that will be +installed, and so on, use a +[`custom_target()`](Reference-manual.md#custom_target) instead. ```meson @@ -54,9 +75,23 @@ gen = generator(mycomp, arguments : ['@INPUT@', '@OUTPUT@']) ``` -The first argument is the executable file to run. The next file specifies a name generation rule. It specifies how to build the output file name for a given input name. `@BASENAME@` is a placeholder for the input file name without preceding path or suffix (if any). So if the input file name were `some/path/filename.idl`, then the output name would be `filename.c`. You can also use `@PLAINNAME@`, which preserves the suffix which would result in a file called `filename.idl.c`. The last line specifies the command line arguments to pass to the executable. `@INPUT@` and `@OUTPUT@` are placeholders for the input and output files, respectively, and will be automatically filled in by Meson. If your rule produces multiple output files and you need to pass them to the command line, append the location to the output holder like this: `@OUTPUT0@`, `@OUTPUT1@` and so on. - -With this rule specified we can generate source files and add them to a target. +The first argument is the executable file to run. The next file +specifies a name generation rule. It specifies how to build the output +file name for a given input name. `@BASENAME@` is a placeholder for +the input file name without preceding path or suffix (if any). So if +the input file name were `some/path/filename.idl`, then the output +name would be `filename.c`. You can also use `@PLAINNAME@`, which +preserves the suffix which would result in a file called +`filename.idl.c`. The last line specifies the command line arguments +to pass to the executable. `@INPUT@` and `@OUTPUT@` are placeholders +for the input and output files, respectively, and will be +automatically filled in by Meson. If your rule produces multiple +output files and you need to pass them to the command line, append the +location to the output holder like this: `@OUTPUT0@`, `@OUTPUT1@` and +so on. + +With this rule specified we can generate source files and add them to +a target. ```meson gen_src = gen.process('input1.idl', 'input2.idl') @@ -67,13 +102,26 @@ Generators can also generate multiple output files with unknown names: ```meson gen2 = generator(someprog, - outputs : ['@BASENAME@.c', '@BASENAME@.h'], + output : ['@BASENAME@.c', '@BASENAME@.h'], arguments : ['--out_dir=@BUILD_DIR@', '@INPUT@']) ``` -In this case you can not use the plain `@OUTPUT@` variable, as it would be ambiguous. This program only needs to know the output directory, it will generate the file names by itself. - -To make passing different additional arguments to the generator program at each use possible, you can use the `@EXTRA_ARGS@` string in the `arguments` list. Note that this placeholder can only be present as a whole string, and not as a substring. The main reason is that it represents a list of strings, which may be empty, or contain multiple elements; and in either case, interpolating it into the middle of a single string would be troublesome. If there are no extra arguments passed in from a `process()` invocation, the placeholder is entirely omitted from the actual list of arguments, so an empty string won't be passed to the generator program because of this. If there are multiple elements in `extra_args`, they are inserted into to the actual argument list as separate elements. +In this case you can not use the plain `@OUTPUT@` variable, as it +would be ambiguous. This program only needs to know the output +directory, it will generate the file names by itself. + +To make passing different additional arguments to the generator +program at each use possible, you can use the `@EXTRA_ARGS@` string in +the `arguments` list. Note that this placeholder can only be present +as a whole string, and not as a substring. The main reason is that it +represents a list of strings, which may be empty, or contain multiple +elements; and in either case, interpolating it into the middle of a +single string would be troublesome. If there are no extra arguments +passed in from a `process()` invocation, the placeholder is entirely +omitted from the actual list of arguments, so an empty string won't be +passed to the generator program because of this. If there are multiple +elements in `extra_args`, they are inserted into to the actual +argument list as separate elements. ```meson gen3 = generator(genprog, diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 8d6f89c..a02ad1c 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -580,7 +580,7 @@ the following special substitutions: - `@PLAINNAME@`: the complete input file name, e.g: `foo.c` becomes `foo.c` (unchanged) - `@BASENAME@`: the base of the input filename, e.g.: `foo.c.y` becomes `foo.c` (extension is removed) -Each string passed to the `outputs` keyword argument *must* be +Each string passed to the `output` keyword argument *must* be constructed using one or both of these two substitutions. In addition to the above substitutions, the `arguments` keyword diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md index 4b7006e..7611232 100644 --- a/docs/markdown/Reference-tables.md +++ b/docs/markdown/Reference-tables.md @@ -70,7 +70,7 @@ future releases. These are the parameter names for passing language specific arguments to your build target. | Language | Parameter name | -| ----- | ----- +| ----- | ----- | | C | c_args | | C++ | cpp_args | | C# | cs_args | diff --git a/docs/markdown/Release-notes-for-0.45.0.md b/docs/markdown/Release-notes-for-0.45.0.md index b3df71c..23bff93 100644 --- a/docs/markdown/Release-notes-for-0.45.0.md +++ b/docs/markdown/Release-notes-for-0.45.0.md @@ -1,16 +1,187 @@ --- title: Release 0.45 -short-description: Release notes for 0.45 (preliminary) +short-description: Release notes for 0.45 ... # New features -This page is a placeholder for the eventual release notes. +## Config-Tool based dependencies can be specified in a cross file -Notable new features should come with release note updates. This is -done by creating a file snippet called `snippets/featurename.md` and -whose contents should look like this: +Tools like LLVM and pcap use a config tool for dependencies, this is a script +or binary that is run to get configuration information (cflags, ldflags, etc) +from. - ## Feature name +These binaries may now be specified in the `binaries` section of a cross file. - A short description explaining the new feature and how it should be used. +```dosini +[binaries] +cc = ... +llvm-config = '/usr/bin/llvm-config32' +``` + +## Visual Studio C# compiler support + +In addition to the Mono C# compiler we also support Visual Studio's C# +compiler. Currently this is only supported on the Ninja backend. + +## Removed two deprecated features + +The standalone `find_library` function has been a no-op for a long +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') + +This is now an error. The correct format for this is now: + + run_target('targetname', + command : ['command', 'arg1', 'arg2']) + +## Experimental FPGA support + +This version adds support for generating, analysing and uploading FPGA +programs using the [IceStorm +toolchain](http://www.clifford.at/icestorm/). This support is +experimental and is currently limited to the `iCE 40` series of FPGA +chips. + +FPGA generation integrates with other parts of Meson seamlessly. As an +example, [here](https://github.com/jpakkane/lm32) is an example +project that compiles a simple firmware into Verilog and combines that +with an lm32 softcore processor. + +## Generator outputs can preserve directory structure + +Normally when generating files with a generator, Meson flattens the +input files so they all go in the same directory. Some code +generators, such as Protocol Buffers, require that the generated files +have the same directory layout as the input files used to generate +them. This can now be achieved like this: + +```meson +g = generator(...) # Compiles protobuf sources +generated = gen.process('com/mesonbuild/one.proto', + 'com/mesonbuild/two.proto', + preserve_path_from : meson.current_source_dir()) +``` + +This would cause the following files to be generated inside the target +private directory: + + com/mesonbuild/one.pb.h + com/mesonbuild/one.pb.cc + com/mesonbuild/two.pb.h + com/mesonbuild/two.pb.cc + +## Hexadecimal string literals + +Hexadecimal integer literals can now be used in build and option files. + + int_255 = 0xFF + +## b_ndebug : if-release + +The value `if-release` can be given for the `b_ndebug` project option. + +This will make the `NDEBUG` pre-compiler macro to be defined for release +type builds as if the `b_ndebug` project option had had the value `true` +defined for it. + +## `install_data()` defaults to `{datadir}/{projectname}` + +If `install_data()` is not given an `install_dir` keyword argument, the +target directory defaults to `{datadir}/{projectname}` (e.g. +`/usr/share/myproj`). + +## install_subdir() supports strip_directory + +If strip_directory=true install_subdir() installs directory contents +instead of directory itself, stripping basename of the source directory. + +## Integer options + +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) + +## New method meson.project_license() + +The `meson` builtin object now has a `project_license()` method that returns a +list of all licenses for the project. + +## Rust cross-compilation + +Cross-compilation is now supported for Rust targets. Like other +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: + +``` +[binaries] +c = '/usr/bin/arm-linux-gnueabihf-gcc-7' +rust = [ + 'rustc', + '--target', 'arm-unknown-linux-gnueabihf', + '-C', 'linker=/usr/bin/arm-linux-gnueabihf-gcc-7', +] +``` + +## Rust compiler-private library disambiguation + +When building a Rust target with Rust library dependencies, an +`--extern` argument is now specified to avoid ambiguity between the +dependency library, and any crates of the same name in `rustc`'s +private sysroot. + +## Project templates + +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 +``` + +## Improve test setup selection + +Test setups are now identified (also) by the project they belong to and it +is possible to select the used test setup from a specific project. E.g. +to use a test setup `some_setup` from project `some_project` for all +executed tests one can use + + meson test --setup some_project:some_setup + +Should one rather want test setups to be used from the same project as +where the current test itself has been defined, one can use just + + meson test --setup some_setup + +In the latter case every (sub)project must have a test setup `some_setup` +defined in it. + +## Can use custom targets as Windows resource files + +The `compile_resources()` function of the `windows` module can now be used on custom targets as well as regular files. +# Can promote dependencies with wrap command + +The `promote` command makes it easy to copy nested dependencies to the top level. + + meson wrap promote scommon + +This will search the project tree for a subproject called `scommon` and copy it to the top level. + +If there are many embedded subprojects with the same name, you have to specify which one to promote manually like this: + + meson wrap promote subprojects/s1/subprojects/scommon + +## Yielding subproject option to superproject + +Normally project options are specific to the current project. However +sometimes you want to have an option whose value is the same over all +projects. This can be achieved with the new `yield` keyword for +options. When set to `true`, getting the value of this option in +`meson.build` files gets the value from the option with the same name +in the master project (if such an option exists). diff --git a/docs/markdown/Release-notes-for-0.46.0.md b/docs/markdown/Release-notes-for-0.46.0.md new file mode 100644 index 0000000..395a94d --- /dev/null +++ b/docs/markdown/Release-notes-for-0.46.0.md @@ -0,0 +1,16 @@ +--- +title: Release 0.46 +short-description: Release notes for 0.46 (preliminary) +... + +# New features + +This page is a placeholder for the eventual release notes. + +Notable new features should come with release note updates. This is +done by creating a file snippet called `snippets/featurename.md` and +whose contents should look like this: + + ## Feature name + + A short description explaining the new feature and how it should be used. diff --git a/docs/markdown/snippets/config-tool-cross.md b/docs/markdown/snippets/config-tool-cross.md deleted file mode 100644 index 1102481..0000000 --- a/docs/markdown/snippets/config-tool-cross.md +++ /dev/null @@ -1,13 +0,0 @@ -# Config-Tool based dependencies can be specified in a cross file - -Tools like LLVM and pcap use a config tool for dependencies, this is a script -or binary that is run to get configuration information (cflags, ldflags, etc) -from. - -These binaries may now be specified in the `binaries` section of a cross file. - -```dosini -[binaries] -cc = ... -llvm-config = '/usr/bin/llvm-config32' -``` diff --git a/docs/markdown/snippets/csc.md b/docs/markdown/snippets/csc.md deleted file mode 100644 index 90a6f7f..0000000 --- a/docs/markdown/snippets/csc.md +++ /dev/null @@ -1,4 +0,0 @@ -## Visual Studio C# compiler support - -In addition to the Mono C# compiler we also support Visual Studio's C# -compiler. Currently this is only supported on the Ninja backend. diff --git a/docs/markdown/snippets/deprecations.md b/docs/markdown/snippets/deprecations.md deleted file mode 100644 index adab2e6..0000000 --- a/docs/markdown/snippets/deprecations.md +++ /dev/null @@ -1,14 +0,0 @@ -## Removed two deprecated features - -The standalone `find_library` function has been a no-op for a long -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') - -This is now an error. The correct format for this is now: - - run_target('targetname', - command : ['command', 'arg1', 'arg2']) diff --git a/docs/markdown/snippets/fpga.md b/docs/markdown/snippets/fpga.md deleted file mode 100644 index b5e4938..0000000 --- a/docs/markdown/snippets/fpga.md +++ /dev/null @@ -1,12 +0,0 @@ -## Experimental FPGA support - -This version adds support for generating, analysing and uploading FPGA -programs using the [IceStorm -toolchain](http://www.clifford.at/icestorm/). This support is -experimental and is currently limited to the `iCE 40` series of FPGA -chips. - -FPGA generation integrates with other parts of Meson seamlessly. As an -example, [here](https://github.com/jpakkane/lm32) is an example -project that compiles a simple firmware into Verilog and combines that -with an lm32 softcore processor. diff --git a/docs/markdown/snippets/gen-subdirs.md b/docs/markdown/snippets/gen-subdirs.md deleted file mode 100644 index fdb5945..0000000 --- a/docs/markdown/snippets/gen-subdirs.md +++ /dev/null @@ -1,21 +0,0 @@ -## Generator outputs can preserve directory structure - -Normally when generating files with a generator, Meson flattens the -input files so they all go in the same directory. Some code -generators, such as Protocol Buffers, require that the generated files -have the same directory layout as the input files used to generate -them. This can now be achieved like this: - -```meson -g = generator(...) # Compiles protobuf sources -generated = gen.process('com/mesonbuild/one.proto', - 'com/mesonbuild/two.proto', - preserve_path_from : meson.current_source_dir()) - -This would cause the following files to be generated inside the target -private directory: - - com/mesonbuild/one.pb.h - com/mesonbuild/one.pb.cc - com/mesonbuild/two.pb.h - com/mesonbuild/two.pb.cc diff --git a/docs/markdown/snippets/hexnumbers.md b/docs/markdown/snippets/hexnumbers.md deleted file mode 100644 index 840c0cb..0000000 --- a/docs/markdown/snippets/hexnumbers.md +++ /dev/null @@ -1,5 +0,0 @@ -## Hexadecimal string literals - -Hexadecimal integer literals can now be used in build and option files. - - int_255 = 0xFF diff --git a/docs/markdown/snippets/if-release.md b/docs/markdown/snippets/if-release.md deleted file mode 100644 index 96e12ef..0000000 --- a/docs/markdown/snippets/if-release.md +++ /dev/null @@ -1,7 +0,0 @@ -## b_ndebug : if-release - -The value `if-release` can be given for the `b_ndebug` project option. - -This will make the `NDEBUG` pre-compiler macro to be defined for release -type builds as if the `b_ndebug` project option had had the value `true` -defined for it. diff --git a/docs/markdown/snippets/install_subdir-strip_directory.md b/docs/markdown/snippets/install_subdir-strip_directory.md deleted file mode 100644 index 9ddb4a4..0000000 --- a/docs/markdown/snippets/install_subdir-strip_directory.md +++ /dev/null @@ -1,4 +0,0 @@ -## install_subdir() supports strip_directory - -If strip_directory=true install_subdir() installs directory contents -instead of directory itself, stripping basename of the source directory. diff --git a/docs/markdown/snippets/installdir.md b/docs/markdown/snippets/installdir.md deleted file mode 100644 index c709ffe..0000000 --- a/docs/markdown/snippets/installdir.md +++ /dev/null @@ -1,5 +0,0 @@ -## `install_data()` defaults to `{datadir}/{projectname}` - -If `install_data()` is not given an `install_dir` keyword argument, the -target directory defaults to `{datadir}/{projectname}` (e.g. -`/usr/share/myproj`). diff --git a/docs/markdown/snippets/intopt.md b/docs/markdown/snippets/intopt.md deleted file mode 100644 index daf660b..0000000 --- a/docs/markdown/snippets/intopt.md +++ /dev/null @@ -1,6 +0,0 @@ -## Integer options - -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) diff --git a/docs/markdown/snippets/project-license.md b/docs/markdown/snippets/project-license.md deleted file mode 100644 index 5da2c6a..0000000 --- a/docs/markdown/snippets/project-license.md +++ /dev/null @@ -1,4 +0,0 @@ -## New method meson.project_license() - -The `meson` builtin object now has a `project_license()` method that returns a -list of all licenses for the project. diff --git a/docs/markdown/snippets/rust-cross.md b/docs/markdown/snippets/rust-cross.md deleted file mode 100644 index 7f18c44..0000000 --- a/docs/markdown/snippets/rust-cross.md +++ /dev/null @@ -1,16 +0,0 @@ -## Rust cross-compilation - -Cross-compilation is now supported for Rust targets. Like other -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: - -``` -[binaries] -c = '/usr/bin/arm-linux-gnueabihf-gcc-7' -rust = [ - 'rustc', - '--target', 'arm-unknown-linux-gnueabihf', - '-C', 'linker=/usr/bin/arm-linux-gnueabihf-gcc-7', -] -``` diff --git a/docs/markdown/snippets/rust-private-disambiguation.md b/docs/markdown/snippets/rust-private-disambiguation.md deleted file mode 100644 index 6988a7a..0000000 --- a/docs/markdown/snippets/rust-private-disambiguation.md +++ /dev/null @@ -1,6 +0,0 @@ -## Rust compiler-private library disambiguation - -When building a Rust target with Rust library dependencies, an -`--extern` argument is now specified to avoid ambiguity between the -dependency library, and any crates of the same name in `rustc`'s -private sysroot. diff --git a/docs/markdown/snippets/templates.md b/docs/markdown/snippets/templates.md deleted file mode 100644 index 6f0474d..0000000 --- a/docs/markdown/snippets/templates.md +++ /dev/null @@ -1,8 +0,0 @@ -## Project templates - -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 -``` diff --git a/docs/markdown/snippets/test-setups.md b/docs/markdown/snippets/test-setups.md deleted file mode 100644 index 4598e73..0000000 --- a/docs/markdown/snippets/test-setups.md +++ /dev/null @@ -1,16 +0,0 @@ -## Improve test setup selection - -Test setups are now identified (also) by the project they belong to and it -is possible to select the used test setup from a specific project. E.g. -to use a test setup `some_setup` from project `some_project` for all -executed tests one can use - - meson test --setup some_project:some_setup - -Should one rather want test setups to be used from the same project as -where the current test itself has been defined, one can use just - - meson test --setup some_setup - -In the latter case every (sub)project must have a test setup `some_setup` -defined in it. diff --git a/docs/markdown/snippets/windows-resources-custom-targets.md b/docs/markdown/snippets/windows-resources-custom-targets.md deleted file mode 100644 index a2dce3a..0000000 --- a/docs/markdown/snippets/windows-resources-custom-targets.md +++ /dev/null @@ -1,3 +0,0 @@ -## Can use custom targets as Windows resource files - -The `compile_resources()` function of the `windows` module can now be used on custom targets as well as regular files. diff --git a/docs/markdown/snippets/wrap_promote.md b/docs/markdown/snippets/wrap_promote.md deleted file mode 100644 index 20fee47..0000000 --- a/docs/markdown/snippets/wrap_promote.md +++ /dev/null @@ -1,11 +0,0 @@ -# Can promote dependencies with wrap command - -The `promote` command makes it easy to copy nested dependencies to the top level. - - meson wrap promote scommon - -This will search the project tree for a subproject called `scommon` and copy it to the top level. - -If there are many embedded subprojects with the same name, you have to specify which one to promote manually like this: - - meson wrap promote subprojects/s1/subprojects/scommon diff --git a/docs/markdown/snippets/yield.md b/docs/markdown/snippets/yield.md deleted file mode 100644 index 3880e67..0000000 --- a/docs/markdown/snippets/yield.md +++ /dev/null @@ -1,8 +0,0 @@ -## Yielding subproject option to superproject - -Normally project options are specific to the current project. However -sometimes you want to have an option whose value is the same over all -projects. This can be achieved with the new `yield` keyword for -options. When set to `true`, getting the value of this option in -`meson.build` files gets the value from the option with the same name -in the master project (if such an option exists). diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 144ca4a..844b600 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -65,6 +65,7 @@ index.md Shipping-prebuilt-binaries-as-wraps.md fallback-wraptool.md Release-notes.md + Release-notes-for-0.46.0.md Release-notes-for-0.45.0.md Release-notes-for-0.44.0.md Release-notes-for-0.43.0.md diff --git a/man/meson.1 b/man/meson.1 index 4429fa2..19ad737 100644 --- a/man/meson.1 +++ b/man/meson.1 @@ -1,4 +1,4 @@ -.TH MESON "1" "December 2017" "meson 0.44.0" "User Commands" +.TH MESON "1" "March 2018" "meson 0.45.0" "User Commands" .SH NAME meson - a high productivity build system .SH DESCRIPTION diff --git a/man/mesonconf.1 b/man/mesonconf.1 index 3a83473..b189663 100644 --- a/man/mesonconf.1 +++ b/man/mesonconf.1 @@ -1,4 +1,4 @@ -.TH MESONCONF "1" "December 2017" "mesonconf 0.44.0" "User Commands" +.TH MESONCONF "1" "March 2018" "mesonconf 0.45.0" "User Commands" .SH NAME mesonconf - a tool to configure Meson builds .SH DESCRIPTION diff --git a/man/mesonintrospect.1 b/man/mesonintrospect.1 index 27f39c0..61aa381 100644 --- a/man/mesonintrospect.1 +++ b/man/mesonintrospect.1 @@ -1,4 +1,4 @@ -.TH MESONINTROSPECT "1" "December 2017" "mesonintrospect 0.44.0" "User Commands" +.TH MESONINTROSPECT "1" "March 2017" "mesonintrospect 0.45.0" "User Commands" .SH NAME mesonintrospect - a tool to extract information about a Meson build .SH DESCRIPTION diff --git a/man/mesontest.1 b/man/mesontest.1 index d2b2743..9a9f743 100644 --- a/man/mesontest.1 +++ b/man/mesontest.1 @@ -1,4 +1,4 @@ -.TH MESON "1" "December 2017" "meson 0.44.0" "User Commands" +.TH MESON "1" "March 2018" "meson 0.45.0" "User Commands" .SH NAME mesontest - test tool for the Meson build system .SH DESCRIPTION diff --git a/man/wraptool.1 b/man/wraptool.1 index 113b33c..93ec457 100644 --- a/man/wraptool.1 +++ b/man/wraptool.1 @@ -1,4 +1,4 @@ -.TH WRAPTOOL "1" "December 2017" "meson 0.44.0" "User Commands" +.TH WRAPTOOL "1" "March 2018" "meson 0.45.0" "User Commands" .SH NAME wraptool - source dependency downloader .SH DESCRIPTION diff --git a/mesonbuild/coredata.py b/mesonbuild/coredata.py index f22f9cd..e2a0b48 100644 --- a/mesonbuild/coredata.py +++ b/mesonbuild/coredata.py @@ -21,7 +21,7 @@ from .mesonlib import MesonException from .mesonlib import default_libdir, default_libexecdir, default_prefix import ast -version = '0.45.0.dev1' +version = '0.46.0.dev1' backendlist = ['ninja', 'vs', 'vs2010', 'vs2015', 'vs2017', 'xcode'] default_yielding = False diff --git a/run_unittests.py b/run_unittests.py index 3e5da22..c2299ca 100755 --- a/run_unittests.py +++ b/run_unittests.py @@ -525,9 +525,13 @@ class BasePlatformTests(unittest.TestCase): self.privatedir = os.path.join(self.builddir, 'meson-private') if inprocess: try: - (returncode, out, _) = run_configure(self.meson_mainfile, self.meson_args + args + extra_args) + (returncode, out, err) = run_configure(self.meson_mainfile, self.meson_args + args + extra_args) if returncode != 0: self._print_meson_log() + print('Stdout:\n') + print(out) + print('Stderr:\n') + print(err) raise RuntimeError('Configure failed') except: self._print_meson_log() @@ -1772,6 +1776,11 @@ int main(int argc, char **argv) { self._run(ninja, workdir=os.path.join(tmpdir, 'builddir')) + # The test uses mocking and thus requires that + # the current process is the one to run the Meson steps. + # If we are using an external test executable (most commonly + # in Debian autopkgtests) then the mocking won't work. + @unittest.skipIf('MESON_EXE' in os.environ, 'MESON_EXE is defined, can not use mocking.') def test_cross_file_system_paths(self): if is_windows(): raise unittest.SkipTest('system crossfile paths not defined for Windows (yet)') diff --git a/test cases/frameworks/10 gtk-doc/include/meson.build b/test cases/frameworks/10 gtk-doc/include/meson.build index f6dd99f..aa32885 100644 --- a/test cases/frameworks/10 gtk-doc/include/meson.build +++ b/test cases/frameworks/10 gtk-doc/include/meson.build @@ -13,4 +13,5 @@ generate_enums_docbook = find_program('generate-enums-docbook.py') docbook = custom_target('enum-docbook', output : 'bar.xml', - command : [generate_enums_docbook, '@OUTPUT@', 'BAR', 'BAR_TYPE', 'BAR_FOO']) + command : [generate_enums_docbook, '@OUTPUT@', 'BAR', 'BAR_TYPE', 'BAR_FOO'], + build_by_default : true) diff --git a/test cases/frameworks/10 gtk-doc/installed_files.txt.bak b/test cases/frameworks/10 gtk-doc/installed_files.txt index 9004af2..6f8ca01 100644 --- a/test cases/frameworks/10 gtk-doc/installed_files.txt.bak +++ b/test cases/frameworks/10 gtk-doc/installed_files.txt @@ -1,13 +1,15 @@ +usr/include/foo-version.h +usr/share/gtk-doc/html/foobar/BAR.html usr/share/gtk-doc/html/foobar/foobar.devhelp2 -usr/share/gtk-doc/html/foobar/foobar-foo.html usr/share/gtk-doc/html/foobar/foobar.html +usr/share/gtk-doc/html/foobar/foobar-foo.html +usr/share/gtk-doc/html/foobar/foobar-foo-version.html usr/share/gtk-doc/html/foobar/home.png usr/share/gtk-doc/html/foobar/index.html -usr/share/gtk-doc/html/foobar/index.sgml -usr/share/gtk-doc/html/foobar/left-insensitive.png usr/share/gtk-doc/html/foobar/left.png -usr/share/gtk-doc/html/foobar/right-insensitive.png +usr/share/gtk-doc/html/foobar/left-insensitive.png usr/share/gtk-doc/html/foobar/right.png +usr/share/gtk-doc/html/foobar/right-insensitive.png usr/share/gtk-doc/html/foobar/style.css -usr/share/gtk-doc/html/foobar/up-insensitive.png usr/share/gtk-doc/html/foobar/up.png +usr/share/gtk-doc/html/foobar/up-insensitive.png |