From 90ae9f22e82aa1fac97e250eb3587c1cfe01d0f5 Mon Sep 17 00:00:00 2001 From: Renato Athaydes Date: Wed, 10 Jan 2024 21:33:21 +0100 Subject: [PATCH 1/2] Wrote DUB introduction in index page. --- docs/index.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 69 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 073352b..c70de69 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,8 @@ The [CLI](cli-reference/dub.md) can be used to - compile projects and external programs ([dub build](cli-reference/dub-build.md), [dub run](cli-reference/dub-run.md)) - test projects ([dub test](cli-reference/dub-test.md)) -To see how to obtain dub, **go to the next page by pressing the button below**. +DUB is bundled with most D compilers' distributions. However, it's also possible to install it separately. +See [Installing DUB](getting-started/install.md) for details. @@ -17,6 +18,71 @@ To see how to obtain dub, **go to the next page by pressing the button below**. -## Starting a new project +## DUB Basics -You can also skip ahead to [First steps](getting-started/first-steps.md) if you already have dub installed. +DUB is a build tool similar to other modern languages build tools like Javascript's [npm](https://www.npmjs.com/) +and Rust's [cargo](https://crates.io/). + +A file called `dub.sdl` (or `dub.json`) is used to configure a DUB project. + +> [SDL](https://sdlang.org/) is a "Simple Declarative Language" inspired by D's syntax. +> Whether to use SDL or JSON for the DUB file is a [matter of taste](https://forum.dlang.org/thread/fehzcwpabruiyhpwiywj@forum.dlang.org). + +A DUB file may look like this: + +```sdl +name "myproject" +description "A minimal D application." +authors "My Name" +copyright "Copyright © 2024, My Name" +license "Boost" + +dependency "libasync" version="~>0.9.5" + +configuration "library" { + targetPath "target/lib" +} + +configuration "unittest" { + dependency "tested" version="~>0.9.5" + dependency "dshould" version="~>1.7.1" + targetPath "target/test" +} +``` + +[DUB Configurations](dub-reference/configurations.md) are used to create different variations of a project. + +In the above example, all configurations include a dependency on `libasync` because that's declared at the top-level, +but only the `unittest` configuration includes the dependencies `tested` and `dshould`. + +When running `dub test`, all [Unit Tests](https://tour.dlang.org/tour/en/gems/unittesting) found in +[sourcePaths](dub-reference/build_settings.md#sourcepaths) are executed using the `unittest` configuration by default. + +To specify a configuration explicitly when building, use the `--config` option: + +``` +dub build --config=library +``` + +DUB also uses the concept of [build types](dub-reference/buildtypes.md) to define what to build. Many build types are +pre-defined, but the most common ones are `debug` and `release`. + +Hence, to build the release version of a library, the following command could be used: + +``` +dub build --config=library --build=release +``` + +Finally, to run the application, use `dub run`. + +Check [Building](dub-guide/building.md) for more details. + +## Next Steps + +[First Steps](getting-started/first-steps.md) completes this overview of the basic DUB workflow. + +The [DUB Guide](dub-guide/recipe.md) goes into more details about building, testing, configuring dependencies and registries, +shared libraries, publishing packages and more. + +More experienced users can use the [DUB Reference](dub-reference/recipe.md) and [CLI Reference](cli-reference/dub/) +for a comprehensive list of the available options. From f6da8df5adfcdf3db27bbaaa8172eb119023d49b Mon Sep 17 00:00:00 2001 From: Renato Athaydes Date: Thu, 11 Jan 2024 18:58:46 +0100 Subject: [PATCH 2/2] Introduction improvements from review. --- docs/index.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index c70de69..adeebc6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -23,12 +23,14 @@ See [Installing DUB](getting-started/install.md) for details. DUB is a build tool similar to other modern languages build tools like Javascript's [npm](https://www.npmjs.com/) and Rust's [cargo](https://crates.io/). -A file called `dub.sdl` (or `dub.json`) is used to configure a DUB project. +A [recipe file](dub-guide/recipe.md) called `dub.sdl` (or `dub.json`) is used to configure a DUB project. -> [SDL](https://sdlang.org/) is a "Simple Declarative Language" inspired by D's syntax. +> [SDL](https://sdlang.org/) is a "Simple Declarative Language" that uses a familiar C syntax. > Whether to use SDL or JSON for the DUB file is a [matter of taste](https://forum.dlang.org/thread/fehzcwpabruiyhpwiywj@forum.dlang.org). -A DUB file may look like this: +User/System-wide default settings can be specified in a [settings file](dub-reference/settings.md). + +A recipe file may look like this: ```sdl name "myproject" @@ -45,7 +47,7 @@ configuration "library" { configuration "unittest" { dependency "tested" version="~>0.9.5" - dependency "dshould" version="~>1.7.1" + dependency "dshould" version="~>1.7.1" targetPath "target/test" } ``` @@ -55,6 +57,13 @@ configuration "unittest" { In the above example, all configurations include a dependency on `libasync` because that's declared at the top-level, but only the `unittest` configuration includes the dependencies `tested` and `dshould`. +To build a project, run [`dub build`](cli-reference/dub-build/) (or just `dub`). + +As a project is built, DUB automatically resolves, downloads and builds its dependencies as needed. + +The resolved dependency versions are stored in a file next to the recipe file, called [dub.selections.json](dub-guide/selections.md), +which is similar to a lock file. + When running `dub test`, all [Unit Tests](https://tour.dlang.org/tour/en/gems/unittesting) found in [sourcePaths](dub-reference/build_settings.md#sourcepaths) are executed using the `unittest` configuration by default.