Merge pull request #4969 from mensinda/cmakeSubProject

CMake subprojects

4 files changed, 151 insertions, 32 deletions

diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md
index 4cc97cf..94f4708 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 project 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 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()`
+   object 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 f59d627..0aa4253 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1082,7 +1082,7 @@ res2 = foo / bar
 ```
 
 Builds a library that is either static, shared or both depending on
-the value of `default_library` 
+the value of `default_library`
 user [option](https://mesonbuild.com/Builtin-options.html).
 You should use this instead of [`shared_library`](#shared_library),
 [`static_library`](#static_library) or
@@ -2175,7 +2175,7 @@ an external dependency with the following methods:
    dep3 will add `['-Werror=foo', '-Werror=bar']` to the compiler args
    of any target it is added to, but libfoo will not be added to the
    link_args.
-   
+
    *Note*: A bug present until 0.50.1 results in the above behavior
    not working correctly.
 
diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md
index 2546441..fc845ff 100644
--- a/docs/markdown/Subprojects.md
+++ b/docs/markdown/Subprojects.md
@@ -14,17 +14,19 @@ Meson tries to solve this problem by making it extremely easy to
 provide both at the same time. The way this is done is that Meson
 allows you to take any other Meson project and make it a part of your
 build without (in the best case) any changes to its Meson setup. It
-becomes a transparent part of the project. 
+becomes a transparent part of the project.
 
-It should be noted that this only works for subprojects that are built
-with Meson. It can not be used with any other build system. The reason
-is the simple fact that there is no possible way to do this reliably
-with mixed build systems.
+It should be noted that this is only guaranteed to work for subprojects
+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
 
-Usually dependencies consist of some header files plus a library to link against. 
-To declare this internal dependency use `declare_dependency` function.  
+Usually dependencies consist of some header files plus a library to link against.
+To declare this internal dependency use `declare_dependency` function.
 
 As an example, suppose we have a simple project that provides a shared
 library. Its `meson.build` would look like this.
@@ -33,22 +35,22 @@ library. Its `meson.build` would look like this.
 project('libsimple', 'c')
 
 inc = include_directories('include')
-libsimple = shared_library('simple', 
-  'simple.c', 
-  include_directories : inc, 
+libsimple = shared_library('simple',
+  'simple.c',
+  include_directories : inc,
   install : true)
 
-libsimple_dep = declare_dependency(include_directories : inc, 
+libsimple_dep = declare_dependency(include_directories : inc,
   link_with : libsimple)
 ```
 
 ### Naming convention for dependency variables
 
-Ideally the dependency variable name should be of `<project_name>_dep` form. 
+Ideally the dependency variable name should be of `<project_name>_dep` form.
 This way one can just use it without even looking inside build definitions of that subproject.
 
-In cases where there are multiple dependencies need to be declared, the default one 
-should be named as `<project_name>_dep` (e.g. `gtest_dep`), and others can have 
+In cases where there are multiple dependencies need to be declared, the default one
+should be named as `<project_name>_dep` (e.g. `gtest_dep`), and others can have
 `<project_name>_<other>_<name>_dep` form (e.g. `gtest_main_dep` - gtest with main function).
 
 There may be exceptions to these rules where common sense should be applied.
@@ -65,16 +67,16 @@ as a subproject, use the `is_subproject` function.
 
 ## Using a subproject
 
-All subprojects must be inside `subprojects` directory.  
-The `subprojects` directory must be at the top level of your project.  
-Subproject declaration must be in your top level `meson.build`.  
+All subprojects must be inside `subprojects` directory.
+The `subprojects` directory must be at the top level of your project.
+Subproject declaration must be in your top level `meson.build`.
 
 ### A simple example
 
 Let's use `libsimple` as a subproject.
 
-At the top level of your project create `subprojects` directory. 
-Then copy `libsimple` into `subprojects` directory. 
+At the top level of your project create `subprojects` directory.
+Then copy `libsimple` into `subprojects` directory.
 
 Your project's `meson.build` should look like this.
 
@@ -84,9 +86,9 @@ project('my_project', 'cpp')
 libsimple_proj = subproject('libsimple')
 libsimple_dep = libsimple_proj.get_variable('libsimple_dep')
 
-executable('my_project', 
-  'my_project.cpp', 
-  dependencies : libsimple_dep, 
+executable('my_project',
+  'my_project.cpp',
+  dependencies : libsimple_dep,
   install : true)
 ```
 
@@ -102,7 +104,7 @@ embed any sources. Some distros have a rule forbidding embedded
 dependencies so your project must be buildable without them or
 otherwise the packager will hate you.
 
-Here's how you would use system libraries and fall back to embedding sources 
+Here's how you would use system libraries and fall back to embedding sources
 if the dependency is not available.
 
 ```meson
@@ -115,9 +117,9 @@ if not libsimple_dep.found()
   libsimple_dep = libsimple_proj.get_variable('libsimple_dep')
 endif
 
-executable('my_project', 
-  'my_project.cpp', 
-  dependencies : libsimple_dep, 
+executable('my_project',
+  'my_project.cpp',
+  dependencies : libsimple_dep,
   install : true)
 ```
 
@@ -141,14 +143,14 @@ project('my_project', 'cpp')
 
 libsimple_dep = dependency('libsimple', fallback : ['libsimple', 'libsimple_dep'])
 
-executable('my_project', 
-  'my_project.cpp', 
-  dependencies : libsimple_dep, 
+executable('my_project',
+  'my_project.cpp',
+  dependencies : libsimple_dep,
   install : true)
 ```
 
 With this setup when libsimple is provided by the system, we use it. When
-that is not the case we use the embedded version (the one from subprojects). 
+that is not the case we use the embedded version (the one from subprojects).
 
 Note that `libsimple_dep` can point to an external or an internal dependency but
 you don't have to worry about their differences. Meson will take care
diff --git a/docs/markdown/snippets/cmake_subprojects.md b/docs/markdown/snippets/cmake_subprojects.md
new file mode 100644
index 0000000..07ff868
--- /dev/null
+++ b/docs/markdown/snippets/cmake_subprojects.md
@@ -0,0 +1,30 @@
+## CMake subprojects
+
+Meson can now directly consume CMake based subprojects with the
+CMake module.
+
+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])
+```
+
+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.