diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Cross-compilation.md | 1 | ||||
| -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/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/snippets/qt5-moc_extra_arguments.md | 8 | ||||
| -rw-r--r-- | docs/markdown/snippets/warning_function | 6 |
10 files changed, 95 insertions, 28 deletions
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/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/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/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') |