diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Compiler-properties.md | 12 | ||||
| -rw-r--r-- | docs/markdown/Creating-releases.md | 15 | ||||
| -rw-r--r-- | docs/markdown/Pkgconfig-module.md | 1 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 86 | ||||
| -rw-r--r-- | docs/markdown/Release-notes-for-0.41.0.md | 30 | ||||
| -rw-r--r-- | docs/markdown/Running-Meson.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Syntax.md | 2 | ||||
| -rw-r--r-- | docs/markdown/legal.md | 2 | ||||
| -rw-r--r-- | docs/sitemap.txt | 1 |
10 files changed, 106 insertions, 47 deletions
diff --git a/docs/README.md b/docs/README.md index 61d2e05..9ed75c1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # Building the documentation 1. Get [hotdoc](https://hotdoc.github.io/installing.html) (0.8.9 required) -1. Run hotdoc: +1. Run hotdoc in the docs/ directory: hotdoc run diff --git a/docs/markdown/Compiler-properties.md b/docs/markdown/Compiler-properties.md index 50615a1..c33d917 100644 --- a/docs/markdown/Compiler-properties.md +++ b/docs/markdown/Compiler-properties.md @@ -97,12 +97,12 @@ result = compiler.run(code, name : 'basic check') 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/Creating-releases.md b/docs/markdown/Creating-releases.md new file mode 100644 index 0000000..b0149a6 --- /dev/null +++ b/docs/markdown/Creating-releases.md @@ -0,0 +1,15 @@ +--- +short-description: Creating releases +... + +# Creating releases + +In addition to development, almost all projects provide periodical source releases. These are standalone packages (usually either in tar or zip format) of the source code. They do not contain any revision control metadata, only the source code. + +Meson provides a simple way of generating these. It consists of a single command: + + ninja dist + +This creates a file called `projectname-version.tar.xz` in the build tree subdirectory `meson-dist`. This archive contains the full contents of the latest commit in revision control including all the submodules. All revision control metadata is removed. Meson then takes this archive and tests that it works by doing a full compile + test + install cycle. If all these pass, Meson will then create a SHA-256 checksum file next to the archive. + +**Note**: Meson behaviour is different from Autotools. The Autotools "dist" target packages up the current source tree. Meson packages the latest revision control commit. The reason for this is that it prevents developers from doing accidental releases where the distributed archive does not match any commit in revision control (especially the one tagged for the release). diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md index 51fe6b2..6b9a968 100644 --- a/docs/markdown/Pkgconfig-module.md +++ b/docs/markdown/Pkgconfig-module.md @@ -20,3 +20,4 @@ The generated file's properties are specified with the following keyword argumen - `requires_private` list of strings to put in the `Requires.private` field - `libraries_private` list of strings to put in the `Libraries.private` field - `install_dir` the directory to install to, defaults to the value of option `libdir` followed by `/pkgconfig` +- `variables` a list of strings with custom variables to add to the generated file. The strings must be in the form `name=value` and may reference other pkgconfig variables, e.g. `datadir=${prefix}/share`. The names `prefix`, `libdir` and `installdir` are reserved and may not be used. diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 00a891b..62c0fb3 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -137,7 +137,7 @@ These are all the supported keyword arguments: Create a custom top level build target. The only positional argument is the name of this target and the keyword arguments are the following. -- `input` list of source files +- `input` list of source files. As of 0.41.0 the list will be flattened. - `output` list of output files - `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', '-arg1', '-arg2']` rather than as a string `'commandname -arg1 -arg2'` as the latter will *not* work) - `install` when true, this target is installed during the install step @@ -228,8 +228,8 @@ With the Ninja backend, Meson will create a build-time [order-only dependency](h Executable supports the following keyword arguments. Note that just like the positional arguments above, these keyword arguments can also be passed to [shared and static libraries](#library). -- `link_with`, one or more shared or static libraries (built by this project) that this target should be linked with -- `link_whole` links all contents of the given static libraries whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC, available since 0.40.0 +- `link_with`, one or more shared or static libraries (built by this project) that this target should be linked with, If passed a list this list will be flattened as of 0.41.0. +- `link_whole` links all contents of the given static libraries whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC, available since 0.40.0. As of 0.41.0 if passed a list that list will be flattened. - `<languagename>_pch` precompiled header file to use for the given language - `<languagename>_args` compiler flags to use for the given language; eg: `cpp_args` for C++ - `link_args` flags to use during linking. You can use UNIX-style flags here for all platforms. @@ -262,11 +262,23 @@ This function is deprecated and in the 0.31.0 release it was moved to [the compi `program_name1` here is a string that can be an executable or script to be searched for in `PATH`, or a script in the current source directory. +`program_name2` and later positional arguments are used as fallback strings to search for. This is meant to be used for cases where the program may have many alternative names, such as `foo` and `foo.py`. The function will check for the arguments one by one and the first one that is found is returned. Meson versions earlier than 0.37.0 only accept one argument. + +Keyword arguments are the following: + +- `required` By default, `required` is set to `true` and Meson will abort if no program can be found. If `required` is set to `false`, Meson continue even if none of the programs can be found. You can then use the `.found()` method on the returned object to check whether it was found or not. + Meson will also autodetect scripts with a shebang line and run them with the executable/interpreter specified in it both on Windows (because the command invocator will reject the command otherwise) and Unixes (if the script file does not have the executable bit set). Hence, you *must not* manually add the interpreter while using this script as part of a list of commands. -`program_name2` and later positional arguments are used as fallback strings to search for. This is meant to be used for cases where the program may have many alternative names, such as `foo` and `foo.py`. The function will check for the arguments one by one and the first one that is found is returned. Meson versions earlier than 0.37.0 only accept one argument. +If you need to check for a program in a non-standard location, you can just pass an absolute path to `find_program`, e.g. +``` +setcap = find_program('setcap', '/usr/sbin/setcap', '/sbin/setcap', required : false) +``` -If none of the programs are found, Meson will abort. You can tell it not to by setting the keyword argument `required` to false, and then use the `.found()` method on the returned object to check whether it was found or not. +It is also possible to pass an array to `find_program` in case you need to construct the set of paths to search on the fly: +``` +setcap = find_program(['setcap', '/usr/sbin/setcap', '/sbin/setcap'], required : false) +``` The returned object also has methods that are documented in the [object methods section](#external-program-object) below. @@ -570,7 +582,7 @@ Builds a shared library with the given sources. Positional and keyword arguments - `version` a string specifying the version of this shared library, such as `1.1.0`. On Linux and OS X, this is used to set the shared library version in the filename, such as `libfoo.so.1.1.0` and `libfoo.1.1.0.dylib`. If this is not specified, `soversion` is used instead (see below). - `soversion` a string specifying the soversion of this shared library, such as `0`. On Linux and Windows this is used to set the soversion (or equivalent) in the filename. For example, if `soversion` is `4`, a Windows DLL will be called `foo-4.dll` and one of the aliases of the Linux shared library would be `libfoo.so.4`. If this is not specified, the first part of `version` is used instead. For example, if `version` is `3.6.0` and `soversion` is not defined, it is set to `3`. -- `vs_module_defs` a string pointing to a file or a File object that contains Visual Studio symbol export definitions. +- `vs_module_defs` a string pointing to a file or a File object that is a Microsoft module definition file for controlling symbol exports, etc., on platforms where that is possible (e.g. Windows). ### shared_module() @@ -660,37 +672,39 @@ The `meson` object allows you to introspect various properties of the system. Th - `backend()` *(added 0.37.0)* returns a string representing the current backend: `ninja`, `vs2010`, `vs2015`, or `xcode`. -- `is_cross_build()` returns `true` if the current build is a cross build and `false` otherwise +- `is_cross_build()` returns `true` if the current build is a [cross build](Cross-compilation.md) and `false` otherwise. + +- `is_unity()` returns `true` when doing a [unity build](Unity-builds.md) (multiple sources are combined before compilation to reduce build time) and `false` otherwise. -- `is_unity()` returns `true` when doing a unity build and `false` otherwise +- `is_subproject()` returns `true` if the current project is being built as a subproject of some other project and `false` otherwise. -- `is_subproject()` returns `true` if the current project is being built as a subproject of some other project and `false` otherwise +- `has_exe_wrapper()` returns true when doing a cross build if there is a wrapper command that can be used to execute cross built binaries (for example when cross compiling from Linux to Windows, one can use `wine` as the wrapper). -- `has_exe_wrapper()` returns true when doing a cross build if there is a wrapper command that can be used to execute cross built binaries (for example when cross compiling from Linux to Windows, one can use `wine` as the wrapper) +- `add_install_script(script_name, arg1, arg2, ...)` causes the script given as an argument to be run during the install step, this script will have the environment variables `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT`, `MESON_INSTALL_PREFIX`, `MESON_INSTALL_DESTDIR_PREFIX`, and `MESONINTROSPECT` set. All additional arguments are passed as parameters. -- `add_install_script(script_name, arg1, arg2, ...)` causes the script given as an argument to be run during the install step, this script will have the environment variables `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT`, `MESON_INSTALL_PREFIX`, and `MESON_INSTALL_DESTDIR_PREFIX` set. All additional arguments are passed as parameters. + To determine the installation location, the script should use the `DESTDIR`, `MESON_INSTALL_PREFIX`, `MESON_INSTALL_DESTDIR_PREFIX` variables. `DESTDIR` will be set only if it is inherited from the outside environment. `MESON_INSTALL_PREFIX` is always set and has the value of the `prefix` option passed to Meson. `MESON_INSTALL_DESTDIR_PREFIX` is always set and contains `DESTDIR` and `prefix` joined together. This is useful because both are absolute paths, and many path-joining functions such as [`os.path.join` in Python](https://docs.python.org/3/library/os.path.html#os.path.join) special-case absolute paths. - `MESON_INSTALL_PREFIX` has the value of the `prefix` option passed to Meson, and `MESON_INSTALL_DESTDIR_PREFIX` has both the value of `DESTDIR` and `prefix` joined together. This is useful because both are absolute paths, and many path-joining functions such as [`os.path.join` in Python](https://docs.python.org/3/library/os.path.html#os.path.join) special-case absolute paths. + `MESONINTROSPECT` contains the path to the `mesonintrospect` executable that corresponds to the `meson` executable that was used to configure the build. (This might be a different path then the first `mesonintrospect` executable found in `PATH`.) It can be used to query build configuration. - `add_postconf_script(script_name, arg1, arg2, ...)` will run the executable given as an argument after all project files have been generated. This script will have the environment variables `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT` set. - `current_source_dir()` returns a string to the current source directory. Note: **you do not need to use this function** when passing files from the current source directory to a function since that is the default. Also, you can use the `files()` function to refer to files in the current or any other source directory instead of constructing paths manually with `meson.current_source_dir()`. -- `current_build_dir()` returns a string to the current build directory +- `current_build_dir()` returns a string with the absolute path to the current build directory. - `source_root()` returns a string with the absolute path to the source root directory. Note: you should use the `files()` function to refer to files in the root source directory instead of constructing paths manually with `meson.source_root()`. -- `build_root()` returns a string with the absolute path to the build root directory +- `build_root()` returns a string with the absolute path to the build root directory. -- `project_version()` returns the version string specified in `project` function call +- `project_version()` returns the version string specified in `project` function call. -- `project_name()` returns the project name specified in the `project` function call +- `project_name()` returns the project name specified in the `project` function call. -- `version()` return a string with the version of Meson +- `version()` return a string with the version of Meson. -- `get_cross_property(propname, fallback_value)` returns the given property from a cross file, the optional second argument is returned if not cross compiling or the given property is not found +- `get_cross_property(propname, fallback_value)` returns the given property from a cross file, the optional second argument is returned if not cross compiling or the given property is not found. -- `install_dependency_manifest(output_name)` installs a manifest file containing a list of all subprojects, their versions and license files to the file name given as the argument +- `install_dependency_manifest(output_name)` installs a manifest file containing a list of all subprojects, their versions and license files to the file name given as the argument. ### `build_machine` object @@ -739,26 +753,26 @@ A build target is either an [executable](#executable), [shared](#shared_library) This object is returned by [`meson.get_compiler(lang)`](#meson-object). It represents a compiler for a given language and allows you to query its properties. It has the following methods: -- `get_id()` returns a string identifying the compiler (e.g. `'gcc'`) -- `version()` returns the compiler's version number as a string +- `get_id()` returns a string identifying the compiler (e.g. `'gcc'`). +- `version()` returns the compiler's version number as a string. - `find_library(lib_name, ...)` tries to find the library specified in the positional argument. The [result object](#external-library-object) can be used just like the return value of `dependency`. If the keyword argument `required` is false, Meson will proceed even if the library is not found. By default the library is searched for in the system library directory (e.g. /usr/lib). This can be overridden with the `dirs` keyword argument, which can be either a string or a list of strings. -- `sizeof(typename, ...)` returns the size of the given type (e.g. `'int'`) or -1 if the type is unknown, to add includes set them in the `prefix` keyword argument, you can specify external dependencies to use with `dependencies` keyword argument -- `alignment(typename)` returns the alignment of the type specified in the positional argument, you can specify external dependencies to use with `dependencies` keyword argument -- `compiles(code)` returns true if the code fragment given in the positional argument compiles, you can specify external dependencies to use with `dependencies` keyword argument, `code` can be either a string containing source code or a `file` object pointing to the source code -- `links(code)` returns true if the code fragment given in the positional argument compiles and links, you can specify external dependencies to use with `dependencies` keyword argument, `code` can be either a string containing source code or a `file` object pointing to the source code -- `run(code)` attempts to compile and execute the given code fragment, returns a run result object, you can specify external dependencies to use with `dependencies` keyword argument, `code` can be either a string containing source code or a `file` object pointing to the source code +- `sizeof(typename, ...)` returns the size of the given type (e.g. `'int'`) or -1 if the type is unknown, to add includes set them in the `prefix` keyword argument, you can specify external dependencies to use with `dependencies` keyword argument. +- `alignment(typename)` returns the alignment of the type specified in the positional argument, you can specify external dependencies to use with `dependencies` keyword argument. +- `compiles(code)` returns true if the code fragment given in the positional argument compiles, you can specify external dependencies to use with `dependencies` keyword argument, `code` can be either a string containing source code or a `file` object pointing to the source code. +- `links(code)` returns true if the code fragment given in the positional argument compiles and links, you can specify external dependencies to use with `dependencies` keyword argument, `code` can be either a string containing source code or a `file` object pointing to the source code. +- `run(code)` attempts to compile and execute the given code fragment, returns a run result object, you can specify external dependencies to use with `dependencies` keyword argument, `code` can be either a string containing source code or a `file` object pointing to the source code. - `has_header` returns true if the specified header can be included, you can specify external dependencies to use with `dependencies` keyword argument and extra code to put above the header test with the `prefix` keyword. In order to look for headers in a specific directory you can use `args : '-I/extra/include/dir`, but this should only be used in exceptional cases for includes that can't be detected via pkg-config and passed via `dependencies`. -- `has_type(typename)` returns true if the specified token is a type, you can specify external dependencies to use with `dependencies` keyword argument -- `has_function(funcname)` returns true if the given function is provided by the standard library or a library passed in with the `args` keyword, you can specify external dependencies to use with `dependencies` keyword argument -- `has_member(typename, membername)` takes two arguments, type name and member name and returns true if the type has the specified member, you can specify external dependencies to use with `dependencies` keyword argument -- `has_members(typename, membername1, membername2, ...)` takes at least two arguments, type name and one or more member names, returns true if the type has all the specified members, you can specify external dependencies to use with `dependencies` keyword argument -- `has_header_symbol(headername, symbolname)` allows one to detect whether a particular symbol (function, variable, #define, type definition, etc) is declared in the specified header, you can specify external dependencies to use with `dependencies` keyword argument -- `has_argument(argument_name)` returns true if the compiler accepts the specified command line argument, that is, can compile code without erroring out or printing a warning about an unknown flag, you can specify external dependencies to use with `dependencies` keyword argument -- `has_multi_arguments(arg1, arg2, arg3, ...)` is the same as `has_argument` but takes multiple arguments and uses them all in a single compiler invocation, available since 0.37.0 -- `first_supported_argument(list_of_strings)`, given a list of strings, returns the first argument that passes the `has_argument` test above or an empty array if none pass -- `symbols_have_underscore_prefix()` returns `true` if the C symbol mangling is one underscore (`_`) prefixed to the symbol, available since 0.37.0 +- `has_type(typename)` returns true if the specified token is a type, you can specify external dependencies to use with `dependencies` keyword argument. +- `has_function(funcname)` returns true if the given function is provided by the standard library or a library passed in with the `args` keyword, you can specify external dependencies to use with `dependencies` keyword argument. +- `has_member(typename, membername)` takes two arguments, type name and member name and returns true if the type has the specified member, you can specify external dependencies to use with `dependencies` keyword argument. +- `has_members(typename, membername1, membername2, ...)` takes at least two arguments, type name and one or more member names, returns true if the type has all the specified members, you can specify external dependencies to use with `dependencies` keyword argument. +- `has_header_symbol(headername, symbolname)` allows one to detect whether a particular symbol (function, variable, #define, type definition, etc) is declared in the specified header, you can specify external dependencies to use with `dependencies` keyword argument. +- `has_argument(argument_name)` returns true if the compiler accepts the specified command line argument, that is, can compile code without erroring out or printing a warning about an unknown flag, you can specify external dependencies to use with `dependencies` keyword argument. +- `has_multi_arguments(arg1, arg2, arg3, ...)` is the same as `has_argument` but takes multiple arguments and uses them all in a single compiler invocation, available since 0.37.0. +- `first_supported_argument(list_of_strings)`, given a list of strings, returns the first argument that passes the `has_argument` test above or an empty array if none pass. +- `symbols_have_underscore_prefix()` returns `true` if the C symbol mangling is one underscore (`_`) prefixed to the symbol, available since 0.37.0. - `compute_int(expr, ...')` computes the value of the given expression (as an example `1 + 2`). When cross compiling this is evaluated with an iterative algorithm, you can specify keyword arguments `low` (defaults to -1024), `high` (defaults to 1024) and `guess` to specify max and min values for the search and the value to try first. -- `get_define(definename)` returns the given preprocessor symbol's value as a string or empty string if it is not defined +- `get_define(definename)` returns the given preprocessor symbol's value as a string or empty string if it is not defined. The following keyword arguments can be used: diff --git a/docs/markdown/Release-notes-for-0.41.0.md b/docs/markdown/Release-notes-for-0.41.0.md index 2b7469a..a96ded0 100644 --- a/docs/markdown/Release-notes-for-0.41.0.md +++ b/docs/markdown/Release-notes-for-0.41.0.md @@ -25,6 +25,34 @@ ninja itself, providing better interoperability with custom commands. This support may not be perfect; please report any issues found with special characters to the issue tracker. +## Pkgconfig support for custom variables + +The Pkgconfig module object can add arbitrary variables to the generated .pc +file with the new `variables` keyword: +```meson +pkg.generate(libraries : libs, + subdirs : h, + version : '1.0', + name : 'libsimple', + filebase : 'simple', + description : 'A simple demo library.', + variables : ['datadir=${prefix}/data']) +``` + +## A target for creating tarballs + +Creating distribution tarballs is simple: + + ninja dist + +This will create a `.tar.xz` archive of the source code including +submodules without any revision control information. This command also +verifies that the resulting archive can be built, tested and +installed. This is roughly equivalent to the `distcheck` target in +other build systems. Currently this only works for projects using Git +and only with the Ninja backend. + + ## Support for passing arguments to Rust compiler -Targets for building rust now take a `rust_args` keyword.
\ No newline at end of file +Targets for building rust now take a `rust_args` keyword. diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index 2dbb755..0e8da43 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -58,7 +58,7 @@ If you are not using an IDE, Meson uses the [Ninja build system](https://ninja-b ninja -The main usability difference between Ninja and Make is that Ninja will automatically detect the number of CPUs in your computer and parallelize itself accordingly. You can override the amount of parallel processes used with the command line argument `-j <num processes>`. +The main usability difference between Ninja and Make is that Ninja will automatically detect the number of CPUs in your computer and parallelize itself accordingly. You can override the amount of parallel processes used with the command line argument `-j <num processes>`. It should be noted that after the initial configure step `ninja` is the only command you ever need to type to compile. No matter how you alter your source tree (short of moving it to a completely new location), Meson will detect the changes and regenerate itself accordingly. This is especially handy if you have multiple build directories. Often one of them is used for development (the "debug" build) and others only every now and then (such as a "static analysis" build). Any configuration can be built just by `cd`'ing to the corresponding directory and running Ninja. diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index 6f43887..2a7428b 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -103,7 +103,7 @@ Strings also support a number of other methods that return transformed copies. ```meson # Similar to the Python str.strip(). Removes leading/ending spaces and newlines define = ' -Dsomedefine ' -stripped_define = target.strip() +stripped_define = define.strip() # 'stripped_define' now has the value '-Dsomedefine' ``` diff --git a/docs/markdown/legal.md b/docs/markdown/legal.md index 56ab70b..474d129 100644 --- a/docs/markdown/legal.md +++ b/docs/markdown/legal.md @@ -1,6 +1,6 @@ # Legal information -Meson is copyrighted by all members of the Meson development team. For details see the <tt>authors.txt</tt> file that comes with the source code. Meson is licensed under the [Apache 2 license]. +Meson is copyrighted by all members of the Meson development team. Meson is licensed under the [Apache 2 license]. Meson is a registered trademark of Jussi Pakkanen. diff --git a/docs/sitemap.txt b/docs/sitemap.txt index c4bb0d4..9dceb05 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -42,6 +42,7 @@ index.md Build-system-converters.md Configuring-a-build-directory.md Run-targets.md + Creating-releases.md Creating-OSX-packages.md Creating-Linux-binaries.md Reference-manual.md |