4 files changed, 83 insertions, 0 deletions
diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md
new file mode 100644
index 0000000..4cc97cf
--- /dev/null
+++ b/docs/markdown/CMake-module.md
@@ -0,0 +1,71 @@
+# CMake module
+
+This module provides helper tools for generating cmake package files.
+
+
+## Usage
+
+To use this module, just do: **`cmake = import('cmake')`**. The
+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.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),
+it generates a `name` package version file.
+
+* `name`: the name of the package.
+* `version`: the version of the generated package file.
+* `compatibility`: a string indicating the kind of compatibility, the accepted values are
+`AnyNewerVersion`, `SameMajorVersion`, `SameMinorVersion` or `ExactVersion`.
+It defaults to `AnyNewerVersion`. Depending on your cmake installation some kind of
+compatibility may not be available.
+* `install_dir`: optional installation directory, it defaults to `$(libdir)/cmake/$(name)`
+
+
+Example:
+
+```meson
+cmake = import('cmake')
+
+cmake.write_basic_package_version_file(name: 'myProject', version: '1.0.0')
+```
+
+### cmake.configure_package_config_file()
+
+This function is the equivalent of the corresponding [CMake function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-configuration-file),
+it generates a `name` package configuration file from the `input` template file. Just like the cmake function
+in this file the `@PACKAGE_INIT@` statement will be replaced by the appropriate piece of cmake code.
+The equivalent `PATH_VARS` argument is given through the `configuration` parameter.
+
+* `name`: the name of the package.
+* `input`: the template file where that will be treated for variable substitutions contained in `configuration`.
+* `install_dir`: optional installation directory, it defaults to `$(libdir)/cmake/$(name)`.
+* `configuration`: a `configuration_data` object that will be used for variable substitution in the template file.
+
+
+Example:
+
+meson.build:
+
+```meson
+cmake = import('cmake')
+
+conf = configuration_data()
+conf.set_quoted('VAR', 'variable value')
+
+cmake.configure_package_config_file(
+    name: 'myProject',
+    input: 'myProject.cmake.in',
+    configuration: conf
+)
+```
+
+myProject.cmake.in:
+
+```text
+@PACKAGE_INIT@
+
+set(MYVAR VAR)
+```
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 5436ec3..e913e25 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -266,6 +266,9 @@ following.
 - `build_by_default` *(added 0.38)* causes, when set to true, to
   have this target be built by default, that is, when invoking plain
   `ninja`; the default value is false
+  *(changed in 0.50)* if `build_by_default` is explicitly set to false, `install`
+  will no longer override it. If `build_by_default` is not set, `install` will
+  still determine its default.
 - `build_always` (deprecated) if `true` this target is always considered out of
   date and is rebuilt every time.  Equivalent to setting both
   `build_always_stale` and `build_by_default` to true.
diff --git a/docs/markdown/Release-notes-for-0.50.0.md b/docs/markdown/Release-notes-for-0.50.0.md
index cb4fe0d..a08edfb 100644
--- a/docs/markdown/Release-notes-for-0.50.0.md
+++ b/docs/markdown/Release-notes-for-0.50.0.md
@@ -15,3 +15,11 @@ whose contents should look like this:
 
     A short description explaining the new feature and how it should be used.
 
+## custom_target: install no longer overrides build_by_default
+
+Earlier, if `build_by_default` was set to false and `install` was set to true in
+a `custom_target`, `install` would override it and the `custom_target` would
+always be built by default.
+Now if `build_by_default` is explicitly set to false it will no longer be
+overridden. If `build_by_default` is not set, its default will still be
+determined by the value of `install` for greater backward compatibility.
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index b8c41b4..f80c279 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -30,6 +30,7 @@ index.md
 		Subprojects.md
 		Disabler.md
 		Modules.md
+			CMake-module.md
 			Dlang-module.md
 			Gnome-module.md
 			Hotdoc-module.md