diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Contributing.md | 31 | ||||
| -rw-r--r-- | docs/markdown/Disabler.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Release-notes-for-0.43.0.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Release-notes-for-0.44.0.md | 12 | ||||
| -rw-r--r-- | docs/markdown/Using-wraptool.md | 60 | ||||
| -rw-r--r-- | docs/markdown/snippets/wrap_promote.md | 11 |
7 files changed, 103 insertions, 17 deletions
diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md index 354bf62..169bf4c 100644 --- a/docs/markdown/Contributing.md +++ b/docs/markdown/Contributing.md @@ -32,6 +32,37 @@ basis. Sometimes it may be easier to write the test than convince the maintainers that one is not needed. Exercise judgment and ask for help in problematic cases. +The tests are split into two different parts: unit tests and full +project tests. To run all tests, execute `./run_tests.py`. Unit tests +can be run with `./run_unittests.py` and project tests with +`./run_project_tests.py`. + +Each project test is a standalone project that can be compiled on its +own. They are all in `test cases` subdirectory. The simplest way to +run a single project test is to do something like `./meson.py test\ +cases/common/1\ trivial builddir`. The one exception to this is `test +cases/unit` directory discussed below. + +The test cases in the `common` subdirectory are meant to be run always +for all backends. They should only depend on C and C++, without any +external dependencies such as libraries. Tests that require those are +in the `test cases/frameworks` directory. If there is a need for an +external program in the common directory, such as a code generator, it +should be implemented as a Python script. The goal of test projects is +also to provide sample projects that end users can use as a base for +their own projects. + +All project tests follow the same pattern: they are compiled, tests +are run and finally install is run. Passing means that building and +tests succeed and installed files match the `installed_files.txt` file +in the test's source root. Any tests that require more thorough +analysis, such as checking that certain compiler arguments can be +found in the command line or that the generated pkg-config files +actually work should be done with a unit test. + +Projects needed by unit tests are in the `test cases/unit` +subdirectory. They are not run as part of `./run_project_tests.py`. + ## Documentation The `docs` directory contains the full documentation that will be used diff --git a/docs/markdown/Disabler.md b/docs/markdown/Disabler.md index bd2b322..81417f6 100644 --- a/docs/markdown/Disabler.md +++ b/docs/markdown/Disabler.md @@ -63,4 +63,4 @@ endif This concentrates the handling of this option in one place and other build definition files do not need to be sprinkled with `if` -statements.
\ No newline at end of file +statements. diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index f797da1..14c931d 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -483,7 +483,7 @@ Keyword arguments are the following: then use the `.found()` method on the returned object to check whether it was found or not. -- `native` defines how this executable should be searched. By default +- `native` *(since 0.43)* defines how this executable should be searched. By default it is set to `false`, which causes Meson to first look for the executable in the cross file (when cross building) and if it is not defined there, then from the system. If set to `true`, the cross diff --git a/docs/markdown/Release-notes-for-0.43.0.md b/docs/markdown/Release-notes-for-0.43.0.md index 3f981e8..7702f3c 100644 --- a/docs/markdown/Release-notes-for-0.43.0.md +++ b/docs/markdown/Release-notes-for-0.43.0.md @@ -1,6 +1,6 @@ --- title: Release 0.43 -short-description: Release notes for 0.43 (preliminary) +short-description: Release notes for 0.43 ... # Portability improvements to Boost Dependency diff --git a/docs/markdown/Release-notes-for-0.44.0.md b/docs/markdown/Release-notes-for-0.44.0.md index 93e224d..56956d7 100644 --- a/docs/markdown/Release-notes-for-0.44.0.md +++ b/docs/markdown/Release-notes-for-0.44.0.md @@ -71,10 +71,12 @@ Added a new keyword argument to the `subdir` command. It is given a list of dependency objects and the function will only recurse in the subdirectory if they are all found. Typical usage goes like this. - d1 = dependency('foo') # This is found - d2 = dependency('bar') # This is not found +```meson +d1 = dependency('foo') # This is found +d2 = dependency('bar') # This is not found - subdir('somedir', if_found : [d1, d2]) +subdir('somedir', if_found : [d1, d2]) +``` In this case the subdirectory would not be entered since `d2` could not be found. @@ -138,6 +140,8 @@ Meson now ships an internal version of Python in the MSI installer packages. This means that it can run Python scripts that are part of your build transparently. That is, if you do the following: - myprog = find_program('myscript.py') +```meson +myprog = find_program('myscript.py') +``` Then Meson will run the script with its internal Python version if necessary. diff --git a/docs/markdown/Using-wraptool.md b/docs/markdown/Using-wraptool.md index 8e5f898..08b1bfa 100644 --- a/docs/markdown/Using-wraptool.md +++ b/docs/markdown/Using-wraptool.md @@ -1,12 +1,20 @@ # Using wraptool -Wraptool is a helper tool that allows you to manage your source dependencies using the WrapDB database. It gives you all things you would expect, such as installing and updating dependencies. The wrap tool works on all platforms, the only limitation is that the wrap definition works on your target platform. If you find some Wraps that don't work, please file bugs or, even better, patches. +Wraptool is a helper tool that allows you to manage your source +dependencies using the WrapDB database. It gives you all things you +would expect, such as installing and updating dependencies. The wrap +tool works on all platforms, the only limitation is that the wrap +definition works on your target platform. If you find some Wraps that +don't work, please file bugs or, even better, patches. -All code examples here assume that you are running the commands in your top level source directory. Lines that start with the `$` mark are commands to type. +All code examples here assume that you are running the commands in +your top level source directory. Lines that start with the `$` mark +are commands to type. ## Simple querying -The simplest operation to do is to query the list of packages available. To list them all issue the following command: +The simplest operation to do is to query the list of packages +available. To list them all issue the following command: $ wraptool list box2d @@ -22,27 +30,35 @@ The simplest operation to do is to query the list of packages available. To list vorbis zlib -Usually you want to search for a specific package. This can be done with the `search` command: +Usually you want to search for a specific package. This can be done +with the `search` command: $ wraptool search jpeg libjpeg -To determine which versions of libjpeg are available to install, issue the `info` command: +To determine which versions of libjpeg are available to install, issue +the `info` command: $ wraptool info libjpeg Available versions of libjpeg: 9a 2 -The first number is the upstream release version, in this case `9a`. The second number is the Wrap revision number. They don't relate to anything in particular, but larger numbers imply newer releases. You should always use the newest available release. +The first number is the upstream release version, in this case +`9a`. The second number is the Wrap revision number. They don't relate +to anything in particular, but larger numbers imply newer +releases. You should always use the newest available release. ## Installing dependencies -Installing dependencies is just as straightforward. First just create the `subprojects` directory at the top of your source tree and issue the install command. +Installing dependencies is just as straightforward. First just create +the `subprojects` directory at the top of your source tree and issue +the install command. $ wraptool install libjpeg Installed libjpeg branch 9a revision 2 -Now you can issue a `subproject('libjpeg')` in your `meson.build` file to use it. +Now you can issue a `subproject('libjpeg')` in your `meson.build` file +to use it. To check if your projects are up to date you can issue the `status` command. @@ -51,9 +67,33 @@ To check if your projects are up to date you can issue the `status` command. libjpeg up to date. Branch 9a, revision 2. zlib not up to date. Have 1.2.8 2, but 1.2.8 4 is available. -In this case `zlib` has a newer release available. Updating it is straightforward: +In this case `zlib` has a newer release available. Updating it is +straightforward: $ 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`. +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`. + +## Promoting dependencies + +Meson will only search for subprojects from the top level +`subprojects` directory. If you have subprojects that themselves have +subprojects, you must transfer them to the top level. This can be done +by going to your source root and issuing a promotion command. + + meson wrap promote projname + +This will cause Meson to go through your entire project tree, find an +embedded subproject and copy it to the top level. + +If there are multiple embedded copies of a subproject, Meson will not +try to guess which one you want. Instead it will print all the +possibilities. You can then manually select which one to promote by +writing it out fully. + + meson wrap promote subprojects/s1/subprojects/projname + +This functionality was added in Meson release 0.45.0. diff --git a/docs/markdown/snippets/wrap_promote.md b/docs/markdown/snippets/wrap_promote.md new file mode 100644 index 0000000..20fee47 --- /dev/null +++ b/docs/markdown/snippets/wrap_promote.md @@ -0,0 +1,11 @@ +# Can promote dependencies with wrap command + +The `promote` command makes it easy to copy nested dependencies to the top level. + + meson wrap promote scommon + +This will search the project tree for a subproject called `scommon` and copy it to the top level. + +If there are many embedded subprojects with the same name, you have to specify which one to promote manually like this: + + meson wrap promote subprojects/s1/subprojects/scommon |