d的dub构建配置

冀弘厚

2023-12-01

影响传递给编译器与链接器的壳选项.所有设置都是可选的.可用$环境变量,自身用$$表示.不匹配预定义的,就用环境变量.

依赖

//=== "dub.sdl"
...
dependency "vibe-d" version="~>0.9.5"

dependency "localdep" path="../localdep" optional=true default=true
dependency "remote" repository="git+https://example.org/remote.git" version="a1b2c3d4"
dependency "modified" version="~>1.2.3" {
    dflags "--special-flag" "-O4"
}
//=== "dub.json"
...
"dependencies": {
    "vibe-d": "~>0.9.5",

    "localdep": {
        "path": "../localdep",
        "optional": true,
        "default": true
    },
    "remote": {
        "repository": "git+https://example.org/remote.git",
        "version": "a1b2c3d4"
    },
    "modified": {
        "version": "~>1.2.3",
        "dflags": ["--special-flag", "-O4"]
    }
}

参数:"名":...
对每个使用的依赖添加依赖(dependency)指令.
此设置不支持平台规范.
版本细节

系统依赖

systemDependencies "OpenSSL (1.1.0 或 later, 1.0.0i also supported)"

目标类型

targetType "executable"

`值`	意思
`"自动检测(autodetect)"`	自动检测`目标类型`.这是`默认值`,使`dub`生成两个`"application"`和`"library"`配置.用额外值只生成`一个`.`配置`块内`禁止`此值.
`"无(none)"`	`不编译`,也不`输出`文件.对应用`"dependency"`指令拖进`额外包或子包`的包很有用.
`"可执行(executable)"`	生成`可执行`二进制文件.(如,在`Windows`上为`exe`)
`"library"`	指定`不限制`实际类型的`按库`用包.这是`大多数库`的`默认值`.
`"源库(sourceLibrary)"`	不生成`二进制`,而是强制`dub`直接添加`所有源文件`作依赖.
`"静态库(staticLibrary)"`	强制输出为静态库.(如`lib/a`文件)
`"动态库(dynamicLibrary)"`	强制输出为`动态/共享库`.(如`.dll`或`.dylib`或`.so`.)

目标名

targetName "cloudapp"

自动添加特定类型和平台的前后缀.

targetName "cloudapp"
targetType "library"
= cloudapp.lib //Windows
= libcloudapp.a //Linux
//
targetName "cloudapp"
targetType "executable"
= cloudapp.exe //Windows
= cloudapp //Linux

目标路径

targetPath "bin"

输出二进制文件的目标路径.

工作目录

workingDirectory "bin"

生成的可执行文件的固定工作目录.

子配置

subConfiguration "avrd" "atmega1284p"
subConfiguration "vibe-d/tls" "botan"
subConfiguration ":subpackage" "FromRoot"

参数为"<依赖>" "<配置>",为特定配置,锁定依赖.

构建要求

buildRequirements "allowWarnings" "requireContracts"

参数:"要求" ....构建过程所需设置列表.
细节在此

构建选项

buildOptions "allowWarnings" "requireContracts"

同样,细节在此
 细节2

库

libs "mycommons"
libs "advapi32" "wldap32" platform="windows"
libs "ldap" "lber" platform="posix"
//sdl对比json
"libs": ["mycommons"],
"libs-windows": ["advapi32", "wldap32"],
"libs-posix": ["ldap", "lber"]

库名根据编译器转换为适当的链接器标志.如ssl=>-L-lssl.
posix,先用pkg-config --exists <lib>来检查标志.

源文件

sourceFiles "doc2.d" "latex.d" "cgi.d" "comment.d" "css/*.d"
//
"sourceFiles": ["doc2.d", "latex.d", "cgi.d", "comment.d", "css/*.d"]

支持全局匹配.
对添加普通源目录中不包含的某些配置或平台相关源文件很有用,用来给编译器传递附加文件.

源路径

sourcePaths "source"
"sourcePaths": ["source"]

自定义查找源文件的路径,未指定,则用"source"或"src"
注意,一般还需要定义"importPaths",因为"sourcePaths"不会影响它,并且这是可相互导入源文件所必需.
sourceFiles/sourcePaths非常重要.用来找要编译/导入的源文件.

排除源文件

excludedSourceFiles "source/server/*.d" "source/main.d"

sourceFiles/sourcePaths中要排除的源文件.

主源文件

mainSourceFile "source/vibe/appmain.d"

确定包含main()函数的文件.在定义了不同的main函数时(如"dub test"),dub可用此设置来排除文件.

复制文件

copyFiles "LICENSE_MYDEP.txt"
copyFiles "libs/win64/*.dll" platform="windows-x86_64"
copyFiles "libs/win32/*.dll" platform="windows-x86"

复制文件,到targetPath.默认递归复制

"copyFiles": ["path/to/dir"]
//递归复制
"copyFiles": ["path/to/dir/*"]
//仅复制一层

支持全局匹配.

额外依赖文件

extraDependencyFiles "libs/*"

重新生成dub项目的匹配文件.
不必此设置,因为已检查所有源文件,导入文件与串导入文件是否更新.但是,在重复更新静态库时,可能有用.支持全局匹配.

版本

条件编译的版本

versions "NoNetwork" "DemoMode"

示例:

void draw()
{
    version (DemoMode)
    {
        drawText("DEMO MODE");
    }
}

注意:(可选)存在的依赖项已定义Have_*版本.

调试版本

debugVersions "SQLTests"

示例:

// 避免使用sourceLibrary依赖项污染依赖项的单元测试
debug (SQLTests)
{
    unittest
    {
        assert(everythingWorks());
    }
}

导入路径

importPaths "source" "extern"

搜索D模块的额外导入路径(默认,用source/目录).
建议把所有源路径放入导入路径中,以便可相互导入源.
如对外部链接的库代码,可定义额外导入路径.如果仅使用导入路径中代码,而不链接包含实际定义的目标文件,则可能会有链接错误.
等价于dmd中的-I.

串导入路径

importPaths "views"

搜索串导入的额外导入路径,默认为views/.
import("filename.ext")语句用他们.相当于-J路径.
示例:

//example.d
//加载要嵌入到`可执行`文件中的文件
static immutable string[] mirrors = import("mirrors.txt").split("\n");

//嵌入二进制文件到可执行文件中
//(如,加载`GTK`资源,加载嵌入DLL等)
static immutable ubyte[] resources = cast(immutable(ubyte)[])import("resources.gresource");

//views/mirrors.txt
https://example.org
https://example.com

//views/resources.gresource
<二进制内容>

预生成命令

...
// 特殊条件下重建
preGenerateCommands `if [ -f some_condition ]; then touch source/app.d; fi`

生成项目前执行的壳命令列表
在dub build,dub run和dub generate上运行.

即使不需要重新编译包,或生成makefile等文件时,也会执行此命令.
如果写入由源文件,导入路径,串导入路径或extraDependencyFiles观察的文件,则重新生成此包.
如果要在重新生成时更新源文件,可用(预生成命令)它.

后生成命令

类似.

预构建命令

preBuildCommands `$DUB --single update_git_version.d`

在dub build和dub run前跑.

后构建命令

postBuildCommands `gpg --sign my_executable`

类似.

运行前命令

preRunCommands `echo "EXECUTABLE OUTPUT:"`

dub run前运行.

运行后命令

preRunCommands `./cleanup.sh`

dub run后运行.

d标志

...
dflags `--relocation-model=rwpi` platform="ldc"

传递给D编译器的额外标志
标志通常特定于正在使用的编译器,但会自动从DMD转换一组标志到指定编译器.见构建选项.

l标志

...
lflags `-L$PACKAGE_DIR/libs/`

传递给链接器的额外标志,一般与正在使用的链接器相关.

注入源文件

injectSourceFiles `inject/*.d`

将编译源文件进依赖此包的二进制文件.
应在像Boost的宽松许可文件中用,否则有风险.

示例:

//=== "dep/dub.json"
{
    "name": "toload",
    "description": "展示从依赖项注入源文件的示例.",
    "targetType": "library",
    "buildOptions": ["betterC"],
    "sourcePaths": ["source"],
    "importPaths": ["source"],
    "injectSourceFiles": ["ahook.d"]
}
//=== "dep/ahook.d"
module ahook;

version(D_BetterC) {
    pragma(crt_constructor)
    extern(C) void someInitializer() {
        import core.stdc.stdio;
        printf("跑勾挂!\n");
    }
} else {
    shared static this() {
        import std.stdio;
        writeln("有运行时!!!!");
    }
}
//=== "dep/source/something.d"
module something;

void doSomething() {
    import core.stdc.stdio;

    version(D_BetterC) {
        printf("不在exe中");
    } else {
        printf("在exe中");
    }
}
//=== "app/dub.json"

{
    "name": "runner",
    "description": "展示从依赖项运行器注入源文件的示例",
    "targetType": "executable",
    "dependencies": {
        "dep": "~>1.0.0"
    }
}
//=== "app/source/entry.d"
void main() {
    import something;
    doSomething();
}

注入源文件将从依赖定义它们的依赖项的项目上下文中导入文件.