diff --git a/source/dubregistry/web.d b/source/dubregistry/web.d index 3a0288f0..581ef993 100644 --- a/source/dubregistry/web.d +++ b/source/dubregistry/web.d @@ -477,21 +477,21 @@ class DubRegistryFullWebFrontend : DubRegistryWebFrontend { render!("search_results.dt", queryString, results); } - void getGettingStarted() { render!("getting_started.dt"); } - void getAbout() { redirect("/getting_started"); } - void getUsage() { redirect("/getting_started"); } - void getAdvancedUsage() { render!("advanced_usage.dt"); } + void getGettingStarted() { redirect("https://dub.pm/getting_started"); } + void getAbout() { getGettingStarted(); } + void getUsage() { getGettingStarted(); } + void getAdvancedUsage() { redirect("https://dub.pm/getting_started"); } - void getPublish() { render!("publish.dt"); } - void getDevelop() { render!("develop.dt"); } + void getPublish() { redirect("https://dub.pm/commandline"); } + void getDevelop() { redirect("https://dub.pm/commandline"); } @path("/package-format") void getPackageFormat(string lang = null) { switch (lang) { - default: redirect("package-format?lang=json"); break; - case "json": render!("package_format_json.dt"); break; - case "sdl": render!("package_format_sdl.dt"); break; + default: redirect("https://dub.pm/package-format-json"); break; + case "json": redirect("https://dub.pm/package-format-json"); break; + case "sdl": redirect("https://dub.pm/package-format-sdl"); break; } } @@ -758,9 +758,7 @@ class DubRegistryFullWebFrontend : DubRegistryWebFrontend { @path("/docs/commandline") void getCommandLineDocs() { - import dub.commandline; - auto commands = getCommands(); - render!("docs.commandline.dt", commands); + redirect("https://dub.pm/commandline"); } private void enforceUserPackage(User user, string package_name) diff --git a/views/advanced_usage.dt b/views/advanced_usage.dt deleted file mode 100644 index 0fb75e48..00000000 --- a/views/advanced_usage.dt +++ /dev/null @@ -1,51 +0,0 @@ -extends layout - -block title - - auto title = "Advanced DUB Usage"; - -block body - h2#app-arguments Pass commandline arguments to application - - p To pass command-line arguments to an application you're running, execute dub run <dub arguments> -- <application arguments>. - - h2#single-file Single-file packages - - p For small or script-like applications, DUB supports a special mode where the whole package is contained in a single .d file. The package recipe description can be embedded into code comments within the file: - - pre.code. - #!/usr/bin/env dub - /+ dub.sdl: - name "hello" - +/ - void main() { - import std.stdio : writeln; - writeln("Hello, World!"); - } - - p This application can be executed by running dub run --single hello.d. - - p In addition to the normal method of passing commandline arguments, you can use the shorthand dub hello.d <arguments to hello>. This shorthand and the optional shebang allow you to run applications via ./hello <arguments> from your shell if you set the executable bit of the file. - - p Single-file packages cannot be used to create library packages. - - h2#local-deps Using dependencies not published on the registry - - p There are various options to use packages not published on the registry: - - dl - dt dub add-path - dd Adds a local search directory. All direct subdirectories will be searched for packages. Local search directories are preferred over packages downloaded from the registry. - - dt dub add-local - dd Similar to the above, but only adds a single package directory. - - dt dub add-override - dd Overrides a certain version or version range of a package with another version, branch, or path. This can be used to change dependencies system-wide without modifying a package's description or selection files. - - dt Path-based dependencies - dd Package descriptions in the dub.json/dub.sdl can specify a path instead of a version; this can be used with Git submodules or subtrees, or with a known directory layout, to use arbitrarily defined versions of a dependency. Note that this should only be used for non-public packages. - - dt Path-based selections - dd You can specify arbitrary versions, branches, and paths in the dub.selections.json file, even if they contradict the dependency specification of the packages involved (note that DUB will output a warning in that case). - - p Execute dub <command> -h for more information on these commands. diff --git a/views/develop.dt b/views/develop.dt deleted file mode 100644 index 6645a312..00000000 --- a/views/develop.dt +++ /dev/null @@ -1,47 +0,0 @@ -extends layout - -block title - - auto title = "Develop with DUB"; - -block body - h2: a.anchor(title="Permalink to this section", id="publishing-packages", href="#publishing-packages") Publishing packages - - p To publish your own packages, just create a new package with a valid package description file (see the package format specification) and follow the instructions on the "publishing packages" page. - - - h2: a.anchor(title="Permalink to this section", id="help-with-dub", href="#help-with-dub") Help with DUB's development - - p You can help enhancing DUB by writing bug reports or by making pull requests on GitHub. - - p The main development happens on github in the following repositories: - - ul - li - a(href="https://github.com/dlang/dub") DUB command line tool - li - a(href="https://github.com/dlang/dub-registry") DUB registry website - - - h3: a.anchor(title="Permalink to this section", id="development-focus", href="#development-focus") Development focus - - p If you want to help out, the most important things right now are: - - ul - li Help getting a final call on some design decisions (see the forum) - li Improved package representation on the registry (categories, search function and different top-lists) - li Test and fix the different target types for various platforms and compilers - - p But in general, of course, any kind support is greatly appreciated! - - h2: a.anchor(title="Permalink to this section", id="package-scoring", href="#package-scoring") Package Scoring - - p Search results are sorted by relevance. Relevance is a combined metric of the package score and the full-text search score, see #[a(href="https://github.com/dlang/dub-registry/blob/01cc896df7a5fa48cf65/source/dubregistry/dbcontroller.d#L239-L258") #[code searchPackages(query)]]. At the moment the package score is a number between #[code 0.0] and #[code 5.0] based on the following metrics. - - ul - li Recent downloads (~50% weight) - li Repo stars (~25% weight) - li Repo watchers (~25% weight) - li Repo forks (~25% weight) - li Repo open issues (~-25% weight) - - p Each of those metrics is log-scaled relative to their average before they are combined and capped with a non-linear tanh. See #[a(href="https://github.com/dlang/dub-registry/blob/01cc896df7a5fa48cf65/source/dubregistry/registry.d#L576-L617") #[code computeScore()]] for more details. We appreciate any support in improving the package score. diff --git a/views/docs.commandline.dt b/views/docs.commandline.dt deleted file mode 100644 index 20c67cbd..00000000 --- a/views/docs.commandline.dt +++ /dev/null @@ -1,108 +0,0 @@ -extends layout - -block title - - auto title = "Commandline interface"; - -block body - - import dub.commandline; - - import std.string : split; - - void writeIndentedLine(string line) - - while (line.length > 0 && line[0] == ' ') - |   - - line = line[1 .. $]; - |= line - - - h2 General usage - - pre< - code dub [--version] [<command>] [<options...>] [-- [<application arguments...>]] - - p If the command is omitted, DUB will default to "run". When running an application, "--" can be used to separate DUB options from options passed to the application. - - p Setting the "http_proxy" environment variable will instruct DUB to use a proxy server when fetching packages or package meta data. - - p The following options are always accepted in addition to command specific ones: - - - CommonOptions options; - - auto common_args = new CommandArgs(null); - - options.prepare(common_args); - table - - foreach (arg; common_args.recognizedArgs) - tr - - auto names = arg.names.split("|"); - - auto sarg = names[0].length == 1 ? names[0] : null; - - auto larg = names[0].length > 1 ? names[0] : names.length > 1 ? names[1] : null; - - if (sarg.length) - td -#{sarg} - - else - td   - - - if (larg.length) - - if (arg.defaultValue.peek!bool) - td --#{larg} - - else - td --#{larg}=<value> - - else - td   - td - - foreach (ln; arg.helpText) - - writeIndentedLine(ln); - br - - h2 Command overview - - ul - - foreach (grp; commands) - li= grp.caption - ul - - foreach (cmd; grp.commands) - li - a(href="\##{cmd.name}") #{cmd.name} - | - #{cmd.description} - - - foreach (grp; commands) - h2 #{grp.caption} commands - - foreach (cmd; grp.commands) - - if (cmd.hidden) continue; - - h3(id=cmd.name)= cmd.name - - pre< - code dub #{cmd.name} #{cmd.argumentsPattern} [<options...>]#{cmd.acceptsAppArgs ? " -- " : ""} - - - if (cmd.helpText.length) - p - - foreach (ln; cmd.helpText) - - writeIndentedLine(ln); - br - - else - p= cmd.description - - - auto args = new CommandArgs(null); - - cmd.prepare(args); - - - if (args.recognizedArgs.length) - p Available options: - table - - foreach (arg; args.recognizedArgs) - tr - - auto names = arg.names.split("|"); - - auto sarg = names[0].length == 1 ? names[0] : null; - - auto larg = names[0].length > 1 ? names[0] : names.length > 1 ? names[1] : null; - - if (sarg.length) - td -#{sarg} - - else - td   - - - if (larg.length) - - if (arg.defaultValue.peek!bool) - td --#{larg} - - else - td --#{larg}=<value> - - else - td   - td - - foreach (ln; arg.helpText) - - writeIndentedLine(ln); - br diff --git a/views/getting_started.dt b/views/getting_started.dt deleted file mode 100644 index dd914471..00000000 --- a/views/getting_started.dt +++ /dev/null @@ -1,119 +0,0 @@ -extends layout - -block title - - auto title = "Getting Started With DUB"; - -block body - h2 Installing DUB - - p DUB is the D language's official package manager, providing simple and configurable cross-platform builds. DUB can also generate VisualD and Mono-D package files for easy IDE support. - - p To install DUB, search your operating system's package manager or download the pre-compiled package for your platform. The Windows installer will perform all installation steps; for other archives, you will want to ensure the DUB executable is in your path. Installation from source on other platforms is as simple as installing the dmd development files and your system's libcurl-dev, then running ./build.sh in the repository's folder. - - h2#own-projects Starting a new project - - p From your top-level source directory, run: - - pre.code $ dub init myproject - - p This begins an interactive session: - - pre.code. - Package recipe format (sdl/json) [json]: - Name [myproject]: - Description [A minimal D application.]: My first project - Author name [imadev]: My Name - License [proprietary]: Boost - Copyright string [Copyright © 2017, imadev]: - Add dependency (leave empty to skip) []: - Successfully created an empty project in '/home/imadev/src/myproject'. - Package successfully created in myproject - - p DUB has created a "myproject" directory containing a .gitignore, a dub configuration file, and a source/app.d source tree. - - p Notice that there are two configuration file formats available. JSON is a commonly-known format, and SDL (SDLang) is a clean, minimalist format. Both offer equivalent functionality (though unlike JSON, SDLang allows comments); use whichever you prefer. - - p The following configuration file is generated: - table - tr - th JSON - th SDLang - tr - td - pre.code.lang-json - |{ - | "name": "myproject", - | "authors": [ - | "My Name" - | ], - | "description": "My first project", - | "copyright": "Copyright © 2017, imadev", - | "license": "Boost" - |} - td - pre.code.lang-sdl. - name "myproject" - description "My first project" - authors "My Name" - copyright "Copyright © 2017, imadev" - license "Boost" - - p For more information and help with configuring your builds, see the documentation for JSON and SDLang. DUB is smart and will provide sane defaults, but you can override almost anything. - - p Execute dub build to build your project, dub run to build and run it, or dub test to build and run unit tests. The last line below is the output of the default application. - - pre.code. - $ dub run - Performing "debug" build using dmd for x86. - myproject ~master: building configuration "application"... - Linking... - Running ./myproject.exe - Edit source/app.d to start your project. - - p See the command line interface documentation, or run dub --help and dub <command> --help for more information. - - h2#adding-deps Adding a dependency - - p When you find a package to use from the DUB registry, add it to the dependency list in your DUB configuration file: - - table - tr - th JSON - th SDLang - tr - td - pre.code.lang-json - |{ - | "name": "myproject", - | "authors": [ - | "My Name" - | ], - | "description": "My first project", - | "copyright": "Copyright © 2017, imadev", - | "license": "Boost", - | "dependencies": { - | "dub": "~>1.3.0" - | } - |} - td - pre.code.lang-sdl. - name "myproject" - description "My first project" - authors "My Name" - copyright "Copyright © 2017, imadev" - license "Boost" - dependency "dub" version="~>1.3.0" - - p The DUB registry uses git tags to determine application versioning and DUB's dependency management is designed to work best according to SemVer rules. Please follow the rules of the SemVer specification for all packages you list on the registry. See the package documentation for more information on dependency version specification. - - p You can publish packages to the registry here. - - h2#foreign-projects Building a third-party project - - p You can easily fetch and build third-party projects published to the dub registry via the dub fetch <package name> command. - - p To get the package, run dub fetch <package name> to download the package and install it in your user build directory. dub run <package name> can then be used to build and execute the package. dub fetch --cache=local <package name> will extract the package into a subfolder of your current working directory. - - h2#advanced-usage Advanced usage - - p For more advanced feature, like single-file packages and managing local packages, please see the advanced usage guide. diff --git a/views/layout.inc.menu.dt b/views/layout.inc.menu.dt index ef48155d..59275049 100644 --- a/views/layout.inc.menu.dt +++ b/views/layout.inc.menu.dt @@ -10,7 +10,7 @@ - import std.range : empty; - import std.string : split; - import std.typecons : tuple; - - auto listitems = [tuple("Packages", [""]), tuple("Documentation", ["Getting Started;getting_started", "Advanced Usage;advanced_usage", "Command line documentation;docs/commandline", "Development;develop", "Package format (JSON);package-format?lang=json", "Package format (SDLang);package-format?lang=sdl"]), tuple("About", ["Forums;http://forum.rejectedsoftware.com/groups/rejectedsoftware.dub", "Bug tracker (website);https://github.com/dlang/dub-registry/issues", "Bug tracker (DUB);https://github.com/dlang/dub/issues", "Github repository (website);https://github.com/dlang/dub-registry", "GitHub repository (DUB);https://github.com/dlang/dub"]), tuple("Download", ["download"])]; + - auto listitems = [tuple("Packages", [""]), tuple("Documentation", ["Getting Started;https://dub.pm/getting_started", "Advanced Usage;https://dub.pm/advanced_usage", "Command line;https://dub.pm/commandline", "Development;https://dub.pm/develop", "Package format (JSON);https://dub.pm/package-format-json", "Package format (SDLang);https://dub.pm/package-format-sdl"]), tuple("About", ["Forums;http://forum.rejectedsoftware.com/groups/rejectedsoftware.dub", "Bug tracker (website);https://github.com/dlang/dub-registry/issues", "Bug tracker (DUB);https://github.com/dlang/dub/issues", "Github repository (website);https://github.com/dlang/dub-registry", "GitHub repository (DUB);https://github.com/dlang/dub"]), tuple("Download", ["download"])]; - if( req.session ) - listitems ~= tuple("My account", ["Manage packages;my_packages", "Edit profile;profile", "Log out;logout"]); - else diff --git a/views/package_format_json.dt b/views/package_format_json.dt deleted file mode 100644 index c3b03f7c..00000000 --- a/views/package_format_json.dt +++ /dev/null @@ -1,709 +0,0 @@ -extends layout - -block title - - auto title = "Package file format (JSON)"; - -block body - - enum iff = `iff`; - - h2 Introduction - - p - strong NOTE: this describes the JSON version of the package file format. See also the specification based on SDLang. - - p Every DUB package should contain a dub.json (or dub.sdl, formerly also package.json) file in its root folder. This file contains meta-information about the project and its dependencies. This information is used for building the project and for deploying it using the registry. The following sections give an overview of the recognized settings and their meaning. Note that any unknown settings are ignored for backwards compatibility reasons. - - p A typical example of a simple application that requires no platform specific setup: - - pre.code - |{ - | "name": "myproject", - | "description": "A little web service of mine.", - | "authors": ["Peter Parker"], - | "homepage": "http://myproject.example.com", - | "license": "GPL-2.0", - | "dependencies": { - | "vibe-d": "~>0.7.23" - | } - |} - - p Please keep the description concise (not more than 100 characters) and avoid including unspecific information such as the fact that the package is written in D. The same goes for the package name - since all DUB packages are written in D, it's usually better to avoid mentioning D explicitly, unless the package is for example a high-level wrapper around a C/C++ library. - - h2 Contents - - nav - ul - li - a(href="#standard-settings") Global settings - ul - li: a(href="#sub-packages") Sub packages - li: a(href="#licenses") License specifications - li - a(href="#build-settings") Build settings - ul - li: a(href="#version-specs") Version specifications - li: a(href="#target-types") Target types - li: a(href="#build-requirements") Build requirements - li: a(href="#build-options") Build options - li: a(href="#environment-variables") Environment variables - li - a(href="#configurations") Configurations - ul - li: a(href="#configuration-settings") Specific settings - li: a(href="#build-types") Build types - - - - a#standard-fields - h2#standard-settings Global settings - - p In addition to the settings listed here, all build settings are allowed at the global scope. - - table - tr - th Name - th Type - th Description - - tr - td name [required] - td: code string - td Name of the package, used to uniquely identify the package. Must be comprised of only lower case ASCII alpha-numeric characters, "-" or "_". - - tr - td description [required for publishing] - td: code string - td Brief description of the package - - tr - td homepage - td: code string - td URL of the project website - - tr - td authors - td: code string[] - td List of project authors (the suggested format is either "Peter Parker" or "Peter Parker <pparker@example.com>") - - tr - td copyright - td: code string - td Copyright declaration string - - tr - td license [required for publishing] - td: code string - td License(s) under which the project can be used - see the license specification section for possible values - - tr - td subPackages - td: code T[] - td Defines an array of sub-packages defined in the same directory as the root project, where each entry is either a path of a sub folder or an object of the same formatas a dub.json file - see the sub package section for more information - - tr - td configurations - td: code T[] - td Speficies an optional list of build configurations (chosen on the command line using --config=...) - see the configurations section for more details - - tr - td buildTypes - td: code T[string] - td Defines additional custom build types or overrides the default ones (chosen on the command line using --build=...) - see the build types section for an example - - tr - td -ddoxFilterArgs - td: code string[] - td Specifies a list of command line flags usable for controlling filter behavior for --build=ddox [experimental] - - - h3#sub-packages Sub packages - - p A package may contain an arbitrary number of additional publicly visible packages. These packages can be defined in the "subPackages" section of the main dub.json file. They can be referenced by concatenating their name with the name of the main package using a colon as the delimiter (i.e. "main-package-name:sub-package-name"). - - p The typical use for this feature is to split up a library into a number of parts without breaking it up into different code repositories: - - pre.code - |{ - | "name": "mylib", - | "targetType": "none", - | "dependencies": { - | "mylib:component1": "*", - | "mylib:component2": "*" - | }, - | "subPackages": [ - | "./component1/", - | "./component2/" - | ] - |} - p /dub.json - - pre.code - |{ - | "name": "component1", - | "targetType": "library" - |} - p /component1/dub.json - - p The sub directories /component1 and /component2 then contain normal packages and can be referred to as "mylib:component1" and "mylib:component2" from outside projects. To refer to sub packages within the same repository use the "*" version specifier. - - p It is also possible to define the sub packages within the root package file, but note that it is generally discouraged to put the source code of multiple sub packages into the same source folder. Doing so can lead to hidden dependencies to sub packages that haven't been explicitly stated in the "dependencies" section. These hidden dependencies can then result in build errors in conjunction with certain build modes or dependency trees that may be hard to understand. - - pre.code - |{ - | "name": "mylib", - | "targetType": "none", - | "dependencies": { - | "mylib:component1": "*", - | "mylib:component2": "*" - | }, - | "subPackages": [ - | { - | "name": "component1", - | "targetType": "library", - | "sourcePaths": ["component1/source"], - | "importPaths": ["component1/source"] - | } - | ] - |} - p /dub.json - - - h3#licenses License specifications - - p The license setting should only contain one of the standard license identifiers if possible. At a later point in time, DUB may use this information to validate proper licensing in dependency hierarchies and output warnings when licenses don't match up. Multiple licenses can be separated using the term "or" and for versioned licenses, the postfix "or later" is allowed to also include any later version of the same license. - - p The standard license identifiers are: - |public domain, - |AFL-3.0 (Academic Free License 3.0), - |AGPL-3.0 (Affero GNU Public License 3.0), - |Apache-2.0, - |APSL-2.0 (Apple Public Source License), - |Artistic-2.0, - |BSL-1.0 (Boost Software License), - |BSD 2-clause, - |BSD 3-clause, - |EPL-1.0 (Eclipse Public License), - |GPL-2.0, - |GPL-3.0, - |ISC, - |LGPL-2.1, - |LGPL-3.0, - |MIT, - |MPL-2.0 (Mozilla Public License 2.0), - |MS-PL (Microsoft Public License), - |MS-RL (Microsoft Reciprocal License), - |NCSA (University of Illinois/NCSA Open Source License), - |OpenSSL (OpenSSL License), - |SSLeay (SSLeay License), - |Zlib (zlib/libpng License) - - p Any other value is considered to be a proprietary license, which is assumed to be incompatible with any other license. If you think there is a license that should be included in this list, please file a quick bug report. Please also note that pure D bindings of C/C++ libraries should specify the same license as the original library, although a stricter but compatible license can be used, too. - - p Some example license specifications: - pre.code - |"GPL-3.0" - |"GPL-2.0 or later" - |"GPL-2.0 or later or proprietary" - |"GPL-2.0 or LGPL-3.0" - |"LGPL-2.1 or proprietary" - - h2#build-settings Build settings - - p Build settings influence the command line options passed to the compiler and linker. All settings are optional. - - p Platform specific settings are supported through the use of field name suffixes. Suffixes are dash separated list of operating system/architecture/compiler identifiers, as defined in the D language reference, but converted to lower case. The order of these suffixes is os-architecture-compiler, where any of these parts can be left off. Examples: - - pre.code - |{ - | "versions": ["PrintfDebugging"], - | "dflags-dmd": ["-vtls"], - | "versions-x86_64": ["UseAmd64Impl"] - | "libs-posix": ["ssl", "crypto"], - | "sourceFiles-windows-x86_64-dmd": ["lib/win32/mylib.lib"], - |} - - table - tr - th Name - th Type - th Description - - tr - td dependencies - td: code T[string] - td List of project dependencies given as pairs of "<name>" : <version-spec> - see next section for how version specifications look like - this setting does not support platform suffixes - - tr - td systemDependencies - td: code string - td A textual description of the required system dependencies (external C libraries) required by the package. This will be visible on the registry and will be displayed in case of linker errors - this setting does not support platform suffixes - - tr - td targetType - td: code string - td Specifies a specific target type - this setting does not support platform suffixes - - tr - td targetName - td: code string - td Sets the base name of the output file; type and platform specific pre- and suffixes are added automatically - this setting does not support platform suffixes - - tr - td targetPath - td: code string - td The destination path of the output binary - this setting does not support platform suffixes - - tr - td workingDirectory - td: code string - td A fixed working directory from which the generated executable will be run - this setting does not support platform suffixes - - tr - td subConfigurations - td: code string[string] - td Locks the dependencies to specific configurations; a map from package name to configuration name, see also the configurations section - this setting does not support platform suffixes - - tr - td buildRequirements - td: code string[] - td List of required settings for the build process. See the build requirements section for details. - - tr - td buildOptions - td: code string[] - td List of build option identifiers (corresponding to compiler flags) - see the build options section for details. - - tr - td libs - td: code string[] - td A list of external library names - depending on the compiler, these will be converted to the proper linker flag (e.g. "ssl" might get translated to "-L-lssl"). On Posix platforms dub will try to find the correct linker flags by using pkg-config - - tr - td sourceFiles - td: code string[] - td Additional files passed to the compiler - can be useful to add certain configuration dependent source files that are not contained in the general source folder - - tr - td sourcePaths - td: code string[] - td Allows to customize the path where to look for source files (any folder "source" or "src" is automatically used as a source path if no sourcePaths setting is specified) - note that you usually also need to define "importPaths" as "sourcePaths" don't influence those - - tr - td excludedSourceFiles - td: code string[] - td Files that should be removed for the set of already added source files (takes precedence over "sourceFiles" and "sourcePaths") - Glob matching can be used to pattern match multiple files at once - - tr - td mainSourceFile - td: code string - td Determines the file that contains the main() function. This setting can be used by dub to exclude this file in situations where a different main function is defined (e.g. for "dub test") - this setting does not support platform suffixes - - tr - td copyFiles - td: code string[] - td A list of globs matching files or directories to be copied to targetPath. Matching directories are copied recursively, i.e. "copyFiles": ["path/to/dir"]" recursively copies dir, while "copyFiles": ["path/to/dir/*"]" only copies files within dir. - - tr - td versions - td: code string[] - td A list of D versions to be defined during compilation - - tr - td debugVersions - td: code string[] - td A list of D debug identifiers to be defined during compilation - - tr - td importPaths - td: code string[] - td Additional import paths to search for D modules (the source/ folder is used by default as a source folder, if it exists) - - tr - td stringImportPaths - td: code string[] - td Additional import paths to search for string imports/views (the views/ folder is used by default as a string import folder, if it exists) - tr - td preGenerateCommands - td: code string[] - td A list of shell commands that is executed before project generation is started - tr - td postGenerateCommands - td: code string[] - td A list of shell commands that is executed after project generation is finished - tr - td preBuildCommands - td: code string[] - td A list of shell commands that is executed always before the project is built - tr - td postBuildCommands - td: code string[] - td A list of shell commands that is executed always after the project is built - - tr - td dflags - td: code string[] - td Additional flags passed to the D compiler - note that these flags are usually specific to the compiler in use, but a set of flags is automatically translated from DMD to the selected compiler - - tr - td lflags - td: code string[] - td Additional flags passed to the linker - note that these flags are usually specific to the linker in use - - h3#version-specs Version specifications - p A version specification can either be a simple declaration or a more complex variant, allowing more control. - - ul - li Simple variant: - p: code "<name>" : "<version-specifier>" - p This is the usual way to specify a dependency. - - li Complex variant: - p: code "<name>" : { "<attribute>": "<value>"[, ...] } - p The following attributes can be used to to control how a dependency is resolved: - ul - li - p "version": "<version-specifier>" - The version specification as used for the simple form - p A version specification should only be specified when no "path" attribute is present, or when compatibility with older versions of DUB (< 0.9.22) is desired. - li - p "path": "<path-to-package>" - Use a folder to source a package from. - p References a package in a specific path. This can be used in situations where a specific copy of a package needs to be used. Examples of this include packages that are included as GIT submodules, or packages in sub folders of the main package, such as example projects. - li - p "optional": true - Indicates an optional dependency. - p With this set to true, the dependency will only be used if explicitly selected in dub.selections.json. If omitted, this attribute defaults to false. - p Note that versions prior to 0.9.25 used to choose an optional dependency !{iff} it was available on the local machine. - li - p "default": true - Choose an optional dependency by default. - p With this set to true, the dependency will be chosen by default if no dub.selections.json exists yet. If omitted, this attribute defaults to false. Note that this only has an effect if the "optional" attribute is set to true. - p Note that versions prior to 0.9.25 will ignore this attribute. - - p Version specifiers define a range of acceptable versions. They can be specified in any of the following ways: - ul - li Restrict to a certain minor version: "~>2.2.13", equivalent to ">=2.2.13 <2.3.0" - li Restrict to a certain major version: "~>2.2", equivalent to ">=2.2.0 <3.0.0" - li Require a certain version: "==1.3.0" - li Require a minimum version: ">=1.3.0" - li Require a version range: ">=1.3.0 <=1.3.4" - li Match any released version (equivalent to ">=0.0.0"): "*" - li Use a GIT branch (deprecated): "~master" - - p Numbered versions are formatted and compared according to the SemVer specification. The recommended way to specify versions is using the ~> operator as a way to balance between flexible upgrades and reducing the risk of code breakage. - - p Whenever you refer to (sub) packages within the same repository, use the "any version" version specifier: "*" - - - h3#target-types Target types - - p The following values are recognized for the "targetType" setting: - - table - tr - th Value - th Description - tr - td "autodetect" - td Automatically detects the target type. This is the default global value and causes dub to try and generate "application" and "library" configurations. Use of other values limits the auto-generated configurations to either of the two. This value is not allowed inside of a configuration block. - - tr - td "none" - td Does not generate an output file. This is useful for packages that are supposed to drag in other packages using the "dependencies" section. - - tr - td "executable" - td Generates an executable binary - - tr - td "library" - td Specifies that the package is to be used as a library, without limiting the actual type of library. This should be the default for most libraries. - - tr - td "sourceLibrary" - td This target type does not generate a binary, but rather forces dub to add all source files directly to the same compiler invocation as the dependent project. - - tr - td "staticLibrary" - td Forces output as a static library container. - - tr - td "dynamicLibrary" - td Forces output as a dynamic/shared library. - - h3#build-requirements Build requirements - - p The following values are recognized as array items for the "buildRequirements" setting: - - table - tr - th Value - th Description - tr - td "allowWarnings" - td Warnings do not abort compilation - tr - td "silenceWarnings" - td Don't show warnings - tr - td "disallowDeprecations" - td Using deprecated features aborts compilation - tr - td "silenceDeprecations" - td Don't show deprecation warnings - tr - td "disallowInlining" - td Avoid function inlining, even in release builds - tr - td "disallowOptimization" - td Avoid optimizations, even in release builds - tr - td "requireBoundsCheck" - td Always perform bounds checks - tr - td "requireContracts" - td Leave assertions and contracts enabled in release builds - tr - td "relaxProperties" - td Do not enforce strict property handling (removes the -property switch) [deprecated, recent versions of DUB never issue -property] - tr - td "noDefaultFlags" - td Does not emit build type specific flags (e.g. -debug, -cov or -unittest). Note that this flag should never be used for released packages and is indended purely as a development/debugging tool. Using "-build=plain" may also be a more appropriate alternative. - - h3#build-options Build options - - p The "buildOptions" setting provides a compiler agnostic way to specify common compiler options/flags. Note that many of these options are implicitly managed by the "buildRequirements" setting and most others usually only occur in "buildTypes" blocks. It supports the following values: - - table - tr - th Value - th Description - th Corresponding DMD flag - tr - td "debugMode" - td Compile in debug mode (enables contracts) - td -debug - tr - td "releaseMode" - td Compile in release mode (disables assertions and bounds checks) - td -release - tr - td "coverage" - td Enable code coverage analysis - td -cov - tr - td "debugInfo" - td Enable symbolic debug information - td -g - tr - td "debugInfoC" - td Enable symbolic debug information in C compatible form - td -gc - tr - td "alwaysStackFrame" - td Always generate a stack frame - td -gs - tr - td "stackStomping" - td Perform stack stomping - td -gx - tr - td "inline" - td Perform function inlining - td -inline - tr - td "noBoundsCheck" - td Disable all bounds checking - td -boundscheck=off - tr - td "optimize" - td Enable optimizations - td -O - tr - td "profile" - td Emit profiling code - td -profile - tr - td "profileGC" - td Emit GC profiling information - td -profile=gc - tr - td "unittests" - td Compile unit tests - td -unittest - tr - td "verbose" - td Verbose compiler output - td -v - tr - td "ignoreUnknownPragmas" - td Ignores unknown pragmas during compilation - td -ignore - tr - td "syntaxOnly" - td Don't generate object files - td -o- - tr - td "warnings" - td Enable warnings, enabled by default (use "buildRequirements" to control this setting) - td -wi - tr - td "warningsAsErrors" - td Treat warnings as errors (use "buildRequirements" to control this setting) - td -w - tr - td "ignoreDeprecations" - td Do not warn about using deprecated features (use "buildRequirements" to control this setting) - td -d - tr - td "deprecationWarnings" - td Warn about using deprecated features, enabled by default (use "buildRequirements" to control this setting) - td -dw - tr - td "deprecationErrors" - td Stop compilation upon usage of deprecated features (use "buildRequirements" to control this setting) - td -de - tr - td "property" - td Enforce property syntax - deprecated - td -property - - h3#environment-variables Environment variables - include inc.package_format.envvars - - - h2#configurations Configurations - - p In addition to platform specific build settings, it is possible to define build configurations. Build configurations add or override build settings to the global ones. To choose a configuration, use dub --config=<name>. By default, the first configuration that matches the target type and build platform is selected automatically. The configurations are defined by adding a "configurations" section. - - p If no configurations are specified, dub automatically tries to detect the two default configurations "application" and "library". The "application" configuration is only added if at least one of the following files is found: source/app.d, source/main.d, source/<package name>/app.d, source/<package name>/main.d, src/app.d, src/main.d, src/<package name>/app.d, src/<package name>/main.d. Those files are expected to contain only the application entry point (usually main()) and are only added to the "application" configuration. - - p The configuration name "unittest" has a special meaning - if a configuration with this name is present, it will be used by default when executing dub test. It can be assumed to have the -unittest flag present (through the "unittest" build type). Possible use cases for custom unittest configurations overriding the default behavior of excluding the main source file or adding additional modules containing additional external tests, which don't need to be compiled in the application/library mode. - - p When defining a configuration's platform, any of the suffixes described in build settings may be combined to make the configuration as specific as necessary. - - p The following example defines "metro-app" and "desktop-app" configurations that are only available on Windows and a "glut-app" configuration that is available on all platforms. - - pre.code - |{ - | ... - | "name": "somepackage", - | "configurations": [ - | { - | "name": "metro-app", - | "targetType": "executable", - | "platforms": ["windows"], - | "versions": ["MetroApp"], - | "libs": ["d3d11"] - | }, - | { - | "name": "desktop-app", - | "targetType": "executable", - | "platforms": ["windows"], - | "versions": ["DesktopApp"], - | "libs": ["d3d9"] - | }, - | { - | "name": "glut-app", - | "targetType": "executable", - | "versions": ["GlutApp"] - | } - | ] - |} - - p You can choose a specific configuration for certain dependencies by using the "subConfigurations" section: - - pre.code - |{ - | ... - | "dependencies": { - | "somepackage": ">=1.0.0" - | }, - | "subConfigurations": { - | "somepackage": "glut-app" - | } - |} - - p If no configuration is specified for a package, the first one that matches the current platform is chosen (see the "platforms" setting below). - - - a#configuration-fields - h3#configuration-settings Configuration block specific settings - - p In addition to the usual build settings, the following settings are recognized inside of a configuration block: - - table - tr - th Name - th Type - th Description - - tr - td name [required] - td: code string - td Name of the configuration - tr - td platforms - td: code string[] - td A list of platform suffixes (as used for the build settings) to limit on which platforms the configuration applies - - h2#build-types Build types - - p By default, a set of predefined build types is already provided by DUB and can be specified using dub build --build=<name>: - - table - tr - th Name - th Build options - tr - td plain - td [] - tr - td debug - td ["debugMode", "debugInfo"] - tr - td release - td ["releaseMode", "optimize", "inline"] - tr - td release-debug - td ["releaseMode", "optimize", "inline", "debugInfo"] - tr - td release-nobounds - td ["releaseMode", "optimize", "inline", "noBoundsCheck"] - tr - td unittest - td ["unittests", "debugMode", "debugInfo"] - tr - td docs - td ["syntaxOnly"], plus "dflags": ["-c", "-Dddocs"] - tr - td ddox - td ["syntaxOnly"], plus "dflags": ["-c", "-Df__dummy.html", "-Xfdocs.json"] - tr - td profile - td ["profile", "optimize", "inline", "debugInfo"] - tr - td profile-gc - td ["profileGC", "debugInfo"] - tr - td cov - td ["coverage", "debugInfo"] - tr - td unittest-cov - td ["unittests", "coverage", "debugMode", "debugInfo"] - tr - td syntax - td ["syntaxOnly"] - - p The existing build types can be customized and new build types can be added using the global "buildTypes" section. Each entry in "buildTypes" can use any of the low level build settingss (excluding "dependencies", "targetType", "targetName", "targetPath", "workingDirectory", "subConfigurations"). The build settings specified here will later be modified/augmented by the package/configuration specific settings. - - p An example that overrides the "debug" build type and defines a new "debug-profile" type: - - pre.code - |{ - | "name": "my-package", - | "buildTypes": { - | "debug": { - | "buildOptions": ["debugMode", "debugInfo", "optimize"] - | }, - | "debug-profile": { - | "buildOptions": ["debugMode", "debugInfo", "profile"] - | } - | } - |} diff --git a/views/package_format_sdl.dt b/views/package_format_sdl.dt deleted file mode 100644 index 5cba740e..00000000 --- a/views/package_format_sdl.dt +++ /dev/null @@ -1,675 +0,0 @@ -extends layout - -block title - - auto title = "Package file format (SDLang)"; - -block body - - enum iff = `iff`; - - h2 Introduction - - p - strong NOTE: this describes the SDLang version of the package file format. See also the specification based on JSON. - - p Every DUB package should contain a dub.sdl (or dub.json) file in its root folder. This file contains meta-information about the project and its dependencies. This information is used for building the project and for deploying it using the registry. The following sections give an overview of the recognized settings and their meaning. Note that any unknown settings are ignored for backwards compatibility reasons. - - p The package format described here is based on SDLang, a simple declarative language with a lean syntax and an XML-like structure with tags, attributes, and values. In contrast to the JSON based format, all the directives described in the following section can be used multiple times and will override or append values, depending on their meaning. - - p A typical example of a simple application that requires no platform specific setup: - - pre.code - |// dub.sdl can contain comments! - |name "myproject" - |description "A little web service of mine." - |authors "Peter Parker" - |homepage "http://myproject.example.com" - |license "GPL-2.0" - |dependency "vibe-d" version="~>0.7.23" - - p Please keep the description concise (not more than 100 characters) and avoid including unspecific information such as the fact that the package is written in D. The same goes for the package name - since all DUB packages are written in D, it's usually better to avoid mentioning D explicitly, unless the package is for example a high-level wrapper around a C/C++ library. - - h2 Contents - - nav - ul - li - a(href="#standard-settings") Global settings - ul - li: a(href="#sub-packages") Sub packages - li: a(href="#licenses") License specifications - li - a(href="#build-settings") Build settings - ul - li: a(href="#platform-specs") Platform specifications - li: a(href="#version-specs") Version specifications - li: a(href="#target-types") Target types - li: a(href="#build-requirements") Build requirements - li: a(href="#build-options") Build options - li: a(href="#environment-variables") Environment variables - li - a(href="#configurations") Configurations - ul - li: a(href="#configuration-settings") Specific settings - li - a(href="#build-types") Build types - - - - h2#standard-settings Global settings - - p In addition to the settings listed here, all build settings are allowed at the global scope. - - table - tr - th Name - th Arguments - th Description - - tr - td name [required] - td: code "<name>" - td Name of the package, used to uniquely identify the package. Must be comprised of only lower case ASCII alpha-numeric characters, "-" or "_". - - tr - td description [required for publishing] - td: code "<text>" - td Brief description of the package - - tr - td homepage - td: code "<url>" - td URL of the project website - - tr - td authors - td: code "<author1>" ["<author2>" [...]] - td List of project authors (the suggested format is either "Peter Parker" or "Peter Parker <pparker@example.com>") - - tr - td copyright - td: code "<text>" - td Copyright declaration string - - tr - td license [required for publishing] - td: code "<license spec>" - td License(s) under which the project can be used - see the license specification section for possible values - - tr - td subPackage - td #[code "<path>"] or #[code { ... }] - td Defines a sub-package using either a path to a sub directory, or in-place - see the sub package section for more information - - tr - td configuration - td: code "<name>" { ... } - td Speficies a build configuration (chosen on the command line using --config=...) - see the configurations section for more details - - tr - td buildType - td: code "<name>" { ... } - td Defines an additional custom build type or overrides one of the default ones (chosen on the command line using --build=...) - see the build types section for an example - - tr - td x:ddoxFilterArgs - td: code "<arg1>" ["<arg2>" [...]] - td Specifies a list of command line flags usable for controlling filter behavior for --build=ddox [experimental] - - - h3#sub-packages Sub packages - - p A package may contain an arbitrary number of additional publicly visible packages. These packages can be defined using subPackage directives in the main dub.sdl file. They can be referenced by concatenating their name with the name of the main package using a colon as the delimiter (i.e. "main-package-name:sub-package-name"). - - p The typical use for this feature is to split up a library into a number of parts without breaking it up into different code repositories: - - pre.code - |name "mylib" - |targetType "none" - |dependency "mylib:component1" version="*" - |dependency "mylib:component2" version="*" - |subPackage "./component1/" - |subPackage "./component2/" - p: code /dub.sdl - - pre.code - |name "component1" - |targetType "library" - p: code /component1/dub.sdl - - p The sub directories /component1 and /component2 then contain normal packages and can be referred to as "mylib:component1" and "mylib:component2" from outside projects. To refer to sub packages within the same repository use the "*" version specifier. - - p It is also possible to define the sub packages within the root package file, but note that it is generally discouraged to put the source code of multiple sub packages into the same source folder. Doing so can lead to hidden dependencies to sub packages that haven't been explicitly stated in the "dependencies" section. These hidden dependencies can then result in build errors in conjunction with certain build modes or dependency trees that may be hard to understand. - - pre.code - |name "mylib" - |targetType "none" - |dependency "mylib:component1" version="*" - |subPackage { - | name "component1" - | targetType "library" - | sourcePaths "component1/source" - | importPaths "component1/source" - |} - p: code /dub.sdl - - - h3#licenses License specifications - - p The license setting should only contain one of the standard license identifiers if possible. At a later point in time, DUB may use this information to validate proper licensing in dependency hierarchies and output warnings when licenses don't match up. Multiple licenses can be separated using the term "or" and for versioned licenses, the postfix "or later" is allowed to also include any later version of the same license. - - p The standard license identifiers are: - |public domain, - |AFL-3.0 (Academic Free License 3.0), - |AGPL-3.0 (Affero GNU Public License 3.0), - |Apache-2.0, - |APSL-2.0 (Apple Public Source License), - |Artistic-2.0, - |BSL-1.0 (Boost Software License), - |BSD 2-clause, - |BSD 3-clause, - |EPL-1.0 (Eclipse Public License), - |GPL-2.0, - |GPL-3.0, - |ISC, - |LGPL-2.1, - |LGPL-3.0, - |MIT, - |MPL-2.0 (Mozilla Public License 2.0), - |MS-PL (Microsoft Public License), - |MS-RL (Microsoft Reciprocal License), - |NCSA (University of Illinois/NCSA Open Source License), - |OpenSSL (OpenSSL License), - |SSLeay (SSLeay License), - |Zlib (zlib/libpng License) - - p Any other value is considered to be a proprietary license, which is assumed to be incompatible with any other license. If you think there is a license that should be included in this list, please file a quick bug report. Please also note that pure D bindings of C/C++ libraries should specify the same license as the original library, although a stricter but compatible license can be used, too. - - p Some example license specifications: - pre.code - |"GPL-3.0" - |"GPL-2.0 or later" - |"GPL-2.0 or later or proprietary" - |"GPL-2.0 or LGPL-3.0" - |"LGPL-2.1 or proprietary" - - h2#build-settings Build settings - - p Build settings influence the command line options passed to the compiler and linker. All settings are optional. - - table - tr - th Name - th Arguments - th Description - - tr - td dependency - td: code "<name>" ... - td Adds a single dependency of the given name, attributes are used to configure the version/path to use - see next section for how version specifications look like. Use multiple dependency directives to add more than one dependency - this setting does not support the platform attribute - - tr - td systemDependencies - td: code "<text>" - td A textual description of the required system dependencies (external C libraries) required by the package. This will be visible on the registry and will be displayed in case of linker errors - this setting does not support the platform attribute - - tr - td targetType - td: code "<type>" - td Specifies a specific target type - this setting does not support the platform attribute - - tr - td targetName - td: code "<name>" - td Sets the base name of the output file; type and platform specific pre- and suffixes are added automatically - this setting does not support the platform attribute - - tr - td targetPath - td: code "<path>" - td The destination path of the output binary - this setting does not support the platform attribute - - tr - td workingDirectory - td: code "<path>" - td A fixed working directory from which the generated executable will be run - this setting does not support the platform attribute - - tr - td subConfiguration - td: code "<dependency>" "<configuration>" - td Locks a dependency (first argument) to a specific configuration (second argument); see also the configurations section - this setting does not support the platform attribute - - tr - td buildRequirements - td: code "<requirement1>" ["<requirement2>" [...]] - td List of required settings for the build process. See the build requirements section for details. - - tr - td buildOptions - td: code "<option1>" ["<option2>" [...]] - td List of build option identifiers (corresponding to compiler flags) - see the build options section for details. - - tr - td libs - td: code "<lib1>" ["<lib2>" [...]] - td A list of external library names - depending on the compiler, these will be converted to the proper linker flag (e.g. "ssl" might get translated to "-L-lssl"). On Posix platforms dub will try to find the correct linker flags by using pkg-config - - tr - td sourceFiles - td: code "<pattern1>" ["<pattern2>" [...]] - td Additional files passed to the compiler - can be useful to add certain configuration dependent source files that are not contained in the general source folder - - tr - td sourcePaths - td: code "<path1>" ["<path2>" [...]] - td Allows to customize the path where to look for source files (any folder "source" or "src" is automatically used as a source path if no sourcePaths setting is specified) - note that you usually also need to define "importPaths" as "sourcePaths" don't influence those - - tr - td excludedSourceFiles - td: code "<pattern1>" ["<pattern2>" [...]] - td Files that should be removed for the set of already added source files (takes precedence over "sourceFiles" and "sourcePaths") - Glob matching can be used to pattern match multiple files at once - - tr - td mainSourceFile - td: code "<path>" - td Determines the file that contains the main() function. This setting can be used by dub to exclude this file in situations where a different main function is defined (e.g. for "dub test") - this setting does not support platform suffixes - - tr - td copyFiles - td: code "<pattern1>" ["<pattern2>" [...]] - td A list of globs matching files or directories to be copied to targetPath. Matching directories are copied recursively, i.e. "copyFiles": ["path/to/dir"]" recursively copies dir, while "copyFiles": ["path/to/dir/*"]" only copies files within dir. - - tr - td versions - td: code "<version1>" ["<version2>" [...]] - td A list of D versions to be defined during compilation - - tr - td debugVersions - td: code "<version1>" ["<version2>" [...]] - td A list of D debug identifiers to be defined during compilation - - tr - td importPaths - td: code "<path1>" ["<path2>" [...]] - td Additional import paths to search for D modules (the source/ folder is used by default as a source folder, if it exists) - - tr - td stringImportPaths - td: code "<path1>" ["<path2>" [...]] - td Additional import paths to search for string imports/views (the views/ folder is used by default as a string import folder, if it exists) - tr - td preGenerateCommands - td: code "<cmd1>" ["<cmd2>" [...]] - td A list of shell commands that is executed before project generation is started - tr - td postGenerateCommands - td: code "<cmd1>" ["<cmd2>" [...]] - td A list of shell commands that is executed after project generation is finished - tr - td preBuildCommands - td: code "<cmd1>" ["<cmd2>" [...]] - td A list of shell commands that is executed always before the project is built - tr - td postBuildCommands - td: code "<cmd1>" ["<cmd2>" [...]] - td A list of shell commands that is executed always after the project is built - - tr - td dflags - td: code "<flag1>" ["<flag2>" [...]] - td Additional flags passed to the D compiler - note that these flags are usually specific to the compiler in use, but a set of flags is automatically translated from DMD to the selected compiler - - tr - td lflags - td: code "<flag1>" ["<flag2>" [...]] - td Additional flags passed to the linker - note that these flags are usually specific to the linker in use - - - h3#platform-specs Platform specifications - - p Platform specific settings are supported through the use of the "platform" attribute. Platform attributes contain dash separated list of operating system/architecture/compiler identifiers, as defined in the D language reference, but converted to lower case. The order of these suffixes is os-architecture-compiler, where any of these parts can be left off. Examples: - - pre.code - |// used on all platforms - |versions "PrintfDebugging" - |// only applies if compiled with DMD - |dflags "-vtls" platform="dmd" - |// only used when building for X86-64 - |versions "UseAmd64Impl" platform="x86_64" - |// only used on Posix systems (Linux, OS X, FreeBSD etc.) - |libs "ssl" "crypto" platform="posix" - |// applies if compiled for Windows, X86-64 using DMD - |sourceFiles "lib/win32/mylib.lib" platform="windows-x86_64-dmd" - - - h3#version-specs Version specifications - p A version specification can consist of a number of attributes, mainly the "version" attribute: - - ul - li - p version="<version-specifier>" - The version specification as used for the simple form - p A version specification should only be specified when no "path" attribute is present, or when compatibility with older versions of DUB (< 0.9.22) is desired. - li - p path="<path-to-package>" - Use a folder to source a package from. - p References a package in a specific path. This can be used in situations where a specific copy of a package needs to be used. Examples of this include packages that are included as GIT submodules, or packages in sub folders of the main package, such as example projects. - li - p optional=true - Indicates an optional dependency. - p With this set to true, the dependency will only be used if explicitly selected in dub.selections.json. If omitted, this attribute defaults to false. - p Note that versions prior to 0.9.25 used to choose an optional dependency !{iff} it was available on the local machine. - li - p default=true - Choose an optional dependency by default. - p With this set to true, the dependency will be chosen by default if no dub.selections.json exists yet. If omitted, this attribute defaults to false. Note that this only has an effect if the "optional" attribute is set to true. - p Note that versions prior to 0.9.25 will ignore this attribute. - - p Version specifiers define a range of acceptable versions. They can be specified in any of the following ways: - ul - li Restrict to a certain minor version: "~>2.2.13", equivalent to ">=2.2.13 <2.3.0" - li Restrict to a certain major version: "~>2.2", equivalent to ">=2.2.0 <3.0.0" - li Require a certain version: "==1.3.0" - li Require a minimum version: ">=1.3.0" - li Require a version range: ">=1.3.0 <=1.3.4" - li Match any released version (equivalent to ">=0.0.0"): "*" - li Use a GIT branch (deprecated): "~master" - - p Numbered versions are formatted and compared according to the SemVer specification. The recommended way to specify versions is using the ~> operator as a way to balance between flexible upgrades and reducing the risk of code breakage. - - p Whenever you refer to (sub) packages within the same repository, use the "any version" version specifier: "*" - - - h3#target-types Target types - - p The following values are recognized for the targetType setting: - - table - tr - th Value - th Description - tr - td "autodetect" - td Automatically detects the target type. This is the default global value and causes dub to try and generate "application" and "library" configurations. Use of other values limits the auto-generated configurations to either of the two. This value is not allowed inside of a configuration block. - - tr - td "none" - td Does not generate an output file. This is useful for packages that are supposed to drag in other packages using "dependency" directives. - - tr - td "executable" - td Generates an executable binary - - tr - td "library" - td Specifies that the package is to be used as a library, without limiting the actual type of library. This should be the default for most libraries. - - tr - td "sourceLibrary" - td This target type does not generate a binary, but rather forces dub to add all source files directly to the same compiler invocation as the dependent project. - - tr - td "staticLibrary" - td Forces output as a static library container. - - tr - td "dynamicLibrary" - td Forces output as a dynamic/shared library. - - h3#build-requirements Build requirements - - p The following values are recognized as array items in the "buildRequirements" setting: - - table - tr - th Value - th Description - tr - td "allowWarnings" - td Warnings do not abort compilation - tr - td "silenceWarnings" - td Don't show warnings - tr - td "disallowDeprecations" - td Using deprecated features aborts compilation - tr - td "silenceDeprecations" - td Don't show deprecation warnings - tr - td "disallowInlining" - td Avoid function inlining, even in release builds - tr - td "disallowOptimization" - td Avoid optimizations, even in release builds - tr - td "requireBoundsCheck" - td Always perform bounds checks - tr - td "requireContracts" - td Leave assertions and contracts enabled in release builds - tr - td "relaxProperties" - td Do not enforce strict property handling (removes the -property switch) [deprecated, recent versions of DUB never issue -property] - tr - td "noDefaultFlags" - td Does not emit build type specific flags (e.g. -debug, -cov or -unittest). Note that this flag should never be used for released packages and is indended purely as a development/debugging tool. Using "-build=plain" may also be a more appropriate alternative. - - h3#build-options Build options - - p The "buildOptions" setting provides a compiler agnostic way to specify common compiler options/flags. Note that many of these options are implicitly managed by the "buildRequirements" setting and most others usually only occur in buildType block. It supports the following values: - - table - tr - th Value - th Description - th Corresponding DMD flag - tr - td "debugMode" - td Compile in debug mode (enables contracts) - td -debug - tr - td "releaseMode" - td Compile in release mode (disables assertions and bounds checks) - td -release - tr - td "coverage" - td Enable code coverage analysis - td -cov - tr - td "debugInfo" - td Enable symbolic debug information - td -g - tr - td "debugInfoC" - td Enable symbolic debug information in C compatible form - td -gc - tr - td "alwaysStackFrame" - td Always generate a stack frame - td -gs - tr - td "stackStomping" - td Perform stack stomping - td -gx - tr - td "inline" - td Perform function inlining - td -inline - tr - td "noBoundsCheck" - td Disable all bounds checking - td -boundscheck=off - tr - td "optimize" - td Enable optimizations - td -O - tr - td "profile" - td Emit profiling code - td -profile - tr - td "profileGC" - td Emit GC profiling information - td -profile=gc - tr - td "unittests" - td Compile unit tests - td -unittest - tr - td "verbose" - td Verbose compiler output - td -v - tr - td "ignoreUnknownPragmas" - td Ignores unknown pragmas during compilation - td -ignore - tr - td "syntaxOnly" - td Don't generate object files - td -o- - tr - td "warnings" - td Enable warnings, enabled by default (use "buildRequirements" to control this setting) - td -wi - tr - td "warningsAsErrors" - td Treat warnings as errors (use "buildRequirements" to control this setting) - td -w - tr - td "ignoreDeprecations" - td Do not warn about using deprecated features (use "buildRequirements" to control this setting) - td -d - tr - td "deprecationWarnings" - td Warn about using deprecated features, enabled by default (use "buildRequirements" to control this setting) - td -dw - tr - td "deprecationErrors" - td Stop compilation upon usage of deprecated features (use "buildRequirements" to control this setting) - td -de - tr - td "property" - td Enforce property syntax - deprecated - td -property - - h3#environment-variables Environment variables - include inc.package_format.envvars - - - h2#configurations Configurations - - p In addition to platform specific build settings, it is possible to define build configurations. Build configurations add or override build settings to the global ones. To choose a configuration, use dub --config=<name>. By default, the first configuration that matches the target type and build platform is selected automatically. The configurations are defined by adding a "configuration" directive. - - p If no configurations are specified, dub automatically tries to detect the two default configurations "application" and "library". The "application" configuration is only added if at least one of the following files is found: source/app.d, source/main.d, source/<package name>/app.d, source/<package name>/main.d, src/app.d, src/main.d, src/<package name>/app.d, src/<package name>/main.d. Those files are expected to contain only the application entry point (usually main()) and are only added to the "application" configuration. - - p The configuration name "unittest" has a special meaning - if a configuration with this name is present, it will be used by default when executing dub test. It can be assumed to have the -unittest flag present (through the "unittest" build type). Possible use cases for custom unittest configurations overriding the default behavior of excluding the main source file or adding additional modules containing additional external tests, which don't need to be compiled in the application/library mode. - - p When defining a configuration's platform, any of the specifiers described in build settings may be combined to make the configuration as specific as necessary. - - p The following example defines "metro-app" and "desktop-app" configurations that are only available on Windows and a "glut-app" configuration that is available on all platforms. - - pre.code - |... - |name "somepackage" - | - |configuration "metro-app" { - | platforms "windows" - | targetType "executable" - | versions "MetroApp" - | libs "d3d11" - |} - | - |configuration "desktop-app" { - | platforms "windows" - | targetType "executable" - | versions "DesktopApp" - | libs "d3d9" - |} - | - |configuration "glut-app" { - | // works on any platform - | targetType "executable" - | versions "GlutApp" - |} - - p You can choose a specific configuration for certain dependencies by using the "subConfiguration" directive: - - pre.code - | ... - | dependency "somepackage" version=">=1.0.0" - | subConfiguration "somepackage" "glut-app" - - p If no configuration is specified for a package, the first one that matches the current platform is chosen (see the "platforms" setting below). - - - h3#configuration-settings Configuration block specific settings - - p In addition to the usual build settings, the following settings are recognized inside of a configuration block: - - table - tr - th Name - th Arguments - th Description - - tr - td platforms - td: code "<spec1> ["<spec2>" [...]] - td A list of platform specifiers to limit on which platforms the configuration applies - - h2#build-types Build types - - p By default, a set of predefined build types is already provided by DUB and can be specified using dub build --build=<name>: - - table - tr - th Name - th Build options - tr - td plain - td - tr - td debug - td "debugMode" "debugInfo" - tr - td release - td "releaseMode" "optimize" "inline" - tr - td release-debug - td "releaseMode" "optimize" "inline" "debugInfo" - tr - td release-nobounds - td "releaseMode" "optimize" "inline" "noBoundsCheck" - tr - td unittest - td "unittests" "debugMode" "debugInfo" - tr - td docs - td "syntaxOnly", plus dflags "-c" "-Dddocs" - tr - td ddox - td "syntaxOnly", plus dflags "-c" "-Df__dummy.html" "-Xfdocs.json" - tr - td profile - td "profile" "optimize" "inline" "debugInfo" - tr - td profile-gc - td "profileGC", "debugInfo" - tr - td cov - td "coverage" "debugInfo" - tr - td unittest-cov - td "unittests" "coverage" "debugMode" "debugInfo" - tr - td syntax - td "syntaxOnly" - - p The existing build types can be customized and new build types can be added using the global buildType directive. Any of the low level build settings (excluding "dependencies", "targetType", "targetName", "targetPath", "workingDirectory", "subConfigurations") can be used inside those. The build settings specified here will later be modified/augmented by the package/configuration specific settings. - - p An example that overrides the "debug" build type and defines a new "debug-profile" type: - - pre.code - |name "my-package" - |buildType "debug" { - | buildOptions "debugMode" "debugInfo" "optimize" - |} - |buildType "debug-profile" { - | buildOptions "debugMode" "debugInfo" "profile" - |} diff --git a/views/publish.dt b/views/publish.dt deleted file mode 100644 index 7f1a889e..00000000 --- a/views/publish.dt +++ /dev/null @@ -1,29 +0,0 @@ -extends layout - -block title - - auto title = "Publishing packages"; - -block body - - h2#project-creation Creating the project - - p To create a DUB compatible project, the easiest way is to use the dub executable. $ dub init myproject will create a new folder myproject that contains the recommended skeleton and a basic dub.json file. Running $ dub from this directory will build and run the empty project. - - p You should then adjust dub.json to fit the project. Especially the "authors", "copyright", "license" and "description" fields should be properly filled out before publishing. For details about the format of this file, see the package format page. - - - h2#register Registering with the registry - - p If you want to publish your project, simply put the contents into a repository and push it to GitHub, GitLab or Bitbucket. You can then register an account and register the package using your GitHub/GitLab/Bitbucket user name (or organization) and the project name. Anyone who adds the name of your project as a dependency to his/her package description will automatically have the contents of your git repository available to his/her project. - - - h2#versions Version tags - - p The repository will be monitored for changes and new version tags. To add a new version, just create a tag with a name of the form v1.2.3, where 1.2.3 should be changed to the actual version number. About twice per hour, the repository will be queried for new tags and any detected version will be made available on the registry. - - p Furthermore, all named branches will be available as special rolling versions of the form ~master (in case of the git "master" branch). However, those should never directly be used to refer to dependencies. Use those only in dub.selections.json or for version overrides ($ dub add-override). - - - h2#private-repositories Private repositories - - p The #[a(href="https://github.com/dlang/dub-registry") DUB registry] project can also be used as a private service. The settings file can be configured with credentials for a private repository hosting service instance, so that packages are fetched from the LAN, or from a private cloud based repository. Once a private instance is set up, all DUB clients need to be configured to make use of it by adding a #[code(class="lang-json") "registryUrls": ["http://dubregistry.example.com/"]] field with the appropriate URL(s) to #[code ~/.dub/settings.json], or #[code AppData/Roaming/dub/settings.json] on Windows.