diff options
Diffstat (limited to 'docs')
37 files changed, 621 insertions, 241 deletions
diff --git a/docs/markdown/Configuring-a-build-directory.md b/docs/markdown/Configuring-a-build-directory.md index 774addf..8e016e2 100644 --- a/docs/markdown/Configuring-a-build-directory.md +++ b/docs/markdown/Configuring-a-build-directory.md @@ -9,9 +9,7 @@ generated. For example you might want to change from a debug build into a release build, set custom compiler flags, change the build options provided in your `meson_options.txt` file and so on. -The main tool for this is the `meson configure` command. You may also use the -`mesongui` graphical application if you want. However this document -describes the use of the command line client. +The main tool for this is the `meson configure` command. You invoke `meson configure` by giving it the location of your build dir. If omitted, the current working directory is used instead. Here's a diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md index c1ad317..520a081 100644 --- a/docs/markdown/Cross-compilation.md +++ b/docs/markdown/Cross-compilation.md @@ -261,7 +261,7 @@ myvar = meson.get_cross_property('somekey') ## Cross file locations As of version 0.44.0 meson supports loading cross files from system locations -on Linux and the BSDs. This will be $XDG_DATA_DIRS/meson/cross, or if +(except on Windows). This will be $XDG_DATA_DIRS/meson/cross, or if XDG_DATA_DIRS is undefined, then /usr/local/share/meson/cross and /usr/share/meson/cross will be tried in that order, for system wide cross files. User local files can be put in $XDG_DATA_HOME/meson/cross, or @@ -272,7 +272,7 @@ The order of locations tried is as follows: - The user local location - The system wide locations in order -Linux and BSD distributions are encouraged to ship cross files either with +Distributions are encouraged to ship cross files either with their cross compiler toolchain packages or as a standalone package, and put them in one of the system paths referenced above. diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index 74a918a..12e1b1f 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -61,7 +61,7 @@ zdep_prefix = zdep.get_pkgconfig_variable('libdir', define_variable: ['prefix', The dependency detector works with all libraries that provide a `pkg-config` file. Unfortunately several packages don't provide pkg-config files. Meson has autodetection support for some of these, -and they are described later on this page. +and they are described [later in this page](#dependencies-with-custom-lookup-functionality). # Declaring your own @@ -111,6 +111,14 @@ of all the work behind the scenes to make this work. # Dependencies with custom lookup functionality +## AppleFrameworks + +Use the `modules` keyword to list frameworks required, e.g. + +```meson +dep = find_dep('appleframeworks', modules : 'foundation') +``` + ## Boost Boost is not a single dependency but rather a group of different @@ -138,7 +146,11 @@ can set the BOOST_ROOT, BOOST_INCLUDEDIR, and/or BOOST_LIBRARYDIR environment variables. You can set the argument `threading` to `single` to use boost libraries that -has been compiled for single-threaded use instead. +have been compiled for single-threaded use instead. + +## GL + +This finds the OpenGL library in a way appropriate to the platform. ## GTest and GMock @@ -160,9 +172,9 @@ test('gtest test', e) MPI is supported for C, C++ and Fortran. Because dependencies are language-specific, you must specify the requested language using the `language` keyword argument, i.e., - * `dependency('mpi', language='c')` for the C MPI headers and libraries - * `dependency('mpi', language='cpp')` for the C++ MPI headers and libraries - * `dependency('mpi', language='fortran')` for the Fortran MPI headers and libraries + * `dependency('mpi', language: 'c')` for the C MPI headers and libraries + * `dependency('mpi', language: 'cpp')` for the C++ MPI headers and libraries + * `dependency('mpi', language: 'fortran')` for the Fortran MPI headers and libraries Meson prefers pkg-config for MPI, but if your MPI implementation does not provide them, it will search for the standard wrapper executables, @@ -171,9 +183,9 @@ are not in your path, they can be specified by setting the standard environment variables `MPICC`, `MPICXX`, `MPIFC`, `MPIF90`, or `MPIF77`, during configuration. -## Qt5 +## Qt4 & Qt5 -Meson has native Qt5 support. Its usage is best demonstrated with an +Meson has native Qt support. Its usage is best demonstrated with an example. ```meson @@ -204,12 +216,26 @@ the list of sources for the target. The `modules` keyword of `dependency` works just like it does with Boost. It tells which subparts of Qt the program uses. +## SDL2 + +SDL2 can be located using `pkg-confg`, the `sdl2-config` config tool, or as an +OSX framework. + +## Valgrind + +Meson will find valgrind using `pkg-config`, but only uses the compilation flags +and avoids trying to link with it's non-PIC static libs. + +## Vulkan + +Vulkan can be located using `pkg-config`, or the `VULKAN_SDK` environment variable. + ## 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: +they can be found like other dependencies: ```meson pcap_dep = dependency('pcap', version : '>=1.0') @@ -224,6 +250,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. @@ -257,10 +307,10 @@ llvm_dep = dependency( Python3 is handled specially by meson: 1. Meson tries to use `pkg-config`. -1. If `pkg-config` fails meson uses fallback: - - On Windows fallback is current `python3` interpreter. - - On OSX fallback is framework dependency from `/Library/Frameworks`. +1. If `pkg-config` fails meson uses a fallback: + - On Windows the fallback is the current `python3` interpreter. + - On OSX the fallback is a framework dependency from `/Library/Frameworks`. Note that `python3` found by this dependency might differ from the one used in -`python3` module because modules uses current interpreter but dependency tries +`python3` module because modules uses the current interpreter, but dependency tries `pkg-config` first. 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..cbe6c0d 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,19 +102,32 @@ 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, output : '@BASENAME@.cc', arguments : ['@INPUT@', '@EXTRA_ARGS@', '@OUTPUT@']) -gen3_src1 = gen3.process('input1.y) +gen3_src1 = gen3.process('input1.y') gen3_src2 = gen3.process('input2.y', extra_args: '--foo') gen3_src3 = gen3.process('input3.y', extra_args: ['--foo', '--bar']) ``` diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md index fbf9530..ad3715e 100644 --- a/docs/markdown/Gnome-module.md +++ b/docs/markdown/Gnome-module.md @@ -123,7 +123,9 @@ Returns an array of two elements which are: `[c_source, header_file]` ### gnome.mkenums() Generates enum files for GObject using the `glib-mkenums` tool. The -first argument is the base name of the output files. +first argument is the base name of the output files, unless `c_template` +and `h_template` are specified. In this case, the output files will be +the base name of the values passed as templates. This method is essentially a wrapper around the `glib-mkenums` tool's command line API. It is the most featureful method for enum creation. diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index f7939dd..f608c5c 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -6,7 +6,7 @@ short-description: Meson's API to integrate Meson support into an IDE Meson has exporters for Visual Studio and XCode, but writing a custom backend for every IDE out there is not a scalable approach. To solve this problem, Meson provides an API that makes it easy for any IDE or build tool to integrate Meson builds and provide an experience comparable to a solution native to the IDE. -The basic tool for this is a script called `mesonintrospect.py`. Some distro packages might not expose this script in the regular path, and in this case you need to execute it from the install directory. +The basic tool for this is `meson introspect`. The first thing to do when setting up a Meson project in an IDE is to select the source and build directories. For this example we assume that the source resides in an Eclipse-like directory called `workspace/project` and the build tree is nested inside it as `workspace/project/build`. First we initialise Meson by running the following command in the source directory. @@ -16,13 +16,13 @@ For the remainder of the document we assume that all commands are executed insid The first thing you probably want is to get a list of top level targets. For that we use the introspection tool. It comes with extensive command line help so we recommend using that in case problems appear. - mesonintrospect.py --targets + meson introspect --targets The JSON formats will not be specified in this document. The easiest way of learning them is to look at sample output from the tool. Once you have a list of targets, you probably need the list of source files that comprise the target. To get this list for a target, say `exampletarget`, issue the following command. - mesonintrospect.py --target-files exampletarget + meson introspect --target-files exampletarget In order to make code completion work, you need the compiler flags for each compilation step. Meson does not provide this itself, but the Ninja tool Meson uses to build does provide it. To find out the compile steps necessary to build target foo, issue the following command. @@ -32,7 +32,7 @@ Note that if the target has dependencies (such as generated sources), then the c The next thing to display is the list of options that can be set. These include build type and so on. Here's how to extract them. - mesonintrospect.py --buildoptions + meson introspect --buildoptions To set the options, use the `meson configure` command. @@ -40,6 +40,6 @@ Compilation and unit tests are done as usual by running the `ninja` and `ninja t When these tests fail, the user probably wants to run the failing test in a debugger. To make this as integrated as possible, extract the test test setups with this command. - mesonintrospect.py --tests + meson introspect --tests This provides you with all the information needed to run the test: what command to execute, command line arguments and environment variable settings. diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md index cbe01b4..853cf50 100644 --- a/docs/markdown/Pkgconfig-module.md +++ b/docs/markdown/Pkgconfig-module.md @@ -38,8 +38,9 @@ keyword arguments. search path, for example if you install headers into `${PREFIX}/include/foobar-1`, the correct value for this argument would be `foobar-1` -- `requires` list of strings to put in the `Requires` field -- `requires_private` list of strings to put in the `Requires.private` +- `requires` list of strings, pkgconfig-dependencies or libraries that + `pkgconfig.generate()` was used on to put in the `Requires` field +- `requires_private` same as `requires` but for `Requires.private` field field - `url` a string with a url for the library - `variables` a list of strings with custom variables to add to the diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 4dc87c9..589baf1 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -267,6 +267,8 @@ keyword arguments. - `include_directories`, the directories to add to header search path - `link_args`, link arguments to use - `link_with`, libraries to link against + - `link_whole`, libraries to link fully, same as [`executable`](#executable) + Since 0.46.0 - `sources`, sources to add to targets (or generated header files that should be built before sources including them are built) - `version`, the version of this dependency, such as `1.2.3` @@ -433,7 +435,7 @@ be passed to [shared and static libraries](#library). - `install_dir` override install directory for this file. The value is relative to the `prefix` specified. F.ex, if you want to install plugins into a subdir, you'd use something like this: `install_dir : - get_option('libdir') + '/projectname-1.0'`. + join_paths(get_option('libdir'), 'projectname-1.0'`). - `install_rpath` a string to set the target's rpath to after install (but *not* before that) - `objects` list of prebuilt object files (usually for third party @@ -580,7 +582,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 @@ -613,8 +615,13 @@ Obtains the value of the [project build option](Build-options.md) specified in t Note that the value returned for built-in options that end in `dir` such as `bindir` and `libdir` is always a path relative to (and inside) the `prefix`. + The only exceptions are: `sysconfdir`, `localstatedir`, and `sharedstatedir` -which will return the value passed during configuration as-is. +which will return the value passed during configuration as-is, which may be +absolute, or relative to `prefix`. [`install_dir` arguments](Installing.md) +handles that as expected, but if you need the absolute path to one of these +e.g. to use in a define etc., you should use `join_paths(get_option('prefix'), +get_option('localstatedir')))` ### get_variable() @@ -661,6 +668,10 @@ Note that this function call itself does not add the directories into the search path, since there is no global search path. For something like that, see [`add_project_arguments()`](#add_project_arguments). +See also `implicit_include_directories` parameter of +[executable()](#executable), which adds current source and build directories +to include path. + Each directory given is converted to two include paths: one that is relative to the source root and one relative to the build root. @@ -976,14 +987,20 @@ Project supports the following keyword arguments. runresult run_command(command, list_of_args) ``` -Runs the command specified in positional arguments. Returns [an opaque -object](#run-result-object) containing the result of the -invocation. The script is run from an *unspecified* directory, and +Runs the command specified in positional arguments. +`command` can be a string, or the output of [`find_program()`](#find_program), +[`files()`](#files) or [`configure_file()`](#configure_file), or +[a compiler object](#compiler-object). + +Returns [an opaque object](#run-result-object) containing the result of the +invocation. The command is run from an *unspecified* directory, and Meson will set three environment variables `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT` and `MESON_SUBDIR` that specify the source directory, build directory and subdirectory the target was defined in, respectively. +See also [External commands](External-commands.md). + ### run_target ``` meson @@ -1134,6 +1151,8 @@ subproject. However, if you want to use a dependency object from inside a subproject, an easier way is to use the `fallback:` keyword argument to [`dependency()`](#dependency). +[See additional documentation](Subprojects.md). + ### test() ``` meson @@ -1191,10 +1210,18 @@ be up to date on every build. Keywords are similar to `custom_target`. Meson will read the contents of `input`, substitute the `replace_string` with the detected revision number, and write the -result to `output`. This method returns an opaque -[`custom_target`](#custom_target) object that can be used as -source. If you desire more specific behavior than what this command -provides, you should use `custom_target`. +result to `output`. This method returns a +[`custom_target`](#custom_target) object that (as usual) should be +used to signal dependencies if other targets use the file outputted +by this. + +For example, if you generate a header with this and want to use that in +a build target, you must add the return value to the sources of that +build target. Without that, Meson will not know the order in which to +build the targets. + +If you desire more specific behavior than what this command provides, +you should use `custom_target`. ## Built-in objects @@ -1780,7 +1807,7 @@ opaque object representing it. - `get_variable(name)` fetches the specified variable from inside the subproject. This is useful to, for instance, get a [declared - dependency](#declare_dependency) from the subproject. + dependency](#declare_dependency) from the [subproject](Subprojects.md). ### `run result` object 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..6b24183 100644 --- a/docs/markdown/Release-notes-for-0.45.0.md +++ b/docs/markdown/Release-notes-for-0.45.0.md @@ -1,16 +1,194 @@ --- 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. +## Python minimum version is now 3.5 -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: +Meson will from this version on require Python version 3.5 or newer. - ## Feature name +## Config-Tool based dependencies can be specified in a cross file - A short description explaining the new feature and how it should be used. +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' +``` + +## 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/Subprojects.md b/docs/markdown/Subprojects.md index 0d1442e..ad2aae2 100644 --- a/docs/markdown/Subprojects.md +++ b/docs/markdown/Subprojects.md @@ -77,3 +77,27 @@ subproject `b` and have `b` also use `a`. Meson ships with a dependency system to automatically obtain dependency subprojects. It is documented in the [Wrap dependency system manual](Wrap-dependency-system-manual.md). + +# Why must all subprojects be inside a single directory? + +There are several reasons. + +First of all, to maintain any sort of sanity, the system must prevent going +inside other subprojects with `subdir()` or variations thereof. Having the +subprojects in well defined places makes this easy. If subprojects could be +anywhere at all, it would be a lot harder. + +Second of all it is extremely important that end users can easily see what +subprojects any project has. Because they are in one, and only one, place, +reviewing them becomes easy. + +This is also a question of convention. Since all Meson projects have the same +layout w.r.t subprojects, switching between projects becomes easier. You don't +have to spend time on a new project traipsing through the source tree looking +for subprojects. They are always in the same place. + +Finally if you can have subprojects anywhere, this increases the possibility of +having many different (possibly incompatible) versions of a dependency in your +source tree. Then changing some code (such as changing the order you traverse +directories) may cause a completely different version of the subproject to be +used by accident. diff --git a/docs/markdown/snippets/altered-logging.md b/docs/markdown/snippets/altered-logging.md new file mode 100644 index 0000000..4ff9bb0 --- /dev/null +++ b/docs/markdown/snippets/altered-logging.md @@ -0,0 +1,5 @@ +## Log output slightly changed + +The format of some human-readable diagnostic messages has changed in +minor ways. In case you are parsing these messages, you may need to +adjust your code. diff --git a/docs/markdown/snippets/compiler-object-run_command.md b/docs/markdown/snippets/compiler-object-run_command.md new file mode 100644 index 0000000..0308416 --- /dev/null +++ b/docs/markdown/snippets/compiler-object-run_command.md @@ -0,0 +1,10 @@ +## Compiler object can now be passed to run_command() + +This can be used to run the current compiler with the specified arguments +to obtain additional information from it. +One of the use cases is to get the location of development files for the +GCC plugins: + + cc = meson.get_compiler('c') + result = run_command(cc, '-print-file-name=plugin') + plugin_dev_path = result.stdout().strip() 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/declare_dependency-link_whole.md b/docs/markdown/snippets/declare_dependency-link_whole.md new file mode 100644 index 0000000..827b1f6 --- /dev/null +++ b/docs/markdown/snippets/declare_dependency-link_whole.md @@ -0,0 +1,4 @@ +## declare_dependency() supports link_whole + +`declare_dependency()` supports `link_whole` parameter. +`link_whole` propagates to build target that uses dependency. 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/improved-help.md b/docs/markdown/snippets/improved-help.md new file mode 100644 index 0000000..db7e852 --- /dev/null +++ b/docs/markdown/snippets/improved-help.md @@ -0,0 +1,6 @@ +## "meson help" now shows command line help + +Command line parsing is now less surprising. "meson help" is now +equivalent to "meson --help" and "meson help <subcommand>" is +equivalent to "meson <subcommand> --help", instead of creating a build +directory called "help" in these cases. diff --git a/docs/markdown/snippets/improved-meson-init.md b/docs/markdown/snippets/improved-meson-init.md new file mode 100644 index 0000000..ec17bc4 --- /dev/null +++ b/docs/markdown/snippets/improved-meson-init.md @@ -0,0 +1,19 @@ +## Autogeneration of simple meson.build files + +A feature to generate a meson.build file compiling given C/C++ source +files into a single executable has been added to "meson init". By +default, it will take all recognizable source files in the current +directory. You can also specify a list of dependencies with the -d +flag and automatically invoke a build with the -b flag to check if the +code builds with those dependencies. + +For example, + +```meson +meson init -fbd sdl2,gl +``` + +will look for C or C++ files in the current directory, generate a +meson.build for them with the dependencies of sdl2 and gl and +immediately try to build it, overwriting any previous meson.build and +build directory. 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/pkgconfig-requires-non-string.md b/docs/markdown/snippets/pkgconfig-requires-non-string.md new file mode 100644 index 0000000..abf85b0 --- /dev/null +++ b/docs/markdown/snippets/pkgconfig-requires-non-string.md @@ -0,0 +1,5 @@ +## pkgconfig.generate() requires parameters non-string arguments + +`pkgconfig.generate()` `requires` and `requires_private` parameters +accept pkgconfig-dependencies and libraries that pkgconfig-files were +generated for. 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/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 |