diff options
| -rw-r--r-- | docs/markdown/CMake-module.md | 87 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 5 | ||||
| -rw-r--r-- | docs/markdown/Subprojects.md | 42 | ||||
| -rw-r--r-- | docs/markdown/snippets/cmake_subprojects.md | 38 |
4 files changed, 109 insertions, 63 deletions
diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md index 4cc97cf..3b65253 100644 --- a/docs/markdown/CMake-module.md +++ b/docs/markdown/CMake-module.md @@ -1,6 +1,8 @@ # CMake module This module provides helper tools for generating cmake package files. +It also supports the usage of CMake based subprojects, similar to +the normal [meson subprojects](Subprojects.md). ## Usage @@ -10,6 +12,91 @@ following functions will then be available as methods on the object with the name `cmake`. You can, of course, replace the name `cmake` with anything else. +## CMake subprojects + +Using CMake subprojects is similar to using the "normal" meson +subprojects. They also have to be located in the `subprojects` +directory. + +Example: + +```cmake +add_library(cm_lib SHARED ${SOURCES}) +``` + +```meson +cmake = import('cmake') + +# Configure the CMake project +sub_proj = cmake.subproject('libsimple_cmake') + +# Fetch the dependency object +cm_lib = sub_proj.dependency('cm_lib') + +executable(exe1, ['sources'], dependencies: [cm_lib]) +``` + +The `subproject` method is almost identical to the normal meson +`subproject` function. The only difference is that a CMake project +instead of a meson prokect is configured. + +Also, project specific CMake options can be added with the `cmake_options` key. + +The returned `sub_proj` supports the same options as a "normal" subproject. +Meson automatically detects CMake build targets, which can be accessed with +the methods listed [below](#subproject-object). + +It is usually enough to just use the dependency object returned by the +`dependency()` method in the build targets. This is almost identical to +using `declare_dependency()` object from a normal meson subproject. + +It is also possible to use executables defined in the CMake project as code +generators with the `target()` method: + +```cmake +add_executable(cm_exe ${EXE_SRC}) +``` + +```meson +cmake = import('cmake') + +# Subproject with the "code generator" +sub_pro = cmake.subproject('cmCodeGen') + +# Fetch the code generator exe +sub_exe = sub_pro.target('cm_exe') + +# Use the code generator +generated = custom_target( + 'cmake-generated', + input: [], + output: ['test.cpp'], + command: [sub_exe, '@OUTPUT@'] +) +``` + +It should be noted that not all projects are guaranteed to work. The +safest approach would still be to create a `meson.build` for the +subprojects in question. + +### `subproject` object + +This is object is returned by the `subproject` function described above +and supports the following methods: + + - `dependency(target)` returns a dependency object for any CMake target. + - `include_directories(target)` returns a meson include_directories + for the specified target. Using this function is not neccessary if the + dependency object is used. + - `target(target)` returns the raw build target. + - `target_type(target)` returns the type of the target as a string + - `target_list()` returns a list of all target *names*. + - `get_variable(name)` fetches the specified variable from inside + the subproject. Usually `dependency()` or `target()` should be + prefered to extract build targets. + +## CMake configuration files + ### cmake.write_basic_package_version_file() This function is the equivalent of the corresponding [CMake function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-version-file), diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 68c8f9d..0aa4253 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -1405,11 +1405,6 @@ arguments: - `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` - - `method` *(added 0.51.0)* Specifies the configuration method of the - subproject. Possible values are `meson`, `cmake` and `auto`. With - `auto` meson will always prefer a `meson.build` in the subproject - over other methods. The default value of `method` is `auto`. - - `cmake_options` *(added 0.51.0)* List of additional CMake options - `required` *(added 0.48.0)* By default, `required` is `true` and Meson will abort if the subproject could not be setup. You can set this to `false` and then use the `.found()` method on the [returned diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md index 21cb2cb..fc845ff 100644 --- a/docs/markdown/Subprojects.md +++ b/docs/markdown/Subprojects.md @@ -17,8 +17,11 @@ build without (in the best case) any changes to its Meson setup. It becomes a transparent part of the project. It should be noted that this is only guaranteed to work for subprojects -that are built with Meson. Using CMake based subprojects is not guaranteed -to work for all projects. +that are built with Meson. The reason is the simple fact that there is +no possible way to do this reliably with mixed build systems. Because of +this, only meson subprojects are described here. +[CMake based subprojects](CMake-module.md#CMake-subprojects) are also +supported but not guaranteed to work. ## A subproject example @@ -160,41 +163,6 @@ in the top level `subprojects` directory. Recursive use of subprojects is not allowed, though, so you can't have subproject `a` that uses subproject `b` and have `b` also use `a`. -## CMake subprojects - -Meson is also able to use CMake subprojects directly. Using CMake -subprojects is almost identical to using the "normal" meson subprojects: - -```meson -sub_proj = subproject('libsimple_cmake', method : 'cmake') -``` - -The `method` key is optional if the subproject only has a `CMakeList.txt`. -Without specifying a method meson will always first try to find and use a -`meson.build` in the subproject. - -Project specific CMake options can be added with the `cmake_options` key. - -The returned `sub_proj` supports the same options as a "normal" subproject. -Meson automatically detects build targets, which can be retrieved with -`get_variable`. Meson also generates a dependency object for each target. - -These variable names are generated based on the CMake target name. - -```cmake -add_library(cm_exe SHARED ${SOURCES}) -``` - -For `cm_exe`, meson will then define the following variables: - -- `cm_exe` The raw library target (similar to `cm_exe = library('cm_exe', ...)` in meson) -- `cm_exe_dep` The dependency object for the target (similar to `declare_dependency()` in meson) -- `cm_exe_inc` A meson include directory object, containing all include irectories of the target. - -It should be noted that not all projects are guaranteed to work. The -safest approach would still be to create a `meson.build` for the -subprojects in question. - ## Obtaining subprojects Meson ships with a dependency system to automatically obtain diff --git a/docs/markdown/snippets/cmake_subprojects.md b/docs/markdown/snippets/cmake_subprojects.md index 94f68a1..07ff868 100644 --- a/docs/markdown/snippets/cmake_subprojects.md +++ b/docs/markdown/snippets/cmake_subprojects.md @@ -1,33 +1,29 @@ ## CMake subprojects -Meson can now directly consume CMake based subprojects. Using CMake -subprojects is almost identical to using the "normal" meson subprojects: +Meson can now directly consume CMake based subprojects with the +CMake module. -```meson -sub_proj = subproject('libsimple_cmake', method : 'cmake') -``` - -The `method` key is optional if the subproject only has a `CMakeList.txt`. -Without specifying a method meson will always first try to find and use a -`meson.build` in the subproject. - -Project specific CMake options can be added with the new `cmake_options` key. - -The returned `sub_proj` supports the same options as a "normal" subproject. -Meson automatically detects build targets, which can be retrieved with -`get_variable`. Meson also generates a dependency object for each target. +Using CMake subprojects is similar to using the "normal" meson +subprojects. They also have to be located in the `subprojects` +directory. -These variable names are generated based on the CMake target name. +Example: ```cmake -add_library(cm_exe SHARED ${SOURCES}) +add_library(cm_lib SHARED ${SOURCES}) ``` -For `cm_exe`, meson will then define the following variables: +```meson +cmake = import('cmake') + +# Configure the CMake project +sub_proj = cmake.subproject('libsimple_cmake') -- `cm_exe` The raw library target (similar to `cm_exe = library('cm_exe', ...)` in meson) -- `cm_exe_dep` The dependency object for the target (similar to `declare_dependency()` in meson) -- `cm_exe_inc` A meson include directory object, containing all include irectories of the target. +# Fetch the dependency object +cm_lib = sub_proj.dependency('cm_lib') + +executable(exe1, ['sources'], dependencies: [cm_lib]) +``` It should be noted that not all projects are guaranteed to work. The safest approach would still be to create a `meson.build` for the |