diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Fs-module.md | 87 | ||||
| -rw-r--r-- | docs/markdown/Pkgconfig-module.md | 11 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 37 | ||||
| -rw-r--r-- | docs/markdown/snippets/more_meson_sample_templates.md | 6 | ||||
| -rw-r--r-- | docs/markdown/snippets/native_property.md | 18 | ||||
| -rw-r--r-- | docs/markdown/snippets/per_subproject_builtin.md | 15 | ||||
| -rw-r--r-- | docs/markdown/snippets/uninstalled-pkgconfig.md | 8 | ||||
| -rw-r--r-- | docs/theme/extra/templates/navbar_links.html | 47 |
8 files changed, 192 insertions, 37 deletions
diff --git a/docs/markdown/Fs-module.md b/docs/markdown/Fs-module.md index 53bf960..e5941a9 100644 --- a/docs/markdown/Fs-module.md +++ b/docs/markdown/Fs-module.md @@ -9,6 +9,13 @@ Non-absolute paths are looked up relative to the directory where the current `meson.build` file is. If specified, a leading `~` is expanded to the user home directory. +Environment variables are not available as is the rule throughout Meson. +That is, $HOME, %USERPROFILE%, $MKLROOT, etc. have no meaning to the Meson +filesystem module. If needed, pass such variables into Meson via command +line options in `meson_options.txt`, native-file or cross-file. + +Where possible, symlinks and parent directory notation are resolved to an +absolute path. ### exists @@ -19,13 +26,12 @@ special entry such as a device node. ### is_dir Takes a single string argument and returns true if a directory with -that name exists on the file system. This method follows symbolic -links. +that name exists on the file system. ### is_file Takes a single string argument and returns true if an file with that -name exists on the file system. This method follows symbolic links. +name exists on the file system. ### is_symlink @@ -34,6 +40,25 @@ by the string is a symbolic link. ## File Parameters +### is_absolute + +*since 0.54.0* + +Return a boolean indicating if the path string specified is absolute, WITHOUT expanding `~`. + +Examples: + +```meson +fs.is_absolute('~') # false + +home = fs.expanduser('~') +fs.is_absolute(home) # true + +fs.is_absolute(home / 'foo') # true, even if ~/foo doesn't exist + +fs.is_absolute('foo/bar') # false, even if ./foo/bar exists +``` + ### hash The `fs.hash(filename, hash_algorithm)` method returns a string containing @@ -44,7 +69,6 @@ md5, sha1, sha224, sha256, sha384, sha512. ### size The `fs.size(filename)` method returns the size of the file in integer bytes. -Symlinks will be resolved if possible. ### is_samepath @@ -67,7 +91,7 @@ fs.is_samepath(x, z) # true fs.is_samepath(x, j) # false p = 'foo/bar' -q = 'foo/bar/../baz' +q = 'foo/bar/baz/..' r = 'buz' # a symlink pointing to foo/bar s = 'notapath' # non-existant directory @@ -76,10 +100,39 @@ fs.is_samepath(p, r) # true fs.is_samepath(p, s) # false ``` - ## Filename modification -The files need not actually exist yet for this method, as it's just string manipulation. +The files need not actually exist yet for these path string manipulation methods. + +### expanduser + +*since 0.54.0* + +A path string with a leading `~` is expanded to the user home directory + +Examples: + +```meson +fs.expanduser('~') # user home directory + +fs.expanduser('~/foo') # <homedir>/foo +``` + +### as_posix + +*since 0.54.0* + +`fs.as_posix(path)` assumes a Windows path, even if on a Unix-like system. +Thus, all `'\'` or `'\\'` are turned to '/', even if you meant to escape a character. + +Examples + +```meson +fs.as_posix('\\') == '/' # true +fs.as_posix('\\\\') == '/' # true + +fs.as_posix('foo\\bar/baz') == 'foo/bar/baz' # true +``` ### replace_suffix @@ -118,6 +171,26 @@ new = fs.replace_suffix(original, '') # /opt/foo.dll Returns the parent directory (i.e. dirname). +```meson +new = fs.parent('foo/bar') # foo +new = fs.parent('foo/bar/baz.dll') # foo/bar +``` + ### name Returns the last component of the path (i.e. basename). + +```meson +fs.name('foo/bar/baz.dll.a') # baz.dll.a +``` + +### stem + +*since 0.54.0* + +Returns the last component of the path, dropping the last part of the suffix + +```meson +fs.stem('foo/bar/baz.dll') # baz +fs.stem('foo/bar/baz.dll.a') # baz.dll +``` diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md index 4aa82f6..678090b 100644 --- a/docs/markdown/Pkgconfig-module.md +++ b/docs/markdown/Pkgconfig-module.md @@ -54,6 +54,8 @@ keyword arguments. `Version:` field. (*since 0.46.0*) Defaults to the project version if unspecified. - `d_module_versions` a list of module version flags used when compiling D sources referred to by this pkg-config file +- `uninstalled_variables` used instead of the `variables` keyword argument, when + generating the uninstalled pkg-config file. Since *0.54.0* Since 0.46 a `StaticLibrary` or `SharedLibrary` object can optionally be passed as first positional argument. If one is provided a default value will be @@ -62,6 +64,15 @@ provided for all required fields of the pc file: - `description` is set to the project's name followed by the library's name. - `name` is set to the library's name. +Since 0.54.0 uninstalled pkg-config files are generated as well. They are +located in `<build dir>/meson-uninstalled/`. It is sometimes +useful to build projects against libraries built by meson without having to +install them into a prefix. In order to do so, just set +`PKG_CONFIG_PATH=<builddir>/meson-uninstalled` before building your +application. That will cause pkg-config to prefer those `-uninstalled.pc` files +and find libraries and headers from the meson builddir. This is an experimental +feature provided on a best-effort basis, it might not work in all use-cases. + ### Implicit dependencies The exact rules followed to find dependencies that are implicitly added into the diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 57fc1f7..510d443 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -547,11 +547,12 @@ libraries (`.so`, `.dll`, etc) will be linked. With the Ninja backend, Meson will create a build-time [order-only dependency](https://ninja-build.org/manual.html#ref_dependencies) on -all generated input files, including unknown files. For all input -files (generated and non-generated), Meson uses the [dependency -file](https://ninja-build.org/manual.html#ref_headers) generated by -your compiler to determine when to rebuild sources. The behavior is -similar for other backends. +all generated input files, including unknown files. This is needed +to bootstrap the generation of the real dependencies in the +[depfile](https://ninja-build.org/manual.html#ref_headers) +generated by your compiler to determine when to rebuild sources. +Ninja relies on this dependency file for all input files, generated +and non-generated. The behavior is similar for other backends. Executable supports the following keyword arguments. Note that just like the positional arguments above, these keyword arguments can also @@ -1552,7 +1553,8 @@ arguments: that override those set in the subproject's `meson_options.txt` (like `default_options` in `project`, they only have effect when Meson is run for the first time, and command line arguments override - any default options in build files) + any default options in build files). *Since 0.54.0* `default_library` + built-in option can also be overridden. - `version` keyword argument that works just like the one in `dependency`. It specifies what version the subproject should be, as an example `>=1.0.1` @@ -1773,10 +1775,6 @@ the following methods. refer to files in the current or any other source directory instead of constructing paths manually with `meson.current_source_dir()`. -- `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_compiler(language)` returns [an object describing a compiler](#compiler-object), takes one positional argument which is the language to use. It also accepts one keyword argument, `native` @@ -1786,6 +1784,19 @@ the following methods. returns the "cross" compiler if we're currently cross-compiling and the "native" compiler if we're not. +- `get_cross_property(propname, fallback_value)` + *Consider get_external_property() instead*. Returns the given + property from a cross file, the optional fallback_value is returned + if not cross compiling or the given property is not found. + +- `get_external_property(propname, fallback_value, native: true/false)` + *(added 0.54.0)* returns the given property from a native or cross file. + The optional fallback_value is returned if the given property is not found. + The optional `native: true` forces retrieving a variable from the + native file, even when cross-compiling. + If `native: false` or not specified, variable is retrieved from the + cross-file if cross-compiling, and from the native-file when not cross-compiling. + - `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, @@ -2299,6 +2310,8 @@ contains a target with the following methods: 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. + *Since 0.54.0* it can be also called on indexes objects: + `custom_targets[i].full_path()`. - `[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 @@ -2306,6 +2319,10 @@ contains a target with the following methods: source added will be the one that corresponds to the index of the custom target's output argument. +- `to_list()` *Since 0.54.0*, returns a list of opaque objects that references + this target, and can be used as a source in other targets. This can be used to + iterate outputs with `foreach` loop. + ### `dependency` object This object is returned by [`dependency()`](#dependency) and contains diff --git a/docs/markdown/snippets/more_meson_sample_templates.md b/docs/markdown/snippets/more_meson_sample_templates.md new file mode 100644 index 0000000..e10da9c --- /dev/null +++ b/docs/markdown/snippets/more_meson_sample_templates.md @@ -0,0 +1,6 @@ +## More new sample Meson templates for (`Java`, `Cuda`, and more) + +Meson now ships with predefined project templates for `Java`, +`Cuda`, `Objective-C++`, and `C#`, we provided with associated +values for corresponding languages, avalable for both library, +and executable. diff --git a/docs/markdown/snippets/native_property.md b/docs/markdown/snippets/native_property.md new file mode 100644 index 0000000..d3808d8 --- /dev/null +++ b/docs/markdown/snippets/native_property.md @@ -0,0 +1,18 @@ +## Native file properties + +As of Meson 0.54.0, the `--native-file nativefile.ini` can contain: + +* binaries +* paths +* properties + +which are defined and used the same way as in cross files. +The `properties` are new for Meson 0.54.0, and are read like: + +```meson +x = meson.get_external_property('foobar', 'foo') +``` + +where `foobar` is the property name, and the optional `foo` is the fallback string value. + +For cross-compiled projects, `get_external_property()` reads the cross-file unless `native: true` is specified.
\ No newline at end of file diff --git a/docs/markdown/snippets/per_subproject_builtin.md b/docs/markdown/snippets/per_subproject_builtin.md new file mode 100644 index 0000000..44ed1c8 --- /dev/null +++ b/docs/markdown/snippets/per_subproject_builtin.md @@ -0,0 +1,15 @@ +## Per subproject `default_library` option + +The `default_library` built-in option can now be defined per subproject. This is +useful for example when building shared libraries in the main project, but static +link a subproject. + +Most of the time this would be used either by the parent project by setting +subproject's default_options (e.g. `subproject('foo', default_options: 'default_library=static')`), +or by the user using the command line `-Dfoo:default_library=static`. + +The value is overriden in this order: +- Value from parent project +- Value from subproject's default_options if set +- Value from subproject() default_options if set +- Value from command line if set diff --git a/docs/markdown/snippets/uninstalled-pkgconfig.md b/docs/markdown/snippets/uninstalled-pkgconfig.md new file mode 100644 index 0000000..2e265ab --- /dev/null +++ b/docs/markdown/snippets/uninstalled-pkgconfig.md @@ -0,0 +1,8 @@ +## Uninstalled pkg-config files + +The `pkgconfig` module now generates uninstalled pc files as well. For any generated +`foo.pc` file, an extra `foo-uninstalled.pc` file is placed into +`<builddir>/meson-uninstalled`. They can be used to build applications against +libraries built by meson without installing them, by pointing `PKG_CONFIG_PATH` +to that directory. This is an experimental feature provided on a best-effort +basis, it might not work in all use-cases. diff --git a/docs/theme/extra/templates/navbar_links.html b/docs/theme/extra/templates/navbar_links.html index 036c20f..6980f81 100644 --- a/docs/theme/extra/templates/navbar_links.html +++ b/docs/theme/extra/templates/navbar_links.html @@ -1,21 +1,28 @@ @require(page) <li class="dropdown"> - <a class="dropdown-toggle" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> - Modules <span class="caret"></span> - </a> - <ul class="dropdown-menu" id="modules-menu"> - @for tup in (("Gnome-module.html","GNOME"), \ - ("i18n-module.html","i18n"), \ - ("Pkgconfig-module.html","Pkgconfig"), \ - ("Python-module.html","Python"), \ - ("Python-3-module.html","Python 3"), \ - ("Qt4-module.html","Qt4"), \ - ("Qt5-module.html","Qt5"), \ - ("RPM-module.html","RPM"), \ - ("SourceSet-module.html","SourceSet"), \ - ("Windows-module.html","Windows"), \ - ("Hotdoc-module.html","Hotdoc")): + <a class="dropdown-toggle" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> + Modules <span class="caret"></span> + </a> + <ul class="dropdown-menu" id="modules-menu"> + @for tup in ( \ + ("CMake-module.html","CMake"), \ + ("Cuda-module.html","CUDA"), \ + ("Dlang-module.html","Dlang"), \ + ("Fs-module.html","Filesystem"), \ + ("Gnome-module.html","GNOME"), \ + ("Hotdoc-module.html","Hotdoc"), \ + ("i18n-module.html","i18n"), \ + ("Icestorm-module.html","Icestorm"), \ + ("Kconfig-module.html","kconfig"), \ + ("Pkgconfig-module.html","Pkgconfig"), \ + ("Python-module.html","Python"), \ + ("Python-3-module.html","Python 3"), \ + ("Qt4-module.html","Qt4"), \ + ("Qt5-module.html","Qt5"), \ + ("RPM-module.html","RPM"), \ + ("SourceSet-module.html","SourceSet"), \ + ("Windows-module.html","Windows")): <li> <a href="@tup[0]">@tup[1]</a> </li> @@ -29,11 +36,11 @@ </a> <ul class="dropdown-menu" id="quick-refs-menu"> @for tup in (("Reference-manual.html", "Functions"), \ - ("Build-options.html", "Options"), \ - ("Configuration.html", "Configuration"), \ - ("Dependencies.html", "Dependencies"), \ - ("Unit-tests.html", "Tests"), \ - ("Syntax.html", "Syntax")): + ("Build-options.html", "Options"), \ + ("Configuration.html", "Configuration"), \ + ("Dependencies.html", "Dependencies"), \ + ("Unit-tests.html", "Tests"), \ + ("Syntax.html", "Syntax")): <li> <a href="@tup[0]">@tup[1]</a> </li> |