diff options
Diffstat (limited to 'docs')
44 files changed, 623 insertions, 237 deletions
diff --git a/docs/images/gtksample.png b/docs/images/gtksample.png Binary files differindex 1784b77..b6557c4 100644 --- a/docs/images/gtksample.png +++ b/docs/images/gtksample.png diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md index 54905d5..cb7b19e 100644 --- a/docs/markdown/Build-options.md +++ b/docs/markdown/Build-options.md @@ -42,11 +42,16 @@ prefix = get_option('prefix') ``` It should be noted that you can not set option values in your Meson -scripts. They have to be set externally with the `mesonconf` command -line tool. Running `mesonconf` without arguments in a build dir shows -you all options you can set. To change their values use the `-D` +scripts. They have to be set externally with the `meson configure` command +line tool. Running `meson configure` without arguments in a build dir shows +you all options you can set. + +To change their values use the `-D` option: ```console -$ mesonconf -Doption=newvalue +$ meson configure -Doption=newvalue ``` + + +**NOTE:** If you cannot call `meson configure` you likely have a old version of Meson. In that case you can call `mesonconf` instead, but that is deprecated in newer versions diff --git a/docs/markdown/Comparisons.md b/docs/markdown/Comparisons.md index 3c526ad..1deef69 100644 --- a/docs/markdown/Comparisons.md +++ b/docs/markdown/Comparisons.md @@ -2,7 +2,7 @@ title: Comparisons ... -# Comparing Meson with other build systems # +# Comparing Meson with other build systems A common question is *Why should I choose Meson over a different build system X?* There is no one true answer to this as it depends on the @@ -11,37 +11,37 @@ to build medium-to-large projects so the decision is usually made on other points. Here we list some pros and cons of various build systems to help you do the decision yourself. -## GNU Autotools ## +## GNU Autotools -### Pros ### +### Pros Excellent support for legacy Unix platforms, large selection of existing modules. -### Cons ### +### Cons Needlessly slow, complicated, hard to use correctly, unreliable, painful to debug, incomprehensible for most people, poor support for non-Unix platforms (especially Windows). -## CMake ## +## CMake -### Pros ### +### Pros Great support for multiple backends (Visual Studio, XCode, etc). -### Cons ### +### Cons The scripting language is cumbersome to work with. Some simple things are more complicated than necessary. -## SCons ## +## SCons -### Pros ### +### Pros Full power of Python available for defining your build. -### Cons ### +### Cons Slow. Requires you to pass your configuration settings on every invocation. That is, if you do `scons OPT1 OPT2` and then just @@ -51,19 +51,19 @@ previous invocation. ## Bazel -# Pros +### Pros Proven to scale to very large projects. -## Cons +### Cons Implemented in Java. Poor Windows support. Heavily focused on Google's way of doing things (which may be a good or a bad thing). Contributing code requires [signing a CLA](https://bazel.build/contributing.html). -## Meson ## +## Meson -### Pros ### +### Pros The fastest build system [see measurements](Performance-comparison.md), user friendly, designed to @@ -71,7 +71,7 @@ be as invisible to the developer as possible, native support for modern tools (precompiled headers, coverage, Valgrind etc). Not Turing complete so build definition files are easy to read and understand. -### Cons ### +### Cons Relatively new so it does not have a large user base yet, and may thus contain some unknown bugs. Visual Studio and XCode backends not as diff --git a/docs/markdown/Compiler-properties.md b/docs/markdown/Compiler-properties.md index 5978b5d..4def628 100644 --- a/docs/markdown/Compiler-properties.md +++ b/docs/markdown/Compiler-properties.md @@ -29,26 +29,9 @@ Compiler id == The compiler object has a method called `get_id`, which returns a -lower case string describing the "family" of the compiler. It has one -of the following values. - -| Value | Compiler family | -| ----- | ---------------- | -| gcc | The GNU Compiler Collection | -| clang | The Clang compiler | -| msvc | Microsoft Visual Studio | -| intel | Intel compiler | -| llvm | LLVM-based compiler (Swift, D) | -| mono | Xamarin C# compiler | -| dmd | D lang reference compiler | -| rustc | Rust compiler | -| valac | Vala compiler | -| pathscale | The Pathscale Fortran compiler | -| pgi | The Portland Fortran compiler | -| sun | Sun Fortran compiler | -| g95 | The G95 Fortran compiler | -| open64 | The Open64 Fortran Compiler | -| nagfor | The NAG Fortran compiler | +lower case string describing the "family" of the compiler. See +[reference tables](Reference-tables.md) for a list of supported +compiler ids. Does code compile? == @@ -120,12 +103,12 @@ The `result` variable encapsulates the state of the test, which can be extracted with the following methods. The `name` keyword argument works the same as with `compiles`. -| Method | Return value -| ------ | ------------ -| compiled | `True` if compilation succeeded. If `false` then all other methods return undefined values. -| returncode | The return code of the application as an integer -| stdout | Program's standard out as text. -| stderr | Program's standard error as text. +| Method | Return value | +| ------ | ------------ | +| compiled | `True` if compilation succeeded. If `false` then all other methods return undefined values. | +| returncode | The return code of the application as an integer | +| stdout | Program's standard out as text. | +| stderr | Program's standard error as text. | Here is an example usage: diff --git a/docs/markdown/Configuring-a-build-directory.md b/docs/markdown/Configuring-a-build-directory.md index edf3d97..774addf 100644 --- a/docs/markdown/Configuring-a-build-directory.md +++ b/docs/markdown/Configuring-a-build-directory.md @@ -9,11 +9,11 @@ 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 `mesonconf` script. You may also use the +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. -You invoke `mesonconf` by giving it the location of your build dir. If +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 sample output for a simple project. @@ -56,7 +56,7 @@ the option. To set an option you use the `-D` option. For example, changing the installation prefix from `/usr/local` to `/tmp/testroot` you would issue the following command. - mesonconf -Dprefix=/tmp/testroot + meson configure -Dprefix=/tmp/testroot Then you would run your build command (usually `ninja`), which would cause Meson to detect that the build setup has changed and do all the diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md index e232033..f68b1f5 100644 --- a/docs/markdown/Cross-compilation.md +++ b/docs/markdown/Cross-compilation.md @@ -69,6 +69,7 @@ c = '/usr/bin/i586-mingw32msvc-gcc' cpp = '/usr/bin/i586-mingw32msvc-g++' ar = '/usr/i586-mingw32msvc/bin/ar' strip = '/usr/i586-mingw32msvc/bin/strip' +pkgconfig = '/usr/bin/i586-mingw32msvc-pkg-config' exe_wrapper = 'wine' # A command used to run generated executables. ``` diff --git a/docs/markdown/Custom-build-targets.md b/docs/markdown/Custom-build-targets.md index 8bd31db..30a16e3 100644 --- a/docs/markdown/Custom-build-targets.md +++ b/docs/markdown/Custom-build-targets.md @@ -27,7 +27,7 @@ This would generate the binary `output.bin` and install it to `${prefix}/subdir/output.bin`. Variable substitution works just like it does for source generation. -## Details on compiler invocations ## +## Details on compiler invocations Meson only permits you to specify one command to run. This is by design as writing shell pipelines into build definition files leads to diff --git a/docs/markdown/D.md b/docs/markdown/D.md new file mode 100644 index 0000000..7b0d485 --- /dev/null +++ b/docs/markdown/D.md @@ -0,0 +1,89 @@ +--- +title: D +short-description: Compiling D sources +... + +# Compiling D applications + +Meson has support for compiling D programs. A minimal `meson.build` file for D looks like this: + +```meson +project('myapp', 'd') + +executable('myapp', 'app.d') +``` + +## Compiling different versions + +If you are using the [version()](https://dlang.org/spec/version.html) feature for conditional compilation, you can use it using the `d_module_versions` +target property: +```meson +project('myapp', 'd') +executable('myapp', 'app.d', d_module_versions: ['Demo', 'FeatureA']) +``` + +## Using embedded unittests + +If you are using embedded [unittest functions](https://dlang.org/spec/unittest.html), your source code needs to be compiled twice, once in regular +mode, and once with unittests active. This is done by setting the `d_unittest` target property to `true`. +Meson will only ever pass the respective compiler's `-unittest` flag, and never have the compiler generate an empty main function. +If you need that feature in a portable way, create an empty `main()` function for unittests yourself, since the GNU D compiler +does not have this feature. + +This is an example for using D unittests with Meson: +```meson +project('myapp_tested', 'd') + +myapp_src = ['app.d', 'alpha.d', 'beta.d'] +executable('myapp', myapp_src) + +test_exe = executable('myapp_test', myapp_src, d_unittest: true) +test('myapptest', test_exe) +``` + +# Compiling D libraries and installing them + +Building D libraries is a straightforward process, not different from how C libraries are built in Meson. You should generate a pkg-config file +and install it, in order to make other software on the system find the dependency once it is installed. + +This is an example on how to build a D shared library: +```meson +project('mylib', 'd', version: '1.2.0') + +project_soversion = 0 +glib_dep = dependency('glib-2.0') + +my_lib = library('mylib', + ['src/mylib/libfunctions.d'], + dependencies: [glib_dep], + install: true, + version: meson.project_version(), + soversion: project_soversion, + d_module_versions: ['FeatureA', 'featureB'] +) +pkgc.generate(name: 'mylib', + libraries: my_lib, + subdirs: 'd/mylib', + version: meson.project_version(), + description: 'A simple example D library.', + d_module_versions: ['FeatureA'] +) +install_subdir('src/mylib/', install_dir: 'include/d/mylib/') +``` + +It is important to make the D sources install in a subdirectory in the include path, in this case `/usr/include/d/mylib/mylib`. +All D compilers include the `/usr/include/d` directory by default, and if your library would be installed into `/usr/include/d/mylib`, there +is a high chance that, when you compile your project again on a machine where you installed it, the compiler will prefer the old installed include over +the new version in the source tree, leading to very confusing errors. + +This is an example of how to use the D library we just built and installed in an application: +```meson +project('myapp', 'd') + +mylib_dep = dependency('mylib', version: '>= 1.2.0') +myapp_src = ['app.d', 'alpha.d', 'beta.d'] +executable('myapp', myapp_src, dependencies: [mylib_dep]) +``` + +Please keep in mind that the library and executable would both need to be built with the exact same D compiler and D compiler version. The D ABI is not +stable across compilers and their versions, and mixing compilers will lead to problems. diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index 187c4fe..8e780d6 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -45,13 +45,66 @@ non-found dependencies. 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. +pkg-config files. Meson has autodetection support for some of these, +and they are described later on this page. -## Boost ## +# Declaring your own + +You can declare your own dependency objects that can be used +interchangeably with dependency objects obtained from the system. The +syntax is straightforward: + +```meson +my_inc = include_directories(...) +my_lib = static_library(...) +my_dep = declare_dependency(link_with : my_lib, + include_directories : my_inc) +``` + +This declares a dependency that adds the given include directories and +static library to any target you use it in. + +# Building dependencies as subprojects + +Many platforms do not provide a system package manager. On these +systems dependencies must be compiled from source. Meson's subprojects +make it simple to use system dependencies when they are available and +to build dependencies manually when they are not. + +To make this work, the dependency must have Meson build definitions +and it must declare its own dependency like this: + + foo_dep = declare_dependency(...) + +Then any project that wants to use it can write out the following +declaration in their main `meson.build` file. + + foo_dep = dependency('foo', fallback : ['foo', 'foo_dep']) + +What this declaration means is that first Meson tries to look up the +dependency from the system (such as by using pkg-config). If it is not +available, then it builds subproject named `foo` and from that +extracts a variable `foo_dep`. That means that the return value of +this function is either an external or an internal dependency +object. Since they can be used interchangeably, the rest of the build +definitions do not need to care which one it is. Meson will take care +of all the work behind the scenes to make this work. + +# Dependencies with custom lookup functionality + +## Boost Boost is not a single dependency but rather a group of different -libraries. To use Boost with Meson, simply list which Boost modules -you would like to use. +libraries. To use Boost headers-only libraries, simply add Boost as a +dependency. + +```meson +boost_dep = dependency('boost') +exe = executable('myprog', 'file.cc', dependencies : boost_dep) +``` + +To link against boost with Meson, simply list which libraries you would like to +use. ```meson boost_dep = dependency('boost', modules : ['thread', 'utility']) @@ -65,7 +118,10 @@ If your boost headers or libraries are in non-standard locations you can set the BOOST_ROOT, BOOST_INCLUDEDIR, and/or BOOST_LIBRARYDIR environment variables. -## GTest and GMock ## +You can set the argument `threading` to `single` to use boost libraries that +has been compiled for single-threaded use instead. + +## GTest and GMock GTest and GMock come as sources that must be compiled as part of your project. With Meson you don't have to care about the details, just @@ -73,7 +129,7 @@ pass `gtest` or `gmock` to `dependency` and it will do everything for you. If you want to use GMock, it is recommended to use GTest as well, as getting it to work standalone is tricky. -## MPI ## +## MPI MPI is supported for C, C++ and Fortran. Because dependencies are language-specific, you must specify the requested language using the @@ -89,7 +145,7 @@ are not in your path, they can be specified by setting the standard environment variables `MPICC`, `MPICXX`, `MPIFC`, `MPIF90`, or `MPIF77`, during configuration. -## Qt5 ## +## Qt5 Meson has native Qt5 support. Its usage is best demonstrated with an example. @@ -142,18 +198,12 @@ automatically: cups_dep = dependency('cups', version : '>=1.4') ``` -## Declaring your own +## LibWMF -You can declare your own dependency objects that can be used -interchangeably with dependency objects obtained from the system. The -syntax is straightforward: +The libwmf library does not ship with pkg-config at the time or writing +but instead it has its own `libwmf-config` util. Meson will use it +automatically: ```meson -my_inc = include_directories(...) -my_lib = static_library(...) -my_dep = declare_dependency(link_with : my_lib, - include_directories : my_inc) +libwmf_dep = dependency('libwmf', version : '>=0.2.8') ``` - -This declares a dependency that adds the given include directories and -static library to any target you use it in. diff --git a/docs/markdown/Design-rationale.md b/docs/markdown/Design-rationale.md index 269f688..7cf67a4 100644 --- a/docs/markdown/Design-rationale.md +++ b/docs/markdown/Design-rationale.md @@ -67,7 +67,7 @@ need to solve? What sort of solutions would be the most appropriate? To get things started, here is a list of requirements any modern cross-platform build system needs to provide. -###1. Must be simple to use### +### 1. Must be simple to use One of the great virtues of Python is the fact that it is very readable. It is easy to see what a given block of code does. It is @@ -76,7 +76,7 @@ be syntactically and semantically clean. Side effects, global state and interrelations must be kept at a minimum or, if possible, eliminated entirely. -###2. Must do the right thing by default### +### 2. Must do the right thing by default Most builds are done by developers working on the code. Therefore the defaults must be tailored towards that use case. As an example the @@ -85,7 +85,7 @@ information. It shall make binaries that can be run directly from the build directory without linker tricks, shell scripts or magic environment variables. -###3. Must enforce established best practices### +### 3. Must enforce established best practices There really is no reason to compile source code without the equivalent of `-Wall`. So enable it by default. A different kind of @@ -94,7 +94,7 @@ directories. All build artifacts must be stored in the build directory. Writing stray files in the source directory is not permitted under any circumstances. -###4. Must have native support for platforms that are in common use### +### 4. Must have native support for platforms that are in common use A lot of free software projects can be used on non-free platforms such as Windows or OSX. The system must provide native support for the @@ -102,10 +102,10 @@ tools of choice on those platforms. In practice this means native support for Visual Studio and XCode. Having said IDEs invoke external builder binaries does not count as native support. -###5. Must not add complexity due to obsolete platforms### +### 5. Must not add complexity due to obsolete platforms -Work on this build system started during the Christmas holidays of -2012. This provides a natural hard cutoff line of 2012/12/24. Any +Work on this build system started during the Christmas holidays of 2012. +This provides a natural hard cutoff line of 2012/12/24. Any platform, tool or library that was not in active use at that time is explicitly not supported. These include Unixes such as IRIX, SunOS, OSF-1, Ubuntu versions older than 12/10, GCC versions older than 4.7 @@ -113,20 +113,20 @@ and so on. If these old versions happen to work, great. If they don't, not a single line of code will be added to the system to work around their bugs. -###6. Must be fast### +### 6. Must be fast Running the configuration step on a moderate sized project must not take more than five seconds. Running the compile command on a fully up to date tree of 1000 source files must not take more than 0.1 seconds. -###7. Must provide easy to use support for modern sw development features### +### 7. Must provide easy to use support for modern sw development features An example is precompiled headers. Currently no free software build system provides native support for them. Other examples could include easy integration of Valgrind and unit tests, test coverage reporting and so on. -###8. Must allow override of default values### +### 8. Must allow override of default values Sometimes you just have to compile files with only given compiler flags and no others, or install files in weird places. The system must diff --git a/docs/markdown/FAQ.md b/docs/markdown/FAQ.md index 2d28137..441cd69 100644 --- a/docs/markdown/FAQ.md +++ b/docs/markdown/FAQ.md @@ -98,7 +98,7 @@ The only reason why one would use Make instead of Ninja is working on a platform 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? ## +## 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?* @@ -144,7 +144,7 @@ This defaults to `c++11` on GCC compilers. Suppose you want to use `c++14` inste 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 `mesonconf` 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. ## Does wrap download sources behind my back? diff --git a/docs/markdown/Generating-sources.md b/docs/markdown/Generating-sources.md index c251805..ae1302b 100644 --- a/docs/markdown/Generating-sources.md +++ b/docs/markdown/Generating-sources.md @@ -31,7 +31,7 @@ gen_src = custom_target('gen-output', '--h-out', '@OUTPUT1@']) ``` -The `@INPUT@` there will be transformed to `'out.c' 'out.h'`. 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. diff --git a/docs/markdown/Getting-meson.md b/docs/markdown/Getting-meson.md index d654ff3..8664d61 100644 --- a/docs/markdown/Getting-meson.md +++ b/docs/markdown/Getting-meson.md @@ -5,7 +5,7 @@ Meson releases can be downloaded from the [GitHub release page]. Meson is also available in the [Python Package Index] and can be -installed with <tt>pip3 install meson</tt>. +installed with `pip3 install meson`. The newest development code can be obtained directly from [Git] diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md index 99a9c8e..738e2a9 100644 --- a/docs/markdown/Gnome-module.md +++ b/docs/markdown/Gnome-module.md @@ -30,29 +30,19 @@ file called `foobar.h`, which you can then include in your sources. * `c_name`: passed to the resource compiler as an argument after `--c-name` - * `dependencies`: extra targets to depend upon for building - * `export`: (*Added 0.37.0*) if true, export the symbols of the generated sources - * `extra_args`: extra command line arguments to pass to the resource - * `gresource_bundle`: (*Added 0.37.0*) if true, output a `.gresource` file instead of source - * `install`: (*Added 0.37.0*) if true, install the gresource file - * `install_dir`: (*Added 0.37.0*) location to install the header or bundle depending on previous options - * `install_header`: (*Added 0.37.0*) if true, install the header file - * `source_dir`: a list of subdirectories where the resource compiler should look up the files, relative to the location of the XML file - compiler - Returns an array containing: `[c_source, header_file]` or `[gresource_bundle]` @@ -64,36 +54,26 @@ keyword arguments. Many of these map directly to the `g-ir-scanner` tool so see its documentation for more information. * `dependencies`: deps to use during introspection scanning - * `extra_args`: command line arguments to pass to gir compiler - * `export_packages`: extra packages the gir file exports - * `sources`: the list of sources to be scanned for gir data - * `nsversion`: namespace version - * `namespace`: the namespace for this gir object which determines output files - * `identifier_prefix`: the identifier prefix for the gir object, e.g. `Gtk` - * `includes`: list of gir names to be included, can also be a GirTarget - +* `header`: *(Added 0.43.0)* name of main c header to include for the library, e.g. `glib.h` +* `dependencies`: deps to use during introspection scanning * `include_directories`: extra include paths to look for gir files - * `install`: if true, install the generated files - * `install_dir_gir`: (*Added 0.35.0*) which directory to install the gir file into - * `install_dir_typelib`: (*Added 0.35.0*) which directory to install the typelib file into - * `link_with`: list of libraries to link with - -* `symbol_prefix`: the symbol prefix for the gir object, e.g. `gtk` +* `symbol_prefix`: the symbol prefix for the gir object, e.g. `gtk`, + (*Since 0.43.0*) an ordered list of multiple prefixes is allowed Returns an array of two elements which are: `[gir_target, typelib_target]` diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index d2a3e9c..f7939dd 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -34,7 +34,7 @@ The next thing to display is the list of options that can be set. These include mesonintrospect.py --buildoptions -To set the options, use the `mesonconf.py` binary. +To set the options, use the `meson configure` command. Compilation and unit tests are done as usual by running the `ninja` and `ninja test` commands. A JSON formatted result log can be found in `workspace/project/builddir/meson-logs/testlog.json`. diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md index 3454d49..2663ff4 100644 --- a/docs/markdown/Installing.md +++ b/docs/markdown/Installing.md @@ -44,7 +44,7 @@ giving an absolute install path. install_data(sources : 'foo.dat', install_dir : '/etc') # -> /etc/foo.dat ``` -## Custom install behavior ## +## Custom install behavior Sometimes you need to do more than just install basic targets. Meson makes this easy by allowing you to specify a custom script to execute at install time. As an example, here is a script that generates an empty file in a custom directory. @@ -65,7 +65,7 @@ meson.add_install_script('myscript.sh') The argument is the name of the script file relative to the current subdirectory. -## DESTDIR support ## +## DESTDIR support Sometimes you need to install to a different directory than the install prefix. This is most common when building rpm or deb packages. This is done with the `DESTDIR` environment variable and it is used just like with other build systems: diff --git a/docs/markdown/Module-reference.md b/docs/markdown/Module-reference.md index 80e3b8f..60be7bd 100644 --- a/docs/markdown/Module-reference.md +++ b/docs/markdown/Module-reference.md @@ -17,4 +17,4 @@ change in arbitrary ways between releases. The modules might also be removed without warning in future releases. * [SIMD](Simd-module.md) -
\ No newline at end of file + diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md index 5a660fd..7f767f1 100644 --- a/docs/markdown/Pkgconfig-module.md +++ b/docs/markdown/Pkgconfig-module.md @@ -41,3 +41,5 @@ keyword arguments. e.g. `datadir=${prefix}/share`. The names `prefix`, `libdir` and `installdir` are reserved and may not be used. - `version` a string describing the version of this library +- `d_module_versions` a list of module version flags used when compiling + D sources referred to by this pkg-config file diff --git a/docs/markdown/Precompiled-headers.md b/docs/markdown/Precompiled-headers.md index 22fd762..57b2923 100644 --- a/docs/markdown/Precompiled-headers.md +++ b/docs/markdown/Precompiled-headers.md @@ -40,7 +40,7 @@ Toggling the usage of precompiled headers If you wish to compile your project without precompiled headers, you can change the value of the pch option by passing `-Db_pch=false` -argument to Meson at configure time or later with `mesonconf`. You can +argument to Meson at configure time or later with `meson configure`. You can also toggle the use of pch in a configured build directory with the GUI tool. You don't have to do any changes to the source code. Typically this is done to test whether your project compiles diff --git a/docs/markdown/Qt5-module.md b/docs/markdown/Qt5-module.md index 7082309..aea2ae1 100644 --- a/docs/markdown/Qt5-module.md +++ b/docs/markdown/Qt5-module.md @@ -5,17 +5,24 @@ tools and steps required for Qt. The module has one method. ## preprocess -This method takes four keyword arguments, `moc_headers`, -`moc_sources`, `ui_files` and `qresources` which define the files that -require preprocessing with `moc`, `uic` and `rcc`. It returns an -opaque object that should be passed to a main build target. A simple -example would look like this: +This method takes the following keyword arguments: + - `moc_headers`, `moc_sources`, `ui_files`, `qresources`, which define the files that require preprocessing with `moc`, `uic` and `rcc` + - `include_directories`, the directories to add to header search path for `moc` (optional) + - `moc_extra_arguments`, any additional arguments to `moc` (optional). Available since v0.44.0. + +It returns an opaque object that should be passed to a main build target. + +A simple example would look like this: ```meson qt5 = import('qt5') qt5_dep = dependency('qt5', modules: ['Core', 'Gui']) -moc_files = qt5.preprocess(moc_headers : 'myclass.h') +inc = include_directories('includes') +moc_files = qt5.preprocess(moc_headers : 'myclass.h', + moc_extra_arguments: ['-DMAKES_MY_MOC_HEADER_COMPILE'], + include_directories: inc) executable('myprog', 'main.cpp', 'myclass.cpp', moc_files, + include_directories: inc, dependencies : qt5_dep) ``` diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 9d9111e..92c8a1f 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -95,10 +95,10 @@ the following: - `gdb` if `true`, the tests are also run under `gdb` - `timeout_multiplier` a number to multiply the test timeout with -To use the test setup, run `mesontest --setup=*name*` inside the build dir. +To use the test setup, run `meson test --setup=*name*` inside the build dir. Note that all these options are also available while running the -`mesontest` script for running tests instead of `ninja test` or +`meson test` script for running tests instead of `ninja test` or `msbuild RUN_TESTS.vcxproj`, etc depending on the backend. ### benchmark() @@ -201,10 +201,15 @@ following. to the target file. Note that your command argument list may not contain `@OUTPUT@` when capture mode is active. - `command` command to run to create outputs from inputs. The command - may be strings or the return of `find_program()` or `executable()` - (note: always specify commands in array form `['commandname', + may be strings or the return value of functions that return file-like + objects such as [`find_program()`](#find_program), + [`executable()`](#executable), [`configure_file()`](#configure_file), + [`files()`](#files), [`custom_target()`](#custom_target), etc. + Meson will automatically insert the appropriate dependencies on + targets and files listed in this keyword argument. + Note: always specify commands in array form `['commandname', '-arg1', '-arg2']` rather than as a string `'commandname -arg1 - -arg2'` as the latter will *not* work) + -arg2'` as the latter will *not* work. - `depend_files` files ([`string`](#string-object), [`files()`](#files), or [`configure_file()`](#configure_file)) that this target depends on but are not listed in the `command` keyword @@ -424,6 +429,10 @@ be passed to [shared and static libraries](#library). - `override_options` takes an array of strings in the same format as `project`'s `default_options` overriding the values of these options for this target only, since 0.40.0 +- `d_import_dirs` list of directories to look in for string imports used + in the D programmling language +- `d_unittest`, when set to true, the D modules are compiled in debug mode +- `d_module_versions` list of module versions set when compiling D sources The list of `sources`, `objects`, and `dependencies` is always flattened, which means you can freely nest and add lists while @@ -545,6 +554,9 @@ following: - `output` a template string (or list of template strings) defining how an output file name is (or multiple output names are) generated from a single source file name +- `capture` when this argument is set to true, Meson captures `stdout` + of the `executable` and writes it to the target file specified as + `output`. Available since v0.43.0. The returned object also has methods that are documented in the [object methods section](#generator-object) below. @@ -808,10 +820,19 @@ static with only one option. The keyword arguments for this are the same as for [`executable`](#executable) with the following additions: -- `name_prefix` the string that will be used as the suffix for the - target by overriding the default (only used for libraries). By - default this is `lib` on all platforms and compilers except with - MSVC where it is omitted. +- `name_prefix` the string that will be used as the prefix for the + target output filename by overriding the default (only used for + libraries). By default this is `lib` on all platforms and compilers + except with MSVC shared libraries where it is omitted to follow + convention. +- `name_suffix` the string that will be used as the suffix for the + target output filename by overriding the default (see also: + [executable()](#executable)). By default, for shared libraries this + is `dylib` on macOS, `dll` on Windows, and `so` everywhere else. + For static libraries, it is `a` everywhere. By convention MSVC + static libraries use the `lib` suffix, but we use `a` to avoid a + potential name clash with shared libraries which also generate + `xxx.lib` import files. - `rust_crate_type` specifies the crate type for Rust libraries. Defaults to `dylib` for shared libraries and `rlib` for static libraries. @@ -826,6 +847,14 @@ The keyword arguments for this are the same as for [`executable`](#executable) w This function prints its argument to stdout. +### warning() + +``` meson + void warning(text) +``` + +This function prints its argument to stdout prefixed with WARNING:. + ### project() ``` meson @@ -835,7 +864,7 @@ This function prints its argument to stdout. The first argument to this function must be a string defining the name of this project. It is followed by programming languages that the project uses. Supported values for languages are `c`, `cpp` (for -`C++`), `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`) and +`C++`), `d`, `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`) and `vala`. In versions before `0.40.0` you must have at least one language listed. @@ -850,7 +879,7 @@ Project supports the following keyword arguments. - `default_options` takes an array of strings. The strings are in the form `key=value` and have the same format as options to - `mesonconf`. For example to set the default project type you would + `meson configure`. For example to set the default project type you would set this: `default_options : ['buildtype=debugoptimized']`. Note that these settings are only used when running Meson for the first time. Global options such as `buildtype` can only be specified in @@ -1063,7 +1092,7 @@ arguments are the following. for the test Defined tests can be run in a backend-agnostic way by calling -`mesontest` inside the build dir, or by using backend-specific +`meson test` inside the build dir, or by using backend-specific commands, such as `ninja test` or `msbuild RUN_TESTS.vcxproj`. ### vcs_tag() @@ -1300,9 +1329,9 @@ the following methods: - `get_id()` returns a string identifying the compiler. For example, `gcc`, `msvc`, [and more](Compiler-properties.md#compiler-id). -- `get_supported_arguments(list_of_string)` returns an array - containing only the arguments supported by the compiler, as if - `has_argument` were called on them individually. +- `get_supported_arguments(list_of_string)` *(added 0.43.0)* returns + an array containing only the arguments supported by the compiler, + as if `has_argument` were called on them individually. - `has_argument(argument_name)` returns true if the compiler accepts the specified command line argument, that is, can compile code @@ -1432,6 +1461,8 @@ are immutable, all operations return their results as a new string. specified as the argument - `strip()` removes whitespace at the beginning and end of the string + *(added 0.43.0)* optionally can take one positional string argument, + and all characters in that string will be stripped - `to_int` returns the string converted to an integer (error if string is not a number) @@ -1502,7 +1533,10 @@ A build target is either an [executable](#executable), files with custom flags. To use the object file(s) in another build target, use the `objects:` keyword argument. -- `full_path()` returns a full path pointing to the result target file +- `full_path()` returns a full path pointing to the result target file. + NOTE: In most cases using the object itself will do the same job as + this and will also allow Meson to setup inter-target dependencies + correctly. Please file a bug if that doesn't work for you. - `private_dir_include()` returns a opaque value that works like `include_directories` but points to the private directory of this @@ -1554,6 +1588,14 @@ This object is returned by [`custom_target`](#custom_target) and contains a target with the following methods: - `full_path()` returns a full path pointing to the result target file + NOTE: In most cases using the object itself will do the same job as + this and will also allow Meson to setup inter-target dependencies + correctly. Please file a bug if that doesn't work for you. + +- `[index]` returns an opaque object that references this target, and can be + used as a source in other targets. When it is used as such it will make that + target depend on this custom target, but the only source added will be the + one that corresponds to the index of the custom target's output argument. ### `dependency` object @@ -1594,7 +1636,7 @@ during tests. It should be passed as the `env` keyword argument to tests. It has the following methods. - `append(varname, value)` appends the given value to the old value of - the environment variable, e.g. `env.append'('FOO', 'BAR', separator + the environment variable, e.g. `env.append('FOO', 'BAR', separator : ';')` produces `BOB;BAR` if `FOO` had the value `BOB` and plain `BAR` if the value was not defined. If the separator is not specified explicitly, the default path separator for the host diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md new file mode 100644 index 0000000..b604fb6 --- /dev/null +++ b/docs/markdown/Reference-tables.md @@ -0,0 +1,60 @@ +# Reference tables + +## Compiler ids + +These are return values of the `get_id` method in a compiler object. + +| Value | Compiler family | +| ----- | ---------------- | +| gcc | The GNU Compiler Collection | +| clang | The Clang compiler | +| msvc | Microsoft Visual Studio | +| intel | Intel compiler | +| llvm | LLVM-based compiler (Swift, D) | +| mono | Xamarin C# compiler | +| dmd | D lang reference compiler | +| rustc | Rust compiler | +| valac | Vala compiler | +| pathscale | The Pathscale Fortran compiler | +| pgi | The Portland Fortran compiler | +| sun | Sun Fortran compiler | +| g95 | The G95 Fortran compiler | +| open64 | The Open64 Fortran Compiler | +| nagfor | The NAG Fortran compiler | + +## Script environment variables + +| Value | Comment | +| ----- | ------- | +| MESON_SOURCE_ROOT | Absolute path to the source dir | +| MESON_BUILD_ROOT | Absolute path to the build dir | +| MESONINTROSPECT | Command to run to run the introspection command, may be of the form `python /path/to/meson introspect`, user is responsible for splitting the path if necessary. | +| MESON_SUBDIR | Current subdirectory, only set for `run_command` | + +## CPU families + +These are returned by the `cpu_family` method of `build_machine`, +`host_machine` and `target_machine`. For cross compilation they are +set in the cross file. + +| Value | Comment | +| ----- | ------- | +| x86 | 32 bit x86 processor | +| x86_64 | 64 bit x86 processor | +| arm | 32 bit ARM processor | + +Any cpu family not listed in the above list is not guaranteed to +remain stable in future releases. + +## Operating system names + +These are provided by the `.system()` method call. + +| Value | Comment | +| ----- | ------- | +| linux | | +| darwin | Either OSX or iOS | +| windows | Any version of Windows | + +Any string not listed above is not guaranteed to remain stable in +future releases.
\ No newline at end of file diff --git a/docs/markdown/Release-notes-for-0.43.0.md b/docs/markdown/Release-notes-for-0.43.0.md index 0cb8cc1..3f981e8 100644 --- a/docs/markdown/Release-notes-for-0.43.0.md +++ b/docs/markdown/Release-notes-for-0.43.0.md @@ -3,14 +3,121 @@ title: Release 0.43 short-description: Release notes for 0.43 (preliminary) ... -# New features +# Portability improvements to Boost Dependency -This page is a placeholder for the eventual release notes. +The Boost dependency has been improved to better detect the various ways to +install boost on multiple platforms. At the same time the `modules` semantics +for the dependency has been changed. Previously it was allowed to specify +header directories as `modules` but it wasn't required. Now, modules are only +used to specify libraries that require linking. -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: +This is a breaking change and the fix is to remove all modules that aren't +found. - # Feature name +# Generator learned capture - A short description explaining the new feature and how it should be used. +Generators can now be configured to capture the standard output. See +`test cases/common/98 gen extra/meson.build` for an example. + +# Can index CustomTarget objects + +The `CustomTarget` object can now be indexed like an array. The resulting +object can be used as a source file for other Targets, this will create a +dependency on the original `CustomTarget`, but will only insert the generated +file corresponding to the index value of the `CustomTarget`'s `output` keyword. + +```meson +c = custom_target( + ... + output : ['out.h', 'out.c'], +) +lib1 = static_library( + 'lib1', + [lib1_sources, c[0]], + ... +) +exec = executable( + 'executable', + c[1], + link_with : lib1, +) +``` + +# Can override executables in the cross file + +The cross file can now be used for overriding the result of +`find_program`. As an example if you want to find the `objdump` +command and have the following definition in your cross file: + +```ini +[binaries] +... +objdump = '/usr/bin/arm-linux-gnueabihf-objdump-6' +``` + +Then issuing the command `find_program('objdump')` will return the +version specified in the cross file. If you need the build machine's +objdump, you can specify the `native` keyword like this: + +```meson +native_objdump = find_program('objdump', native : true) +``` + +# Easier handling of supported compiler arguments + +A common pattern for handling multiple desired compiler arguments, was to +test their presence and add them to an array one-by-one, e.g.: + +```meson +warning_flags_maybe = [ + '-Wsomething', + '-Wanother-thing', + '-Wno-the-other-thing', +] +warning_flags = [] +foreach flag : warning_flags_maybe + if cc.has_argument(flag) + warning_flags += flag + endif +endforeach +cc.add_project_argument(warning_flags) +``` + +A helper has been added for the foreach/has_argument pattern, so you can +now simply do: + +```meson +warning_flags = [ ... ] +flags = cc.get_supported_arguments(warning_flags) +``` + +# Better support for shared libraries in non-system paths + +Meson has support for prebuilt object files and static libraries. +This release adds feature parity to shared libraries that are either +in non-standard system paths or shipped as part of your project. On +systems that support rpath, Meson automatically adds rpath entries +to built targets using manually found external libraries. + +This means that e.g. supporting prebuilt libraries shipped with your +source or provided by subprojects or wrap definitions by writing a +build file like this: + +```meson +project('myprebuiltlibrary', 'c') + +cc = meson.get_compiler('c') +prebuilt = cc.find_library('mylib', dirs : meson.current_source_dir()) +mydep = declare_dependency(include_directories : include_directories('.'), + dependencies : prebuilt) +``` + +Then you can use the dependency object in the same way as any other. + +# wrap-svn + +The [Wrap dependency system](Wrap-dependency-system-manual.md) now +supports [Subversion](https://subversion.apache.org/) (svn). This +support is rudimentary. The repository url has to point to a specific +(sub)directory containing the `meson.build` file (typically +`trunk/`). However, providing a `revision` is supported. diff --git a/docs/markdown/Release-notes-for-0.44.0.md b/docs/markdown/Release-notes-for-0.44.0.md new file mode 100644 index 0000000..0df2e97 --- /dev/null +++ b/docs/markdown/Release-notes-for-0.44.0.md @@ -0,0 +1,16 @@ +--- +title: Release 0.44 +short-description: Release notes for 0.44 (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 85453e3..923b6a3 100644 --- a/docs/markdown/Subprojects.md +++ b/docs/markdown/Subprojects.md @@ -42,7 +42,7 @@ else l = sp.get_variable('l') endif exe = executable('prog', 'prog.c', include_directories : i, link_with : l, - deps : dep, install : true) + dependencies : dep, install : true) ``` With this setup the system dependency is used when it is available, otherwise we fall back on the bundled version. diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index 02db228..88b9bbb 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -4,23 +4,39 @@ short-description: Syntax and structure of Meson files # Syntax -The syntax of Meson's specification language has been kept as simple as possible. It is *strongly typed* so no object is ever converted to another under the covers. Variables have no visible type which makes Meson *dynamically typed* (also known as *duck typed*). - -The main building blocks of the language are *variables*, *numbers*, *booleans*, *strings*, *arrays*, *function calls*, *method calls*, *if statements* and *includes*. - -Usually one Meson statement takes just one line. There is no way to have multiple statements on one line as in e.g. *C*. Function and method calls' argument lists can be split over multiple lines. Meson will autodetect this case and do the right thing. In other cases you can get multi-line statements by ending the line with a `\`. Apart from line ending whitespace has no syntactic meaning. +The syntax of Meson's specification language has been kept as simple +as possible. It is *strongly typed* so no object is ever converted to +another under the covers. Variables have no visible type which makes +Meson *dynamically typed* (also known as *duck typed*). + +The main building blocks of the language are *variables*, *numbers*, +*booleans*, *strings*, *arrays*, *function calls*, *method calls*, *if +statements* and *includes*. + +Usually one Meson statement takes just one line. There is no way to +have multiple statements on one line as in e.g. *C*. Function and +method calls' argument lists can be split over multiple lines. Meson +will autodetect this case and do the right thing. In other cases you +can get multi-line statements by ending the line with a `\`. Apart +from line ending whitespace has no syntactic meaning. Variables -- -Variables in Meson work just like in other high level programming languages. A variable can contain a value of any type, such as an integer or a string. Variables don't need to be predeclared, you can just assign to them and they appear. Here's how you would assign values to two different variables. +Variables in Meson work just like in other high level programming +languages. A variable can contain a value of any type, such as an +integer or a string. Variables don't need to be predeclared, you can +just assign to them and they appear. Here's how you would assign +values to two different variables. ```meson var1 = 'hello' var2 = 102 ``` -One important difference in how variables work in Meson is that all variables are immutable. This is different from, for example, how Python works. +One important difference in how variables work in Meson is that all +objects are immutable. This is different from, for example, how Python +works. ```meson var1 = [1, 2, 3] @@ -33,7 +49,8 @@ var2 += [4] Numbers -- -Meson supports only integer numbers. They are declared simply by writing them out. Basic arithmetic operations are supported. +Meson supports only integer numbers. They are declared simply by +writing them out. Basic arithmetic operations are supported. ```meson x = 1 + 2 @@ -45,7 +62,7 @@ Strings can be converted to a number like this: ```meson string_var = '42' -num = var1.to_int() +num = string_var.to_int() ``` Booleans @@ -60,13 +77,15 @@ truth = true Strings -- -Strings in Meson are declared with single quotes. To enter a literal single quote do it like this: +Strings in Meson are declared with single quotes. To enter a literal +single quote do it like this: ```meson single quote = 'contains a \' character' ``` -Similarly `\n` gets converted to a newline and `\\\\` to a single backslash. +Similarly `\n` gets converted to a newline and `\\\\` to a single +backslash. #### String concatenation @@ -80,7 +99,8 @@ combined = str1 + '_' + str2 # combined is now abc_xyz #### Strings running over multiple lines -Strings running over multiple lines can be declared with three single quotes, like this: +Strings running over multiple lines can be declared with three single +quotes, like this: ```meson multiline_string = '''#include <foo.h> @@ -89,7 +109,8 @@ int main (int argc, char ** argv) { }''' ``` -This can also be combined with the string formatting functionality described below. +This can also be combined with the string formatting functionality +described below. #### String formatting @@ -101,11 +122,13 @@ res = template.format('text', 1, true) # res now has value 'string: text, number: 1, bool: true' ``` -As can be seen, the formatting works by replacing placeholders of type `@number@` with the corresponding argument. +As can be seen, the formatting works by replacing placeholders of type +`@number@` with the corresponding argument. #### String methods -Strings also support a number of other methods that return transformed copies. +Strings also support a number of other methods that return transformed +copies. **.strip()** @@ -226,7 +249,9 @@ my_array += ['something'] my_array += 'else' ``` -Note appending to an array will always create a new array object and assign it to `my_array` instead of modifying the original since all objects in Meson are immutable. +Note appending to an array will always create a new array object and +assign it to `my_array` instead of modifying the original since all +objects in Meson are immutable. #### Array methods @@ -239,7 +264,8 @@ The following methods are defined for all arrays: Function calls -- -Meson provides a set of usable functions. The most common use case is creating build objects. +Meson provides a set of usable functions. The most common use case is +creating build objects. ```meson executable('progname', 'prog.c') @@ -248,7 +274,8 @@ executable('progname', 'prog.c') Method calls -- -Objects can have methods, which are called with the dot operator. The exact methods it provides depends on the object. +Objects can have methods, which are called with the dot operator. The +exact methods it provides depends on the object. ```meson myobj = some_function() @@ -279,7 +306,9 @@ endif ## Foreach statements -To do an operation on all elements of an array, use the `foreach` command. As an example, here's how you would define two executables with corresponding tests. +To do an operation on all elements of an array, use the `foreach` +command. As an example, here's how you would define two executables +with corresponding tests. ```meson progs = [['prog1', ['prog1.c', 'foo.c']], @@ -291,7 +320,9 @@ foreach p : progs endforeach ``` -Note that Meson variables are immutable. Trying to assign a new value to `progs` inside a foreach loop will not affect foreach's control flow. +Note that Meson variables are immutable. Trying to assign a new value +to `progs` inside a foreach loop will not affect foreach's control +flow. Logical operations -- @@ -334,12 +365,20 @@ The ternary operator works just like in other languages. x = condition ? true_value : false_value ``` -The only exception is that nested ternary operators are forbidden to improve legibility. If your branching needs are more complex than this you need to write an `if/else` construct. +The only exception is that nested ternary operators are forbidden to +improve legibility. If your branching needs are more complex than this +you need to write an `if/else` construct. Includes -- -Most source trees have multiple subdirectories to process. These can be handled by Meson's `subdir` command. It changes to the given subdirectory and executes the contents of `meson.build` in that subdirectory. All state (variables etc) are passed to and from the subdirectory. The effect is roughly the same as if the contents of the subdirectory's Meson file would have been written where the include command is. +Most source trees have multiple subdirectories to process. These can +be handled by Meson's `subdir` command. It changes to the given +subdirectory and executes the contents of `meson.build` in that +subdirectory. All state (variables etc) are passed to and from the +subdirectory. The effect is roughly the same as if the contents of the +subdirectory's Meson file would have been written where the include +command is. ```meson test_data_dir = 'data' @@ -349,4 +388,12 @@ subdir('tests') User-defined functions and methods -- -Meson does not currently support user-defined functions or methods. The addition of user-defined functions would make Meson Turing-complete which would make it harder to reason about and more difficult to integrate with tools like IDEs. More details about this are [in the FAQ](FAQ.md#why-is-meson-not-just-a-python-module-so-i-could-code-my-build-setup-in-python). If because of this limitation you find yourself copying and pasting code a lot you may be able to use a [`foreach` loop instead](#foreach-statements). +Meson does not currently support user-defined functions or +methods. The addition of user-defined functions would make Meson +Turing-complete which would make it harder to reason about and more +difficult to integrate with tools like IDEs. More details about this +are [in the +FAQ](FAQ.md#why-is-meson-not-just-a-python-module-so-i-could-code-my-build-setup-in-python). If +because of this limitation you find yourself copying and pasting code +a lot you may be able to use a [`foreach` loop +instead](#foreach-statements). diff --git a/docs/markdown/Unit-tests.md b/docs/markdown/Unit-tests.md index 7949522..afbeaa0 100644 --- a/docs/markdown/Unit-tests.md +++ b/docs/markdown/Unit-tests.md @@ -57,52 +57,54 @@ Sometimes a test can only determine at runtime that it can not be run. The GNU s ## Testing tool -In version 0.37.0 a new tool called `mesontest` was added. The goal of this tool is to provide a simple way to run tests in a variety of different ways. The tool is designed to be run in the build directory. +The goal of the meson test tool is to provide a simple way to run tests in a variety of different ways. The tool is designed to be run in the build directory. The simplest thing to do is just to run all tests, which is equivalent to running `ninja test`. ```console -$ mesontest +$ meson test ``` You can also run only a single test by giving its name: ```console -$ mesontest testname +$ meson test testname ``` Sometimes you need to run the tests multiple times, which is done like this: ```console -$ mesontest --repeat=10 +$ meson test --repeat=10 ``` Invoking tests via a helper executable such as Valgrind can be done with the `--wrap` argument ```console -$ mesontest --wrap=valgrind testname +$ meson test --wrap=valgrind testname ``` Arguments to the wrapper binary can be given like this: ```console -$ mesontest --wrap='valgrind --tool=helgrind' testname +$ meson test --wrap='valgrind --tool=helgrind' testname ``` Meson also supports running the tests under GDB. Just doing this: ```console -$ mesontest --gdb testname +$ meson test --gdb testname ``` -Mesontest will launch `gdb` all set up to run the test. Just type `run` in the GDB command prompt to start the program. +Meson will launch `gdb` all set up to run the test. Just type `run` in the GDB command prompt to start the program. The second use case is a test that segfaults only rarely. In this case you can invoke the following command: ```console -$ mesontest --gdb --repeat=10000 testname +$ meson test --gdb --repeat=10000 testname ``` -This runs the test up to 10 000 times under GDB automatically. If the program crashes, GDB will halt and the user can debug the application. Note that testing timeouts are disabled in this case so mesontest will not kill `gdb` while the developer is still debugging it. The downside is that if the test binary freezes, the test runner will wait forever. +This runs the test up to 10 000 times under GDB automatically. If the program crashes, GDB will halt and the user can debug the application. Note that testing timeouts are disabled in this case so `meson test` will not kill `gdb` while the developer is still debugging it. The downside is that if the test binary freezes, the test runner will wait forever. -For further information see the command line help of Mesontest by running `mesontest -h`. +For further information see the command line help of Meson by running `meson test -h`. + +**NOTE:** If `meson test` does not work for you, you likely have a old version of Meson. In that case you should call `mesontest` instead. If `mesontest` doesn't work either you have a very old version prior to 0.37.0 and should upgrade. diff --git a/docs/markdown/Users.md b/docs/markdown/Users.md index 46c2654..c27c516 100644 --- a/docs/markdown/Users.md +++ b/docs/markdown/Users.md @@ -9,7 +9,7 @@ If you have a project that uses Meson that you want to add to this list, let us - [AQEMU](https://github.com/tobimensch/aqemu), a Qt GUI for QEMU virtual machines, since version 0.9.3 - [Arduino sample project](https://github.com/jpakkane/mesonarduino) - [Budgie Desktop](https://github.com/budgie-desktop/budgie-desktop), a desktop environment built on GNOME technologies - - [casync](https://github.com/systemd/casync), + - [casync](https://github.com/systemd/casync), Content-Addressable Data Synchronization Tool - [Emeus](https://github.com/ebassi/emeus), Constraint based layout manager for GTK+ - [Frida](https://www.frida.re/), a dynamic binary instrumentation toolkit - [GLib](https://git.gnome.org/browse/glib/), cross-platform C library used by GTK+ and GStreamer (not the default yet) @@ -43,4 +43,4 @@ If you have a project that uses Meson that you want to add to this list, let us - [Wayland and Weston](https://lists.freedesktop.org/archives/wayland-devel/2016-November/031984.html), a next generation display server (not merged yet) - [ZStandard](https://github.com/facebook/zstd/commit/4dca56ed832c6a88108a2484a8f8ff63d8d76d91) a compression algorithm developed at Facebook (not used by default) -Note that a more up-to-date list of GNOME projects that use Meson can be found here: https://wiki.gnome.org/Initiatives/GnomeGoals/MesonPorting +Note that a more up-to-date list of GNOME projects that use Meson can be found [here](https://wiki.gnome.org/Initiatives/GnomeGoals/MesonPorting). diff --git a/docs/markdown/Using-multiple-build-directories.md b/docs/markdown/Using-multiple-build-directories.md index c07b39c..2455640 100644 --- a/docs/markdown/Using-multiple-build-directories.md +++ b/docs/markdown/Using-multiple-build-directories.md @@ -8,7 +8,7 @@ Secondly this makes it very easy to clean your projects: just delete the build s The true benefit comes from somewhere else, though. -## Multiple build directories for the same source tree ## +## Multiple build directories for the same source tree Since a build directory is fully self contained and treats the source tree as a read-only piece of data, it follows that you can have arbitrarily many build trees for any source tree at the same time. Since all build trees can have different configuration, this is extremely powerful. Now you might be wondering why one would want to have multiple build setups at the same time. Let's examine this by setting up a hypothetical project. @@ -36,7 +36,7 @@ The cross compilation file sets up Wine so that not only can you compile your ap To compile any of these build types, just cd into the corresponding build directory and run `ninja` or instruct your IDE to do the same. Note that once you have set up your build directory once, you can just run Ninja and Meson will ensure that the resulting build is fully up to date according to the source. Even if you have not touched one of the directories in weeks and have done major changes to your build configuration, Meson will detect this and bring the build directory up to date (or print an error if it can't do that). This allows you to do most of your work in the default directory and use the others every now and then without having to babysit your build directories. -## Specialized uses ## +## Specialized uses Separate build directories allows easy integration for various different kinds of tools. As an example, Clang comes with a static analyzer. It is meant to be run from scratch on a given source tree. The steps to run it with Meson are very simple. diff --git a/docs/markdown/Using-wraptool.md b/docs/markdown/Using-wraptool.md index e000695..8e5f898 100644 --- a/docs/markdown/Using-wraptool.md +++ b/docs/markdown/Using-wraptool.md @@ -53,7 +53,7 @@ To check if your projects are up to date you can issue the `status` command. In this case `zlib` has a newer release available. Updating it is straightforward: - $ wraptool.py update zlib + $ wraptool update zlib Updated zlib to branch 1.2.8 revision 4 Wraptool can do other things besides these. Documentation for these can be found in the command line help, which can be accessed by `wraptool --help`. diff --git a/docs/markdown/Vala.md b/docs/markdown/Vala.md index e183bb0..c5d2b79 100644 --- a/docs/markdown/Vala.md +++ b/docs/markdown/Vala.md @@ -26,9 +26,9 @@ When dealing with libraries that are not providing Vala bindings, a `--vapidir` ```meson project('vala app', 'c', 'vala') -add_project_arguments(['--vapidir', join_paths(meson.current_source_dir(), 'vapi')], +add_project_arguments(['--vapidir', join_paths(meson.current_source_dir(), 'vapi')], language: 'vala') - + glib_dep = dependency('glib-2.0') gobject_dep = dependency('gobject-2.0') foo_dep = dependency('foo') # 'foo.vapi' will be resolved in './vapi/foo.vapi' @@ -36,7 +36,7 @@ foo_dep = dependency('foo') # 'foo.vapi' will be resolved in './vapi/foo.vapi' executable('app', 'app.vala', dependencies: [glib_dep, gobject_dep, foo_dep]) ``` -In this case, make sure that the VAPI name corresponds to the pkg-config file. +In this case, make sure that the VAPI name corresponds to the pkg-config file. If no pkg-config file is provided, you must use `find_library`. Using`declare_dependency` is cleaner because it does not require passing both dependency objects to the target. @@ -63,9 +63,9 @@ executable('app', 'app.vala', dependencies: [glib_dep, gobject_dep, posix_dep]) If a library target is used, Meson automatically outputs the C header and the VAPI. They can be renamed by setting the `vala_header` and `vala_vapi` arguments respectively. In this case, the second and third elements of the `install_dir` array indicate the destination with `true` to indicate default directories (i.e. `include` and `share/vala/vapi`). ```meson -foo_lib = library('foo', 'foo.vala', +foo_lib = library('foo', 'foo.vala', vala_header: 'foo.h', - vala_vapi: 'foo-1.0.vapi', + vala_vapi: 'foo-1.0.vapi', dependencies: [glib_dep, gobject_dep], install: true, install_dir: [true, true, true]) @@ -78,8 +78,8 @@ To generate GObject Introspection metadata, the `vala_gir` option has to be set The fourth element in the `install_dir` array indicate where the GIR file will be installed. The `true` value tells Meson to use the default directory (i.e. `share/gir-1.0`). ```meson -foo_lib = library('foo', 'foo.vala', - vala_gir: 'Foo-1.0.gir', +foo_lib = library('foo', 'foo.vala', + vala_gir: 'Foo-1.0.gir', dependencies: [glib_dep, gobject_dep], install: true, install_dir: [true, true, true, true]) diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md index a850896..d97fc9a 100644 --- a/docs/markdown/Wrap-dependency-system-manual.md +++ b/docs/markdown/Wrap-dependency-system-manual.md @@ -52,7 +52,7 @@ are downloaded and automatically applied to the subproject. These files contain a Meson build definition for the given subproject. A wrap file with an additional patch URL would look like this. -``` +```ini [wrap-file] directory = libfoobar-1.0 @@ -83,7 +83,7 @@ packaged files. Sometimes you want to check code out directly from Git. Meson supports this natively. All you need to do is to write a slightly different wrap file. -``` +```ini [wrap-git] directory=samplesubproject url=https://github.com/jpakkane/samplesubproject.git diff --git a/docs/markdown/Wrap-review-guidelines.md b/docs/markdown/Wrap-review-guidelines.md index 39acadc..512353c 100644 --- a/docs/markdown/Wrap-review-guidelines.md +++ b/docs/markdown/Wrap-review-guidelines.md @@ -7,7 +7,7 @@ package is rejected. What should be done will be determined on a case-by-case basis. Similarly meeting all these requirements does not guarantee that the package will get accepted. Use common sense. -## Checklist ## +## Checklist Reviewer: copy-paste this to MR discussion box and tick all boxes that apply. diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md index 2dd5ddf..c4aa9c5 100644 --- a/docs/markdown/howtox.md +++ b/docs/markdown/howtox.md @@ -97,12 +97,12 @@ $ ninja coverage-html (or coverage-xml) The coverage report can be found in the meson-logs subdirectory. -## Add some optimization to debug builds ## +## Add some optimization to debug builds By default the debug build does not use any optimizations. This is the desired approach most of the time. However some projects benefit from having some minor optimizations enabled. GCC even has a specific compiler flag `-Og` for this. To enable its use, just issue the following command. ```console -$ mesonconf -Dc_args=-Og +$ meson configure -Dc_args=-Og ``` This causes all subsequent builds to use this command line argument. @@ -139,7 +139,7 @@ Then we need to run the program with some representative input. This step depend Once that is done we change the compiler flags to use the generated information and rebuild. ```console -$ mesonconf -Db_pgo=use +$ meson configure -Db_pgo=use $ ninja ``` diff --git a/docs/markdown/i18n-module.md b/docs/markdown/i18n-module.md index 5e6004a..8fb650a 100644 --- a/docs/markdown/i18n-module.md +++ b/docs/markdown/i18n-module.md @@ -17,20 +17,18 @@ argument which is the name of the gettext module. * `args`: list of extra arguments to pass to `xgettext` when generating the pot file - * `data_dirs`: (*Added 0.36.0*) list of directories to be set for `GETTEXTDATADIRS` env var (Requires gettext 0.19.8+), used for local its files - * `languages`: list of languages that are to be generated. As of 0.37.0 this is optional and the [LINGUAS](https://www.gnu.org/software/gettext/manual/html_node/po_002fLINGUAS.html) file is read. - * `preset`: (*Added 0.37.0*) name of a preset list of arguments, current option is `'glib'`, see [source](https://github.com/mesonbuild/meson/blob/master/mesonbuild/modules/i18n.py) for for their value +* `install`: (*Added 0.43.0*) if false, do not install the built translations. This function also defines targets for maintainers to use: **Note**: These output to the source directory diff --git a/docs/markdown/index.md b/docs/markdown/index.md index 8e35a4d..81c17ff 100644 --- a/docs/markdown/index.md +++ b/docs/markdown/index.md @@ -13,7 +13,7 @@ The main design point of Meson is that every moment a developer spends writing o ## Features * multiplatform support for Linux, OSX, Windows, GCC, Clang, Visual Studio and others -* supported languages include C, C++, Fortran, Java, Rust +* supported languages include C, C++, D, Fortran, Java, Rust * build definitions in a very readable and user friendly non-Turing complete DSL * cross compilation for many operating systems as well as bare metal * optimized for extremely fast full and incremental builds without sacrificing correctness @@ -24,10 +24,10 @@ The main design point of Meson is that every moment a developer spends writing o There are two main methods of connecting with other Meson developers. The first one is the mailing list, which is hosted at [Google Groups](https://groups.google.com/forum/#!forum/mesonbuild). -The second way is via IRC. The channel to use is <tt>#mesonbuild</tt> at [Freenode](https://freenode.net/). +The second way is via IRC. The channel to use is `#mesonbuild` at [Freenode](https://freenode.net/). ## Development -All development on Meson is done on [GitHub project](https://github.com/mesonbuild/meson). For further info look into the <tt>contributing.txt</tt> file that comes with Meson's source checkout. +All development on Meson is done on [GitHub project](https://github.com/mesonbuild/meson). For further info look into the `contributing.txt` file that comes with Meson's source checkout. You do not need to sign a CLA to contribute to Meson. diff --git a/docs/markdown/snippets/add_release_note_snippets_here b/docs/markdown/snippets/add_release_note_snippets_here new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/markdown/snippets/add_release_note_snippets_here diff --git a/docs/markdown/snippets/cross_find.md b/docs/markdown/snippets/cross_find.md deleted file mode 100644 index b16d64d..0000000 --- a/docs/markdown/snippets/cross_find.md +++ /dev/null @@ -1,15 +0,0 @@ -# Can override executables in the cross file - -The cross file can now be used for overriding the result of -`find_program`. As an example if you want to find the `objdump` -command and have the following definition in your cross file: - - [binaries] - ... - objdump = '/usr/bin/arm-linux-gnueabihf-objdump-6' - -Then issuing the command `find_program('objdump')` will return the -version specified in the cross file. If you need the build machine's -objdump, you can specify the `native` keyword like this: - - native_objdump = find_program('objdump', native : true) diff --git a/docs/markdown/snippets/get-supported-arguments.md b/docs/markdown/snippets/get-supported-arguments.md deleted file mode 100644 index c0cc9bf..0000000 --- a/docs/markdown/snippets/get-supported-arguments.md +++ /dev/null @@ -1,23 +0,0 @@ -# Easier handling of supported compiler arguments - -A common pattern for handling multiple desired compiler arguments, was to -test their presence and add them to an array one-by-one, e.g.: - - warning_flags_maybe = [ - '-Wsomething', - '-Wanother-thing', - '-Wno-the-other-thing', - ] - warning_flags = [] - foreach flag : warning_flags_maybe - if cc.has_argument(flag) - warning_flags += flag - endif - endforeach - cc.add_project_argument(warning_flags) - -A helper has been added for the foreach/has_argument pattern, so you can -now simply do: - - warning_flags = [ ... ] - flags = cc.get_supported_flags(warning_flags) diff --git a/docs/markdown/snippets/llvm-static-linking.md b/docs/markdown/snippets/llvm-static-linking.md new file mode 100644 index 0000000..bb72a56 --- /dev/null +++ b/docs/markdown/snippets/llvm-static-linking.md @@ -0,0 +1,8 @@ +# LLVM dependency supports both dynamic and static linking + +The LLVM dependency has been improved to consistently use dynamic linking. +Previously recent version (>= 3.9) would link dynamically while older versions +would link statically. + +Now LLVM also accepts the `static` keyword to enable statically linking to LLVM +modules instead of dynamically linking. diff --git a/docs/markdown/snippets/prefix-dependent-defaults.md b/docs/markdown/snippets/prefix-dependent-defaults.md new file mode 100644 index 0000000..7cc1792 --- /dev/null +++ b/docs/markdown/snippets/prefix-dependent-defaults.md @@ -0,0 +1,10 @@ +# Prefix-dependent defaults for sysconfdir, localstatedir and sharedstatedir + +These options now default in a way consistent with +[FHS](http://refspecs.linuxfoundation.org/fhs.shtml) and common usage. + +If prefix is `/usr`, default sysconfdir to `/etc`, localstatedir to `/var` and +sharedstatedir to `/var/lib`. + +If prefix is `/usr/local` (the default), default localstatedir to `/var/local` +and sharedstatedir to `/var/local/lib`. diff --git a/docs/markdown/snippets/qt5-moc_extra_arguments.md b/docs/markdown/snippets/qt5-moc_extra_arguments.md new file mode 100644 index 0000000..957c3c7 --- /dev/null +++ b/docs/markdown/snippets/qt5-moc_extra_arguments.md @@ -0,0 +1,8 @@ +# Adds support for additional Qt5-Module keyword `moc_extra_arguments` + +When `moc`-ing sources, the `moc` tool does not know about any +preprocessor macros. The generated code might not match the input +files when the linking with the moc input sources happens. + +This amendment allows to specify a a list of additional arguments +passed to the `moc` tool. They are called `moc_extra_arguments`.
\ No newline at end of file diff --git a/docs/markdown/snippets/warning_function b/docs/markdown/snippets/warning_function new file mode 100644 index 0000000..537651e --- /dev/null +++ b/docs/markdown/snippets/warning_function @@ -0,0 +1,6 @@ +# Added warning function + +This function prints its argument to the console prefixed by "WARNING:" in +yellow color. A simple example: + +warning('foo is deprecated, please use bar instead') diff --git a/docs/sitemap.txt b/docs/sitemap.txt index af8aede..6b155af 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -38,6 +38,7 @@ index.md Windows-module.md Java.md Vala.md + D.md IDE-integration.md Custom-build-targets.md Build-system-converters.md @@ -47,6 +48,7 @@ index.md Creating-OSX-packages.md Creating-Linux-binaries.md Reference-manual.md + Reference-tables.md FAQ.md Reproducible-builds.md howtox.md @@ -59,6 +61,7 @@ index.md Shipping-prebuilt-binaries-as-wraps.md fallback-wraptool.md Release-notes.md + Release-notes-for-0.44.0.md Release-notes-for-0.43.0.md Release-notes-for-0.42.0.md Release-notes-for-0.41.0.md |
