diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Dependencies.md | 63 | ||||
| -rw-r--r-- | docs/markdown/Qt5-module.md | 17 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 14 | ||||
| -rw-r--r-- | docs/markdown/Subprojects.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Syntax.md | 91 | ||||
| -rw-r--r-- | docs/markdown/Unit-tests.md | 6 | ||||
| -rw-r--r-- | docs/markdown/Using-wraptool.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Wrap-dependency-system-manual.md | 4 | ||||
| -rw-r--r-- | docs/markdown/i18n-module.md | 4 | ||||
| -rw-r--r-- | docs/markdown/snippets/llvm-static-linking.md | 8 | ||||
| -rw-r--r-- | docs/markdown/snippets/qt5-moc_extra_arguments.md | 8 | ||||
| -rw-r--r-- | docs/markdown/snippets/warning_function | 6 |
12 files changed, 171 insertions, 54 deletions
diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index c3f007f..8e780d6 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -45,7 +45,52 @@ 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. + +# 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 @@ -153,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/Qt5-module.md b/docs/markdown/Qt5-module.md index a8ad73d..aea2ae1 100644 --- a/docs/markdown/Qt5-module.md +++ b/docs/markdown/Qt5-module.md @@ -5,17 +5,22 @@ tools and steps required for Qt. The module has one method. ## preprocess -This method takes five keyword arguments, `moc_headers`, -`moc_sources`, `ui_files` and `qresources` which define the files that -require preprocessing with `moc`, `uic` and `rcc` and 'include_directories' which might be needed by moc. 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']) inc = include_directories('includes') -moc_files = qt5.preprocess(moc_headers : 'myclass.h', include_directories: inc) +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 42d02e1..eee4405 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() @@ -847,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 @@ -1084,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() 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 eaf24cf..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 @@ -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 6ded714..afbeaa0 100644 --- a/docs/markdown/Unit-tests.md +++ b/docs/markdown/Unit-tests.md @@ -95,7 +95,7 @@ Meson also supports running the tests under GDB. Just doing this: $ 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: @@ -103,8 +103,8 @@ The second use case is a test that segfaults only rarely. In this case you can i $ 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/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/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/i18n-module.md b/docs/markdown/i18n-module.md index 1144e29..8fb650a 100644 --- a/docs/markdown/i18n-module.md +++ b/docs/markdown/i18n-module.md @@ -17,21 +17,17 @@ 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: 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/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') |