diff options
Diffstat (limited to 'tools/build_defs/d/README.md')
| -rw-r--r-- | tools/build_defs/d/README.md | 678 |
1 files changed, 0 insertions, 678 deletions
diff --git a/tools/build_defs/d/README.md b/tools/build_defs/d/README.md deleted file mode 100644 index a099cc1665..0000000000 --- a/tools/build_defs/d/README.md +++ /dev/null @@ -1,678 +0,0 @@ -# D rules - -## Rules - -<div class="toc"> - <h2>Rules</h2> - <ul> - <li><a href="#d_library">d_library</a></li> - <li><a href="#d_source_library">d_source_library</a></li> - <li><a href="#d_binary">d_binary</a></li> - <li><a href="#d_test">d_test</a></li> - <li><a href="#d_docs">d_docs</a></li> - </ul> -</div> - -## Setup - -To use the D rules, add the following to your `WORKSPACE` file to add the -external repositories for the D toolchain: - -```python -load("@bazel_tools//tools/build_defs/d:d.bzl", "d_repositories") - -d_repositories() -``` - -## Roadmap - -* Generate documentation using [`ddox`](https://github.com/rejectedsoftware/ddox) - for `d_docs` rule. -* Support for other options as defined in the [Dub package - format](http://code.dlang.org/package-format?lang=json) -* Support for specifying different configurations of a library, closer to - [Dub's model for configurations](http://code.dlang.org/package-format?lang=json#configurations) -* Workspace rule for retrieving dependencies from [Dub](http://code.dlang.org/) - -<a name="d_library"></a> -## d_library - -```python -d_library(name, srcs, deps, includes, linkopts, versions) -``` - -<table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th colspan="2">Attributes</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>name</code></td> - <td> - <code>Name, required</code> - <p>A unique name for this rule.</p> - <p> - This name will be used as the name of the library built by this rule. - </p> - </td> - </tr> - <tr> - <td><code>srcs</code></td> - <td> - <code>List of labels, required</code> - <p>List of D <code>.d</code> source files used to build the library.</p> - </td> - </tr> - <tr> - <td><code>deps</code></td> - <td> - <code>List of labels, optional</code> - <p>List of libraries to be linked to this library target.</p> - <p> - These can either be other <code>d_library</code> targets, - source-only <code>d_source_library</code> targets, or - <code>cc_library</code> targets if linking a native library. - </p> - </td> - </tr> - <tr> - <td><code>imports</code></td> - <td> - <code>List of strings, optional</code> - <p>List of import dirs to add to the compile line.</p> - <p> - These will be passed to the D compiler via <code>-I</code> flags. - </p> - </td> - </tr> - <tr> - <td><code>linkopts</code></td> - <td> - <code>List of strings, optional</code> - <p>List of flags that are added to the D linker command.</p> - <p> - These will be passed to the D compiler via <code>-L</code> flags. - </p> - </td> - </tr> - <tr> - <td><code>versions</code></td> - <td> - <code>List of strings, optional</code> - <p>List of versions to be defined during compilation.</p> - <p> - Versions are used for conditional compilation and are enabled in the - code using <code>version</code> condition blocks. These versions - listed here will be passed to the D compiler using - <code>-version</code> flags. - </p> - </td> - </tr> - </tbody> -</table> - -### Example - -Suppose you have the following directory structure for a D project: - -``` -[workspace]/ - WORKSPACE - foo/ - BUILD - foo.d - bar.d - baz.d -``` - -The library `foo` is built using a `d_library` target: - -`foo/BUILD`: - -```python -load("@bazel_tools//tools/build_defs/d/d", "d_library") - -d_binary( - name = "foo", - srcs = [ - "foo.d", - "bar.d", - "baz.d", - ], -) -``` - -<a name="d_source_library"></a> -## d_source_library - -```python -d_source_library(name, srcs, deps, includes, linkopts, versions) -``` - - -<table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th colspan="2">Attributes</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>name</code></td> - <td> - <code>Name, required</code> - <p>A unique name for this rule.</p> - </td> - </tr> - <tr> - <td><code>srcs</code></td> - <td> - <code>List of labels, required</code> - <p> - List of D <code>.d</code> source files that comprises this source - library target. - </p> - </td> - </tr> - <tr> - <td><code>deps</code></td> - <td> - <code>List of labels, optional</code> - <p>List of library targets depended on by this target.</p> - <p> - These can either be other <code>d_source_library</code> targets or - <code>cc_library</code> targets, such as when this source library - target implements the D interface for a native library. Any native - libraries will be linked by <code>d_library</code> targets that - depend on this target. - </p> - </td> - </tr> - <tr> - <td><code>imports</code></td> - <td> - <code>List of strings, optional</code> - <p>List of import dirs to add to the compile line.</p> - <p> - These will be passed to the D compiler via <code>-I</code> flags for - any <code>d_library</code> targets that depend on this target. - </p> - </td> - </tr> - <tr> - <td><code>linkopts</code></td> - <td> - <code>List of strings, optional</code> - <p>List of flags that are added to the D linker command.</p> - <p> - These will be passed to the D compiler via <code>-L</code> flags for - any <code>d_library</code> targets that depend on this target. - </p> - </td> - </tr> - <tr> - <td><code>versions</code></td> - <td> - <code>List of strings, optional</code> - <p>List of version flags to be defined during compilation.</p> - <p> - Versions are used for conditional compilation and are enabled in the - code using <code>version</code> condition blocks. These versions - listed here will be passed to the D compiler using - <code>-version</code> flags for any <code>d_library</code> targets - that depend on this target. - </p> - </td> - </tr> - </tbody> -</table> - -### Example - -Suppose you have the following directory structure for a project building a -C library and a [D interface](http://dlang.org/interfaceToC.html) for the C -library: - -``` -[workspace]/ - WORKSPACE - greeter/ - BUILD - native_greeter.c - native_greeter.h - native_greeter.d - hello_world - BUILD - hello_world.d -``` - -Build the C library using the `cc_library` rule and then use the -`d_source_library` to define the target for the D interface for the C -`native_greeter` library: - -`greeter/BUILD`: - -```python -load("@bazel_tools//tools/build_defs/d/d", "d_source_library") - -cc_library( - name = "native_greeter_lib", - srcs = ["native_greeter.c"], - hdrs = ["native_greeter.h"], -) - -d_source_library( - name = "native_greeter", - srcs = ["native_greeter.d"], - deps = [":native_greeter_lib"], -) -``` - -Other targets can directly depend on the `d_source_library` target to link -the C library: - -`hello_world/BUILD`: - -```python -load("@bazel_tools//tools/build_defs/d/d", "d_source_library") - -d_binary( - name = "hello_world", - srcs = ["hello_world.d"], - deps = ["//greeter:native_greeter"], -) -``` - -<a name="d_binary"></a> -## d_binary - -```python -d_binary(name, srcs, deps, includes, linkopts, versions) -``` - -<table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th colspan="2">Attributes</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>name</code></td> - <td> - <code>Name, required</code> - <p>A unique name for this rule.</p> - <p> - This name will be used as the name of the binary built by this rule. - </p> - </td> - </tr> - <tr> - <td><code>srcs</code></td> - <td> - <code>List of labels, required</code> - <p>List of D <code>.d</code> source files used to build the binary.</p> - </td> - </tr> - <tr> - <td><code>deps</code></td> - <td> - <code>List of labels, optional</code> - <p>List of libraries to be linked to this binary target.</p> - <p> - These can either be other <code>d_library</code> targets, - source-only <code>d_source_library</code> targets, or - <code>cc_library</code> targets if linking a native library. - </p> - </td> - </tr> - <tr> - <td><code>imports</code></td> - <td> - <code>List of strings, optional</code> - <p>List of import dirs to add to the compile line.</p> - <p> - These will be passed to the D compiler via <code>-I</code> flags. - </p> - </td> - </tr> - <tr> - <td><code>linkopts</code></td> - <td> - <code>List of strings, optional</code> - <p>List of flags that are added to the D linker command.</p> - <p> - These will be passed to the D compiler via <code>-L</code> flags. - </p> - </td> - </tr> - <tr> - <td><code>versions</code></td> - <td> - <code>List of strings, optional</code> - <p>List of versions to be defined during compilation.</p> - <p> - Versions are used for conditional compilation and are enabled in the - code using <code>version</code> condition blocks. These versions - listed here will be passed to the D compiler using - <code>-version</code> flags. - </p> - </td> - </tr> - </tbody> -</table> - -Suppose you have the following directory structure for a D project: - -``` -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - greeter.d - hello_world - BUILD - hello_world.d -``` - -The source file `hello_lib/greeter.d` defines a module `greeter`: - -```d -module greeter; -... -``` - -The `hello_lib` library is built using a `d_library` target: - -`hello_lib/BUILD`: - -```python -load("@bazel_tools//tools/build_defs/d/d", "d_library") - -d_library( - name = "hello_lib", - srcs = ["greeter.d"], -) -``` - -By default, import paths are from the root of the workspace. Thus, the source -for the `hello_world` binary, `hello_world.d`, would import the `greeter` -module as follows: - -```d -import hello_lib.greeter; -``` - -However, this can be changed via the `imports` attribute on the `d_library` -rule. - -The `hello_world` binary is built using a `d_binary` target: - -`hello_world/BUILD`: - -```python -load("@bazel_tools//tools/build_defs/d/d", "d_library") - -d_binary( - name = "hello_world", - srcs = ["hello_world.d"], - deps = ["//hello_lib"], -) -``` - -<a name="d_test"></a> -## d_test - -```python -d_test(name, srcs, deps, includes, linkopts, versions) -``` - -<table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th colspan="2">Attributes</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>name</code></td> - <td> - <code>Name, required</code> - <p>A unique name for this rule.</p> - <p> - This name will be used as the name of the test built by this rule. - </p> - </td> - </tr> - <tr> - <td><code>srcs</code></td> - <td> - <code>List of labels, required</code> - <p>List of D <code>.d</code> source files used to build the test.</p> - </td> - </tr> - <tr> - <td><code>deps</code></td> - <td> - <code>List of labels, optional</code> - <p>List of libraries to be linked to this test target.</p> - <p> - These can either be other <code>d_library</code> targets, - source-only <code>d_source_library</code> targets, or - <code>cc_library</code> targets if linking a native library. - </p> - </td> - </tr> - <tr> - <td><code>imports</code></td> - <td> - <code>List of strings, optional</code> - <p>List of import dirs to add to the compile line.</p> - <p> - These will be passed to the D compiler via <code>-I</code> flags. - </p> - </td> - </tr> - <tr> - <td><code>linkopts</code></td> - <td> - <code>List of strings, optional</code> - <p>List of flags that are added to the D linker command.</p> - <p> - These will be passed to the D compiler via <code>-L</code> flags. - </p> - </td> - </tr> - <tr> - <td><code>versions</code></td> - <td> - <code>List of strings, optional</code> - <p>List of versions to be defined during compilation.</p> - <p> - Versions are used for conditional compilation and are enabled in the - code using <code>version</code> condition blocks. These versions - listed here will be passed to the D compiler using - <code>-version</code> flags. - </p> - </td> - </tr> - </tbody> -</table> - -### Example - -Suppose you have the following directory structure for a D project: - -``` -[workspace]/ - WORKSPACE - hello_lib/ - BUILD - greeter.d - greeter_test.d -``` - -`hello_lib/greeter.d`: - -```d -module greeter; - -import std.stdio; -import std.string; - -class Greeter { - private string greeting; - - public: - this(in string greeting) { - this.greeting = greeting.dup; - } - - string makeGreeting(in immutable string thing) { - return format("%s %s!", this.greeting, thing); - } - - void greet(in immutable string thing) { - writeln(makeGreeting(thing)); - } -} -``` - -`hello_lib/greeter_test.d`: - -```d -import hello_lib.greeter; - -unittest { - auto greeter = new Greeter("Hello"); - assert(greeter.makeGreeting("world") == "Hello world!"); -} - -void main() {} -``` - -To build the library and unit test: - -`hello_lib/BUILD`: - -```python -load("@bazel_tools//tools/build_defs/d/d", "d_library", "d_test") - -d_library( - name = "greeter", - srcs = ["greeter.d"], -) - -d_test( - name = "greeter_test", - srcs = ["greeter_test.d"], - deps = [":greeter"], -) -``` - -The unit test can then be run using: - -```sh -bazel test //hello_lib:greeter_test -``` - -<a name="d_docs"></a> -## d_docs - -```python -d_docs(name, dep) -``` - -<table class="table table-condensed table-bordered table-params"> - <colgroup> - <col class="col-param" /> - <col class="param-description" /> - </colgroup> - <thead> - <tr> - <th colspan="2">Attributes</th> - </tr> - </thead> - <tbody> - <tr> - <td><code>name</code></td> - <td> - <code>Name, required</code> - <p>A unique name for this rule.</p> - </td> - </tr> - <tr> - <td><code>dep</code></td> - <td> - <code>Label, required</code> - <p>The label of the target to generate code documentation for.</p> - <p> - <code>d_docs</code> can generate HTML code documentation for the - source files of <code>d_library</code>, <code>d_source_library</code>, - <code>d_binary</code>, or <code>d_test</code> targets. - </p> - </td> - </tr> - </tbody> -</table> - -### Example - -Suppose you have the following directory structure for a D project: - -``` -[workspace]/ - WORKSPACE - foo/ - BUILD - foo.d - bar.d - baz.d -``` - -The `foo/` directory contains the sources for the `d_library` `foo`. To -generate HTML documentation for the `foo` library, define a `d_docs` target -that takes the `d_library` `foo` as its dependency: - -`foo/BUILD`: - -```python -load("@bazel_tools//tools/build_defs/d/d", "d_library", "d_docs") - -d_library( - name = "foo", - srcs = [ - "foo.d", - "bar.d", - "baz.d", - ], -) - -d_docs( - name = "foo_docs", - dep = ":foo", -) -``` - -Running `bazel build //foo:foo_docs` will generate a zip file containing the -HTML documentation generated from the source files. See the official D language -documentation on the [Documentation Generator](http://dlang.org/ddoc.html) for -more information on the conventions for source documentation. |