docs: Document the D support

5 files changed, 98 insertions, 2 deletions

diff --git a/docs/markdown/D.md b/docs/markdown/D.md
new file mode 100644
index 0000000..7b0d485
--- /dev/null
+++ b/docs/markdown/D.md
@@ -0,0 +1,89 @@
+---
+title: D
+short-description: Compiling D sources
+...
+
+# Compiling D applications
+
+Meson has support for compiling D programs. A minimal `meson.build` file for D looks like this:
+
+```meson
+project('myapp', 'd')
+
+executable('myapp', 'app.d')
+```
+
+## Compiling different versions
+
+If you are using the [version()](https://dlang.org/spec/version.html) feature for conditional compilation, you can use it using the `d_module_versions`
+target property:
+```meson
+project('myapp', 'd')
+executable('myapp', 'app.d', d_module_versions: ['Demo', 'FeatureA'])
+```
+
+## Using embedded unittests
+
+If you are using embedded [unittest functions](https://dlang.org/spec/unittest.html), your source code needs to be compiled twice, once in regular
+mode, and once with unittests active. This is done by setting the `d_unittest` target property to `true`.
+Meson will only ever pass the respective compiler's `-unittest` flag, and never have the compiler generate an empty main function.
+If you need that feature in a portable way, create an empty `main()` function for unittests yourself, since the GNU D compiler
+does not have this feature.
+
+This is an example for using D unittests with Meson:
+```meson
+project('myapp_tested', 'd')
+
+myapp_src = ['app.d', 'alpha.d', 'beta.d']
+executable('myapp', myapp_src)
+
+test_exe = executable('myapp_test', myapp_src, d_unittest: true)
+test('myapptest', test_exe)
+```
+
+# Compiling D libraries and installing them
+
+Building D libraries is a straightforward process, not different from how C libraries are built in Meson. You should generate a pkg-config file
+and install it, in order to make other software on the system find the dependency once it is installed.
+
+This is an example on how to build a D shared library:
+```meson
+project('mylib', 'd', version: '1.2.0')
+
+project_soversion = 0
+glib_dep = dependency('glib-2.0')
+
+my_lib = library('mylib',
+    ['src/mylib/libfunctions.d'],
+    dependencies: [glib_dep],
+    install: true,
+    version: meson.project_version(),
+    soversion: project_soversion,
+    d_module_versions: ['FeatureA', 'featureB']
+)
+pkgc.generate(name: 'mylib',
+              libraries: my_lib,
+              subdirs: 'd/mylib',
+              version: meson.project_version(),
+              description: 'A simple example D library.',
+              d_module_versions: ['FeatureA']
+)
+install_subdir('src/mylib/', install_dir: 'include/d/mylib/')
+```
+
+It is important to make the D sources install in a subdirectory in the include path, in this case `/usr/include/d/mylib/mylib`.
+All D compilers include the `/usr/include/d` directory by default, and if your library would be installed into `/usr/include/d/mylib`, there
+is a high chance that, when you compile your project again on a machine where you installed it, the compiler will prefer the old installed include over
+the new version in the source tree, leading to very confusing errors.
+
+This is an example of how to use the D library we just built and installed in an application:
+```meson
+project('myapp', 'd')
+
+mylib_dep = dependency('mylib', version: '>= 1.2.0')
+myapp_src = ['app.d', 'alpha.d', 'beta.d']
+executable('myapp', myapp_src, dependencies: [mylib_dep])
+```
+
+Please keep in mind that the library and executable would both need to be built with the exact same D compiler and D compiler version. The D ABI is not
+stable across compilers and their versions, and mixing compilers will lead to problems.
diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md
index 5a660fd..7f767f1 100644
--- a/docs/markdown/Pkgconfig-module.md
+++ b/docs/markdown/Pkgconfig-module.md
@@ -41,3 +41,5 @@ keyword arguments.
   e.g. `datadir=${prefix}/share`. The names `prefix`, `libdir` and
   `installdir` are reserved and may not be used.
 - `version` a string describing the version of this library
+- `d_module_versions` a list of module version flags used when compiling
+   D sources referred to by this pkg-config file
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 34b473d..7c26d7c 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -424,6 +424,10 @@ be passed to [shared and static libraries](#library).
 - `override_options` takes an array of strings in the same format as
   `project`'s `default_options` overriding the values of these options
   for this target only, since 0.40.0
+- `d_import_dirs` list of directories to look in for string imports used
+  in the D programmling language
+- `d_unittest`, when set to true, the D modules are compiled in debug mode
+- `d_module_versions` list of module versions set when compiling D sources
 
 The list of `sources`, `objects`, and `dependencies` is always
 flattened, which means you can freely nest and add lists while
@@ -835,7 +839,7 @@ This function prints its argument to stdout.
 The first argument to this function must be a string defining the name
 of this project. It is followed by programming languages that the
 project uses. Supported values for languages are `c`, `cpp` (for
-`C++`), `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`) and
+`C++`), `d`, `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`) and
 `vala`. In versions before `0.40.0` you must have at least one
 language listed.
 
diff --git a/docs/markdown/index.md b/docs/markdown/index.md
index 8e35a4d..2aba0d7 100644
--- a/docs/markdown/index.md
+++ b/docs/markdown/index.md
@@ -13,7 +13,7 @@ The main design point of Meson is that every moment a developer spends writing o
 ## Features
 
 *   multiplatform support for Linux, OSX, Windows, GCC, Clang, Visual Studio and others
-*   supported languages include C, C++, Fortran, Java, Rust
+*   supported languages include C, C++, D, Fortran, Java, Rust
 *   build definitions in a very readable and user friendly non-Turing complete DSL
 *   cross compilation for many operating systems as well as bare metal
 *   optimized for extremely fast full and incremental builds without sacrificing correctness
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index af8aede..cb1570a 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -38,6 +38,7 @@ index.md
 			Windows-module.md
 		Java.md
 		Vala.md
+		D.md
 		IDE-integration.md
 		Custom-build-targets.md
 		Build-system-converters.md