From c3c37fac38dcea1f00cb6750722b39704ef8fc10 Mon Sep 17 00:00:00 2001 From: Matthias Klumpp Date: Sun, 17 Sep 2017 21:36:23 +0200 Subject: [PATCH] docs: Document the D support --- docs/markdown/D.md | 89 +++++++++++++++++++++++++++++++ docs/markdown/Pkgconfig-module.md | 2 + docs/markdown/Reference-manual.md | 6 ++- docs/markdown/index.md | 2 +- docs/sitemap.txt | 1 + 5 files changed, 98 insertions(+), 2 deletions(-) create mode 100644 docs/markdown/D.md diff --git a/docs/markdown/D.md b/docs/markdown/D.md new file mode 100644 index 000000000..7b0d4859e --- /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 5a660fd2f..7f767f120 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 34b473d10..7c26d7c5d 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 8e35a4d90..2aba0d75e 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 af8aede5b..cb1570adf 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