From 0173b2457d9840ae63fff96aa30f387570e985cf Mon Sep 17 00:00:00 2001 From: FFY00 Date: Tue, 17 Jul 2018 23:46:13 +0100 Subject: [PATCH] docs: fix dlang module documentation --- docs/markdown/D.md | 55 +++++++++++++++++++++++------------ docs/markdown/Dependencies.md | 52 +++++++++++++++++++++------------ docs/markdown/Dlang-module.md | 20 +++++++------ 3 files changed, 80 insertions(+), 47 deletions(-) diff --git a/docs/markdown/D.md b/docs/markdown/D.md index 095616649..15de2f72e 100644 --- a/docs/markdown/D.md +++ b/docs/markdown/D.md @@ -5,7 +5,8 @@ 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 has support for compiling D programs. A minimal `meson.build` +file for D looks like this: ```meson project('myapp', 'd') @@ -15,8 +16,8 @@ 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: +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']) @@ -24,10 +25,14 @@ 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 +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: @@ -43,8 +48,10 @@ 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. +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 @@ -71,12 +78,17 @@ pkgc.generate(name: 'mylib', 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: +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') @@ -85,10 +97,15 @@ 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. +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. # Integrating with DUB -DUB is a fully integrated build system for D, but it is also a way to provide dependencies. Adding dependencies from the [D package registry](https://code.dlang.org/) is pretty straight forward. -You can find how to do this in [Dependencies](Dependencies.md#Dub). You can also automatically generate a `dub.json` file as explained in [Dlang](Dlang-module.md#generatedubfile). +DUB is a fully integrated build system for D, but it is also a way to +provide dependencies. Adding dependencies from the [D package registry](https://code.dlang.org/) +is pretty straight forward. You can find how to do this in +[Dependencies](Dependencies.md#Dub). You can also automatically +generate a `dub.json` file as explained in [Dlang](Dlang-module.md#generatedubfile). diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index 20e356ffd..7b4262dde 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -109,6 +109,38 @@ object. Since they can be used interchangeably, the rest of the build definitions do not need to care which one it is. Meson will take care of all the work behind the scenes to make this work. +# Dependency method + +You can use the keyword `method` to let meson know what method to use +when searching for the dependency. The default value is `auto`. +Aditional dependencies methods are `pkg-config`, `config-tool`, +`system`, `sysconfig`, `qmake`, `extraframework` and `dub`. + +```meson +cups_dep = dependency('cups', method : 'pkg-config') +``` + +### Some notes on Dub + +Please understand that meson is only able to find dependencies that +exist in the local Dub repository. You need to manually fetch and +build the target dependencies. + +For `urld`. +``` +dub fetch urld +dub build urld +``` + +Other thing you need to keep in mind is that both meson and Dub need +to be using the same compiler. This can be achieved using Dub's +`-compiler` argument and/or manually setting the `DC` environment +variable when running meson. +``` +dub build urld --compiler=dmd +DC="dmd" meson builddir +``` + # Dependencies with custom lookup functionality Some dependencies have specific detection logic. @@ -186,24 +218,6 @@ have been compiled for single-threaded use instead. `method` may be `auto`, `config-tool`, `pkg-config` or `extraframework`. -## Dub - -Use `method` to find dependencies with Dub. Just create a dependency as you would normally, but add `dub` as the dependency method. -```meson -urld_dep = dependency('urld', method: 'dub') -``` - -Please understand that meson is only able to find existing dependencies. You still need to manually fetch and build them with Dub. -``` -dub fetch urld -dub build urld -``` -Other thing you need to keep in mind is that both meson and Dub need to be using the same compiler. This can be achieved using Dub's `-compiler` argument and/or manually setting the `DC` environment variable when running meson. -``` -dub build urld --compiler=dmd -DC="dmd" meson builddir -``` - ## GL This finds the OpenGL library in a way appropriate to the platform. @@ -298,7 +312,7 @@ The `language` keyword may used. Python3 is handled specially by meson: 1. Meson tries to use `pkg-config`. -1. If `pkg-config` fails meson uses a fallback: +2. If `pkg-config` fails meson uses a fallback: - On Windows the fallback is the current `python3` interpreter. - On OSX the fallback is a framework dependency from `/Library/Frameworks`. diff --git a/docs/markdown/Dlang-module.md b/docs/markdown/Dlang-module.md index d34414347..ca9a381a5 100644 --- a/docs/markdown/Dlang-module.md +++ b/docs/markdown/Dlang-module.md @@ -7,11 +7,14 @@ This module provides tools related to the D programming language. To use this module, just do: **`dlang = import('dlang')`**. You can, of course, replace the name `dlang` with anything else. -The module only exposes one funtion, `generate_dub_file`, used to automatically generate Dub configuration files. +The module only exposes one fucntion, `generate_dub_file`, used to +automatically generate Dub configuration files. ### generate_dub_file() -This method only has two required arguments, the project name and the source folder. -You can pass other arguments with additional keywords, they will be automatically translated to json and added to the `dub.json` file. +This method only has two required arguments, the project name and the +source folder. You can pass other arguments with additional keywords, +they will be automatically translated to json and added to the +`dub.json` file. **Structure** ```meson @@ -32,10 +35,9 @@ dlang.generate_dub_file(meson.project_name().to_lower(), meson.source_root(), ) ``` -You can manually edit a meson generated `dub.json` file or provide a initial one. -The module will only update the values specified in `generate_dub_file()`. +You can manually edit a meson generated `dub.json` file or provide a +initial one. The module will only update the values specified in +`generate_dub_file()`. -Although not required, you will need to have a `description` and `license` if you want to publish the package in the [D package registry](https://code.dlang.org/). - -Other thing to keep in mind is that currently, the module ignores `configurations`, `subConfigurations`, and `buildTypes`. -You can configure that directly in `dub.json`. +Although not required, you will need to have a `description` and +`license` if you want to publish the package in the [D package registry](https://code.dlang.org/). \ No newline at end of file