aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/markdown/Builtin-options.md2
-rw-r--r--docs/markdown/Cuda-module.md183
-rw-r--r--docs/markdown/Dependencies.md19
-rw-r--r--docs/markdown/External-commands.md8
-rw-r--r--docs/markdown/Reference-manual.md6
-rw-r--r--docs/markdown/howtox.md17
-rw-r--r--docs/markdown/i18n-module.md1
-rw-r--r--docs/markdown/snippets/cmake_module_path.md9
-rw-r--r--docs/markdown/snippets/fortran_submodule.md12
-rw-r--r--docs/markdown/snippets/hdf5.md3
-rw-r--r--docs/markdown/snippets/run_command_env.md9
-rw-r--r--docs/sitemap.txt1
12 files changed, 267 insertions, 3 deletions
diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index 288bd79..0d1a16b 100644
--- a/docs/markdown/Builtin-options.md
+++ b/docs/markdown/Builtin-options.md
@@ -42,7 +42,7 @@ Installation options are all relative to the prefix, except:
| werror | false | Treat warnings as errors |
| warning_level {1, 2, 3} | 1 | Set the warning level. From 1 = lowest to 3 = highest |
| layout {mirror,flat} | mirror | Build directory layout. |
-| default-library {shared, static, both} | shared | Default library type. |
+| default_library {shared, static, both} | shared | Default library type. |
| backend {ninja, vs,<br>vs2010, vs2015, vs2017, xcode} | | Backend to use (default: ninja). |
| stdsplit | | Split stdout and stderr in test logs. |
| errorlogs | | Whether to print the logs from failing tests. |
diff --git a/docs/markdown/Cuda-module.md b/docs/markdown/Cuda-module.md
new file mode 100644
index 0000000..caa1756
--- /dev/null
+++ b/docs/markdown/Cuda-module.md
@@ -0,0 +1,183 @@
+---
+short-description: CUDA module
+authors:
+ - name: Olexa Bilaniuk
+ years: [2019]
+ has-copyright: false
+...
+
+# Unstable CUDA Module
+_Since: 0.50.0_
+
+This module provides helper functionality related to the CUDA Toolkit and
+building code using it.
+
+
+**Note**: this module is unstable. It is only provided as a technology preview.
+Its API may change in arbitrary ways between releases or it might be removed
+from Meson altogether.
+
+
+## Importing the module
+
+The module may be imported as follows:
+
+``` meson
+cuda = import('unstable-cuda')
+```
+
+It offers several useful functions that are enumerated below.
+
+
+## Functions
+
+### `nvcc_arch_flags()`
+_Since: 0.50.0_
+
+``` meson
+cuda.nvcc_arch_flags(nvcc_or_version, ...,
+ detected: string_or_array)
+```
+
+Returns a list of `-gencode` flags that should be passed to `cuda_args:` in
+order to compile a "fat binary" for the architectures/compute capabilities
+enumerated in the positional argument(s). The flags shall be acceptable to
+the NVCC compiler object `nvcc_or_version`, or its version string.
+
+A set of architectures and/or compute capabilities may be specified by:
+
+- The single positional argument `'All'`, `'Common'` or `'Auto'`
+- As (an array of)
+ - Architecture names (`'Kepler'`, `'Maxwell+Tegra'`, `'Turing'`) and/or
+ - Compute capabilities (`'3.0'`, `'3.5'`, `'5.3'`, `'7.5'`)
+
+A suffix of `+PTX` requests PTX code generation for the given architecture.
+A compute capability given as `A.B(X.Y)` requests PTX generation for an older
+virtual architecture `X.Y` before binary generation for a newer architecture
+`A.B`.
+
+Multiple architectures and compute capabilities may be passed in using
+
+- Multiple positional arguments
+- Lists of strings
+- Space (` `), comma (`,`) or semicolon (`;`)-separated strings
+
+The single-word architectural sets `'All'`, `'Common'` or `'Auto'` cannot be
+mixed with architecture names or compute capabilities. Their interpretation is:
+
+| Name | Compute Capability |
+|-------------------|--------------------|
+| `'All'` | All CCs supported by given NVCC compiler. |
+| `'Common'` | Relatively common CCs supported by given NVCC compiler. Generally excludes Tegra and Tesla devices. |
+| `'Auto'` | The CCs provided by the `detected:` keyword, filtered for support by given NVCC compiler. |
+
+The supported architecture names and their corresponding compute capabilities
+are:
+
+| Name | Compute Capability |
+|-------------------|--------------------|
+| `'Fermi'` | 2.0, 2.1(2.0) |
+| `'Kepler'` | 3.0, 3.5 |
+| `'Kepler+Tegra'` | 3.2 |
+| `'Kepler+Tesla'` | 3.7 |
+| `'Maxwell'` | 5.0, 5.2 |
+| `'Maxwell+Tegra'` | 5.3 |
+| `'Pascal'` | 6.0, 6.1 |
+| `'Pascal+Tegra'` | 6.2 |
+| `'Volta'` | 7.0 |
+| `'Volta+Tegra'` | 7.2 |
+| `'Turing'` | 7.5 |
+
+
+Examples:
+
+ cuda.nvcc_arch_flags('10.0', '3.0', '3.5', '5.0+PTX')
+ cuda.nvcc_arch_flags('10.0', ['3.0', '3.5', '5.0+PTX'])
+ cuda.nvcc_arch_flags('10.0', [['3.0', '3.5'], '5.0+PTX'])
+ cuda.nvcc_arch_flags('10.0', '3.0 3.5 5.0+PTX')
+ cuda.nvcc_arch_flags('10.0', '3.0,3.5,5.0+PTX')
+ cuda.nvcc_arch_flags('10.0', '3.0;3.5;5.0+PTX')
+ cuda.nvcc_arch_flags('10.0', 'Kepler 5.0+PTX')
+ # Returns ['-gencode', 'arch=compute_30,code=sm_30',
+ # '-gencode', 'arch=compute_35,code=sm_35',
+ # '-gencode', 'arch=compute_50,code=sm_50',
+ # '-gencode', 'arch=compute_50,code=compute_50']
+
+ cuda.nvcc_arch_flags('10.0', '3.5(3.0)')
+ # Returns ['-gencode', 'arch=compute_30,code=sm_35']
+
+ cuda.nvcc_arch_flags('8.0', 'Common')
+ # Returns ['-gencode', 'arch=compute_30,code=sm_30',
+ # '-gencode', 'arch=compute_35,code=sm_35',
+ # '-gencode', 'arch=compute_50,code=sm_50',
+ # '-gencode', 'arch=compute_52,code=sm_52',
+ # '-gencode', 'arch=compute_60,code=sm_60',
+ # '-gencode', 'arch=compute_61,code=sm_61',
+ # '-gencode', 'arch=compute_61,code=compute_61']
+
+ cuda.nvcc_arch_flags('9.2', 'Auto', detected: '6.0 6.0 6.0 6.0')
+ cuda.nvcc_arch_flags('9.2', 'Auto', detected: ['6.0', '6.0', '6.0', '6.0'])
+ # Returns ['-gencode', 'arch=compute_60,code=sm_60']
+
+ cuda.nvcc_arch_flags(nvcc, 'All')
+ # Returns ['-gencode', 'arch=compute_20,code=sm_20',
+ # '-gencode', 'arch=compute_20,code=sm_21',
+ # '-gencode', 'arch=compute_30,code=sm_30',
+ # '-gencode', 'arch=compute_32,code=sm_32',
+ # '-gencode', 'arch=compute_35,code=sm_35',
+ # '-gencode', 'arch=compute_37,code=sm_37',
+ # '-gencode', 'arch=compute_50,code=sm_50', # nvcc.version() < 7.0
+ # '-gencode', 'arch=compute_52,code=sm_52',
+ # '-gencode', 'arch=compute_53,code=sm_53', # nvcc.version() >= 7.0
+ # '-gencode', 'arch=compute_60,code=sm_60',
+ # '-gencode', 'arch=compute_61,code=sm_61', # nvcc.version() >= 8.0
+ # '-gencode', 'arch=compute_70,code=sm_70',
+ # '-gencode', 'arch=compute_72,code=sm_72', # nvcc.version() >= 9.0
+ # '-gencode', 'arch=compute_75,code=sm_75'] # nvcc.version() >= 10.0
+
+_Note:_ This function is intended to closely replicate CMake's FindCUDA module
+function `CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable, [list of CUDA compute architectures])`
+
+
+
+### `nvcc_arch_readable()`
+_Since: 0.50.0_
+
+``` meson
+cuda.nvcc_arch_readable(nvcc_or_version, ...,
+ detected: string_or_array)
+```
+
+Has precisely the same interface as [`nvcc_arch_flags()`](#nvcc_arch_flags),
+but rather than returning a list of flags, it returns a "readable" list of
+architectures that will be compiled for. The output of this function is solely
+intended for informative message printing.
+
+ archs = '3.0 3.5 5.0+PTX'
+ readable = cuda.nvcc_arch_readable(nvcc, archs)
+ message('Building for architectures ' + ' '.join(readable))
+
+This will print
+
+ Message: Building for architectures sm30 sm35 sm50 compute50
+
+_Note:_ This function is intended to closely replicate CMake's FindCUDA module function
+`CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable, [list of CUDA compute architectures])`
+
+
+
+### `min_driver_version()`
+_Since: 0.50.0_
+
+``` meson
+cuda.min_driver_version(nvcc_or_version)
+```
+
+Returns the minimum NVIDIA proprietary driver version required, on the host
+system, by kernels compiled with the given NVCC compiler or its version string.
+
+The output of this function is generally intended for informative message
+printing, but could be used for assertions or to conditionally enable
+features known to exist within the minimum NVIDIA driver required.
+
+
diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md
index e3fedc4..259f09e 100644
--- a/docs/markdown/Dependencies.md
+++ b/docs/markdown/Dependencies.md
@@ -148,6 +148,14 @@ it automatically.
cmake_dep = dependency('ZLIB', method : 'cmake', modules : ['ZLIB::ZLIB'])
```
+It is also possible to reuse existing `Find<name>.cmake` files with the
+`cmake_module_path` property. Using this property is equivalent to setting the
+`CMAKE_MODULE_PATH` variable in CMake. The path(s) given to `cmake_module_path`
+should all be relative to the project source directory. Absolute paths
+should only be used if the CMake files are not stored in the project itself.
+
+Additional CMake parameters can be specified with the `cmake_args` property.
+
### Some notes on Dub
Please understand that meson is only able to find dependencies that
@@ -269,6 +277,17 @@ e = executable('testprog', 'test.cc', dependencies : gtest_dep)
test('gtest test', e)
```
+## HDF5
+HDF5 is supported for C, C++ and Fortran. Because dependencies are
+language-specific, you must specify the requested language using the
+`language` keyword argument, i.e.,
+ * `dependency('hdf5', language: 'c')` for the C HDF5 headers and libraries
+ * `dependency('hdf5', language: 'cpp')` for the C++ HDF5 headers and libraries
+ * `dependency('hdf5', language: 'fortran')` for the Fortran HDF5 headers and libraries
+
+Meson uses pkg-config to find HDF5. The standard low-level HDF5 function and the `HL` high-level HDF5 functions are linked for each language.
+
+
## libwmf
*(added 0.44.0)*
diff --git a/docs/markdown/External-commands.md b/docs/markdown/External-commands.md
index 9336ec3..4c8c8e4 100644
--- a/docs/markdown/External-commands.md
+++ b/docs/markdown/External-commands.md
@@ -16,6 +16,14 @@ output = r.stdout().strip()
errortxt = r.stderr().strip()
```
+Additionally, since 0.50.0, you can pass the command [`environment`](Reference-manual.html#environment-object) object:
+
+```meson
+env = environment()
+env.set('FOO', 'bar')
+run_command('command', 'arg1', 'arg2', env: env)
+```
+
The `run_command` function returns an object that can be queried for
return value and text written to stdout and stderr. The `strip` method
call is used to strip trailing and leading whitespace from
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index e913e25..db43813 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1183,12 +1183,14 @@ and Meson will set three environment variables `MESON_SOURCE_ROOT`,
directory, build directory and subdirectory the target was defined in,
respectively.
-This function has one keyword argument.
+This function supports the following keyword arguments:
- `check` takes a boolean. If `true`, the exit status code of the command will
be checked, and the configuration will fail if it is non-zero. The default is
`false`.
Since 0.47.0
+ - `env` an [environment object](#environment-object) to use a custom environment
+ Since 0.50.0
See also [External commands](External-commands.md).
@@ -2175,7 +2177,7 @@ and has the following methods:
This object is returned by [`environment()`](#environment) and stores
detailed information about how environment variables should be set
during tests. It should be passed as the `env` keyword argument to
-tests. It has the following methods.
+tests and other functions. It has the following methods.
- `append(varname, value1, value2, ...)` appends the given values to
the old value of the environment variable, e.g. `env.append('FOO',
diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md
index 3d8515f..8ae4fde 100644
--- a/docs/markdown/howtox.md
+++ b/docs/markdown/howtox.md
@@ -203,3 +203,20 @@ executable(..., dependencies : m_dep)
```meson
executable(..., install : true, install_dir : get_option('libexecdir'))
```
+
+## Use existing `Find<name>.cmake` files
+
+Meson can use the CMake `find_package()` ecosystem if CMake is installed.
+To find a dependency with custom `Find<name>.cmake`, set the `cmake_module_path`
+property to the path in your project where the CMake scripts are stored.
+
+Example for a `FindCmakeOnlyDep.cmake` in a `cmake` subdirectory:
+
+```meson
+cm_dep = dependency('CmakeOnlyDep', cmake_module_path : 'cmake')
+```
+
+The `cmake_module_path` property is only needed for custom CMake scripts. System
+wide CMake scripts are found automatically.
+
+More information can be found [here](Dependencies.md#cmake)
diff --git a/docs/markdown/i18n-module.md b/docs/markdown/i18n-module.md
index 88f059b..9053edc 100644
--- a/docs/markdown/i18n-module.md
+++ b/docs/markdown/i18n-module.md
@@ -29,6 +29,7 @@ argument which is the name of the gettext module.
[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.
+* `install_dir`: (*Added 0.50.0*) override default install location, default is `localedir`
This function also defines targets for maintainers to use:
**Note**: These output to the source directory
diff --git a/docs/markdown/snippets/cmake_module_path.md b/docs/markdown/snippets/cmake_module_path.md
new file mode 100644
index 0000000..7beb453
--- /dev/null
+++ b/docs/markdown/snippets/cmake_module_path.md
@@ -0,0 +1,9 @@
+## Added `cmake_module_path` and `cmake_args` to dependency
+
+The CMake dependency backend can now make use of existing `Find<name>.cmake`
+files by setting the `CMAKE_MODULE_PATH` with the new `dependency()` property
+`cmake_module_path`. The paths given to `cmake_module_path` should be relative
+to the project source directory.
+
+Furthermore the property `cmake_args` was added to give CMake additional
+parameters.
diff --git a/docs/markdown/snippets/fortran_submodule.md b/docs/markdown/snippets/fortran_submodule.md
new file mode 100644
index 0000000..9e4b9cc
--- /dev/null
+++ b/docs/markdown/snippets/fortran_submodule.md
@@ -0,0 +1,12 @@
+## Fortran submodule support
+
+Initial support for Fortran ``submodule`` was added, where the submodule is in
+the same or different file than the parent ``module``.
+The submodule hierarchy specified in the source Fortran code `submodule`
+statements are used by Meson to resolve source file dependencies.
+For example:
+
+```fortran
+submodule (ancestor:parent) child
+```
+
diff --git a/docs/markdown/snippets/hdf5.md b/docs/markdown/snippets/hdf5.md
new file mode 100644
index 0000000..8ebb4c0
--- /dev/null
+++ b/docs/markdown/snippets/hdf5.md
@@ -0,0 +1,3 @@
+## HDF5
+
+HDF5 support is added via pkg-config.
diff --git a/docs/markdown/snippets/run_command_env.md b/docs/markdown/snippets/run_command_env.md
new file mode 100644
index 0000000..dfa5ac5
--- /dev/null
+++ b/docs/markdown/snippets/run_command_env.md
@@ -0,0 +1,9 @@
+## `run_command` accepts `env` kwarg
+
+You can pass [`environment`](Reference-manual.html#environment-object) object to [`run_command`](Reference-manual.html#run-command), just like to `test`:
+
+```meson
+env = environment()
+env.set('FOO', 'bar')
+run_command('command', 'arg1', 'arg2', env: env)
+```
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index f80c279..6987641 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -44,6 +44,7 @@ index.md
RPM-module.md
Simd-module.md
Windows-module.md
+ Cuda-module.md
Java.md
Vala.md
D.md
generated by cgit v1.1 at 2025-07-30 16:08:35 +0000