DUB软件包根文件夹应包含有构建/部署元信息
的dub.sdl(或dub.json)
文件.忽略未知设置.
简单示例:
//dub.sdl可包含注释,请尽量简洁!
name "我的"
description "示例"
authors "呀"
homepage "http://myproject.example.com"
license "mit"
dependency "vibe-d" version="~>0.7.23"
构建设置
,也可在此用.
名字 | 参数 | 描述 |
---|---|---|
name[必填] |
“ |
包名,_- +英文字母 |
description[发布时必填] |
“ |
简要介绍 |
toolchainRequirements |
DUB,编译器和语言前端要求 | |
homepage |
“ |
主页 |
authors |
“ |
作者列表 |
copyright |
“ |
版权 |
license[发布时必填] |
“ |
许可 |
subPackage |
" |
子包,用路径/原位 ,见子包 |
configuration |
“ |
指定构建配置,用--config=... ,见配置. |
buildType |
“ |
定义构建类型 可覆盖/指定,用--build=... |
x:ddoxFilterArgs |
“ |
实验 ,对--build=ddox的控制过滤行为 可用的命令行标识列表 |
除了主包,还可设置子包,主包:子包
即可.典型的,将一个库分成几个子包.如主目录下dub.sdl
为:
name "mylib"
targetType "none"
dependency "mylib:component1" version="*"
dependency "mylib:component2" version="*"
subPackage "./component1/"
subPackage "./component2/"
//不用直接分成不同仓库
在组件1
里的dub.sdl
里面是:
name "component1"
targetType "library"
组件1
与组件2
可像普通包
一样,外部项目可像"mylib:component1"和"mylib:component2"
引用.用*
版本标识库指向同一库的子库.
name "mylib"
targetType "none"
dependency "mylib:component1" version="*"
//见上行
subPackage {
name "component1"
targetType "library"
sourcePaths "component1/source"
importPaths "component1/source"
}
dub.sdl
中这样声明子包.不建议在根目录
下定义子包
,会导致隐藏依赖
而在sdl
文件中未声明.
目前支持:公共领域
,AFL-3.0
(学术自由许可3.0),AGPL-3.0
(Affero GNU 公共许可 3.0),Apache-2.0
,APSL-2.0
(苹果公共源许可),Artistic-2.0
,BSL-1.0
(Boost 软件许可),BSD 2-clause
,BSD 3-clause
,EPL-1.0
(Eclipse 公共许可),GPL-2.0
,GPL-3.0
,ISC
,LGPL-2.1
,LGPL-3.0
,MIT
,MPL-2.0
(Mozilla 公共许可 2.0),MS-PL
(微软公共许可),MS-RL
(微软相互许可),NCSA
(Illinois大学/NCSA开源许可),OpenSSL
(OpenSSL许可),SLeay
(SSLeay许可),Zlib
(zlib/libpng许可),其余不支持.如:
//这是人家的示例
"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"
影响传给编译器/链接器
的命令行选项,都是可选
的.
名 | 参数 | 描述 |
---|---|---|
dependency |
“ |
添加单个依赖项,属性用来配置要用的版本/路径 ,用多个 本项来表示多个依赖 ,不支持平台 |
systemDependencies |
“ |
系统依赖,如C库,注册表上可见,链接错误时显示,不支持平台 |
targetType |
“ |
目标类型.不支持平台 |
targetName |
“ |
输出名,自动添加前后缀,不支持平台 |
targetPath |
“ |
二进制目标路径,不支持平台 |
workingDirectory |
“ |
固定工作目录,从中运行生成二进制,不支持平台 |
subConfiguration |
“ |
锁定依赖项(第一个)到特定配置(第二个),不支持平台 |
buildRequirements |
“ |
构建要求配置列表 |
buildOptions |
“ |
编译器相关构建选项标识符列表 |
libs |
“ |
外部库名,根据编译器转换成适当的链接标志,如(ssl->-L-lssl ). |
sourceFiles |
“ |
给编译器的其他源文件,一般源目录外添加依赖配置的额外源文件 |
sourcePaths |
“ |
自定义源路径,无则source/src ,通常还要定义importPaths ,因为sourcePaths 不影响他们. |
excludedSourceFiles |
“ |
排除文件,比"sourceFiles"和"sourcePaths" 优先.可用通配符 . |
mainSourceFile |
“ |
含main() 文件,用于dub test 用来区分要测试文件.不支持平台 |
copyFiles |
“ |
复制通配符模式 文件到targetPath ,递归复制. |
versions |
“ |
D版本列表 |
debugVersions |
“ |
D调试标识符列表 |
importPaths |
“ |
D模块导入路径,默认为source/ |
stringImportPaths |
“ |
串导入路径,默认为view/ , |
preGenerateCommands |
“ |
生成命令前命令列表 |
postGenerateCommands |
“ |
生成命令后命令列表 |
preBuildCommands |
“ |
构建命令前命令列表 |
postBuildCommands |
“ |
构建命令后命令列表 |
preRunCommands |
“ |
运行命令前命令列表 |
postRunCommands |
“ |
运行命令后命令列表 |
dflags |
“ |
传递给D编译器 的额外标志,与编译器相关,但一些能自动从dmd 转换成目标编译器标志. |
lflags |
“ |
传递给链接器 的标志,注意与特定链接器相关. |
用platform
属性指定.包含-
号连接的操作系统/体系结构/编译器标识符列表
.预定义的在此且均为小写
,顺序为操系-架构-编译器
,且都可省略
.示例:
//所有平台
versions "PrintfDebugging"
//仅dmd编译
dflags "-vtls" platform="dmd"
//仅"X86-64"
versions "UseAmd64Impl" platform="x86_64"
//仅"Posix systems"(Linux, OS X, FreeBSD等.)
libs "ssl" "crypto" platform="posix"
//"Windows, X86-64且用DMD编译"
sourceFiles "lib/win32/mylib.lib" platform="windows-x86_64-dmd"
用version
属性.如version="
.
当不存在path
或期望与旧版本(<0.9.22
)兼容时,这样限定
path="包路径"
,从文件夹找包.引用特定路径中包
,当要用特定包
时这样用.如git子模块
或主包的子目录
(如示例工程
).
optional=true
,表示可选依赖.为真
时,在dub.selections.json
中显式选择时才用该依赖
,省略时,默认为假
.以前<0.9.25版本意思不一样
,表示仅在
本地机器可用时,选择可选依赖
.
default=true
,默认选择可选依赖.未设置时,该属性默认为假
,如为真
,无dub.selections.json
时选择依赖
.仅在上行的可选为真
时有用.<0.9.25
将忽略本项.
版本限定意思:
次版本:"~>2.2.13"等价于">=2.2.13 <2.3.0"
主版本:"~>2.2"等价于">=2.2.0 <3.0.0"
特定版本:"==1.3.0"
最小版本:">=1.3.0"
版本区间:">=1.3.0 <=1.3.4"
任意版本:">=0.0.0"," * "
git分支(过时):"~master"
建议用~>
在灵活升级/减少破坏
间取得平衡,相同仓库下的子包
用*(任意)
.
值 | 描述 |
---|---|
"autodetect" |
默认全局值,尝试生成exe|库 配置,配置块中不允许 该值,用其他值会限定为生成的配置中的一个 . |
"none" |
不生成输出文件,在用依赖 引入其他包时有用. |
"executable" |
exe 可执行 |
"library" |
库,不限制库类型 |
"sourceLibrary" |
不生成exe ,但强制按依赖项目 把所有源文件加至编译器调用中 |
"staticLibrary" |
静态库 |
"dynamicLibrary" |
动态库 |
以下值按数组
对待
值 | 描述 |
---|---|
"allowWarnings" |
警告不中止编译 |
"silenceWarnings" |
不显示警告 |
"disallowDeprecations" |
过时时中断编译 |
"silenceDeprecations" |
不显示过时 |
"disallowInlining" |
禁止内联,释放 版本也禁止. |
"disallowOptimization" |
禁止优化,释放 版本也禁止. |
"requireBoundsCheck" |
总是检查边界 |
"requireContracts" |
释放 版本也保留断言/合约 |
"relaxProperties" |
过时 ,不强制严格属性处理 |
"noDefaultFlags" |
不产生构建类型 相关标志(如-debug,-cov,-unittest ),禁止用于释放 版本,完全作为开发/调试 工具,可试试-build=plain . |
编译器无关的方式来指定常见编译器选项/标志
.许多由构建要求
管理,其余仅在构建类型
块上出现.
值 | 描述 | dmd标志 |
---|---|---|
"debugMode" |
(启用合约)按调试编译 | -debug |
"releaseMode" |
(禁止断言/检查边界)释放编译 | -release |
"coverage" |
启用代码覆盖率分析 | -cov |
"debugInfo" |
启用符号调试信息 | -g |
"debugInfoC" |
按C兼容格式启用符号调试信息 | -gc |
"alwaysStackFrame" |
始终生成堆栈帧 | -gs |
"stackStomping" |
踩栈 | -gx |
"inline" |
内联函数 | -inline |
"noBoundsCheck" |
禁用检查边界 | -boundscheck=off |
"optimize" |
优化 | -O |
"profile" |
概要分析 | -profile |
"profileGC" |
垃集概要分析 | -profile=gc |
"unittests" |
编译单元测试 | -unittest |
"verbose" |
详细输出 | -v |
"ignoreUnknownPragmas" |
编译时忽略未知指示 | -ignore |
"syntaxOnly" |
不生成目标文件 | -o- |
"warnings" |
启用警告,默认启用(用构建要求 来控制) |
-wi |
"warningsAsErrors" |
警告当作错误,(用…控制) | -w |
"ignoreDeprecations" |
不警告过时,(…) | -d |
"deprecationWarnings" |
警告过时,(…) | -dw |
"deprecationErrors" |
过时当作错误,(…) | -de |
"property" |
强制属性语法,已过时 |
-property |
"betterC" |
按betterC 模式编译 |
-betterC |
$变量
,用$$
表$
.
变量 | 内容 |
---|---|
$PACKAGE_DIR |
包目录 |
$ROOT_PACKAGE_DIR |
构建依赖树的根包路径 |
$ |
特定程序包依赖图路径,$ 大写,且无版本 串 |
$DUB |
DUB路径 |
$ARCH |
CPU架构 : “x86”, “x86_64” |
$PLATFORM |
运行平台 : “linux”, “windows”, … |
$PLATFORM_POSIX |
运行平台 : “posix”, “windows”, … |
$BUILD_TYPE |
构建类型 : “debug”, “release”, … |
自定义指令,预定义变量
变量 | 内容 |
---|---|
$DUB_PACKAGE |
包名 |
$DUB_PACKAGE_VERSION |
包版本 |
$DUB_ROOT_PACKAGE |
根包名 |
$DUB_ROOT_PACKAGE_TARGET_TYPE |
根包的"targetType" |
$DUB_ROOT_PACKAGE_TARGET_PATH |
根包"targetPath" |
$DUB_ROOT_PACKAGE_TARGET_NAME |
根包"targetName" |
$DFLAGS |
"dflags" 内容 |
$LFLAGS |
"lflags" 内容 |
$VERSIONS |
"versions" 内容 |
$LIBS |
"libs" 内容 |
$IMPORT_PATHS |
"importPaths" 内容 |
$STRING_IMPORT_PATHS |
"stringImportPaths" 内容 |
$DC |
编译器名(如"../dmd"或"ldc2" ) |
$DC_BASE |
编译器基名(如"dmd"或"ldc" ) |
$D_FRONTEND_VER |
前端版本,2.072.2 为"2072" |
$DUB_EXE |
DUB路径 |
$DUB_PLATFORM |
目标平台(如"windows"或"linux" ) |
$DUB_ARCH |
目标架构名(如"x86"或"x86_64" ) |
$DUB_TARGET_TYPE |
"targetType" 内容 |
$DUB_TARGET_PATH |
"targetPath" 内容 |
$DUB_TARGET_NAME |
"targetName" 内容 |
$DUB_WORKING_DIRECTORY |
工作目录 |
$DUB_MAIN_SOURCE_FILE |
"mainSourceFile" 内容 |
$DUB_CONFIG |
已选构建配置(如"application"或"library" ) |
$DUB_BUILD_TYPE |
已选构建类型(如"debug"或"unittest" ) |
$DUB_BUILD_MODE |
已选构建模式(如"separate"或"singleFile" ) |
$DUB_COMBINED |
用了--combined 则为真,否则为空 |
$DUB_RUN |
调用了"run" 命令,则为真,否则为空 |
$DUB_FORCE |
调用了--force ,则为真,否则为空 |
$DUB_RDMD |
调用了--rdmd ,则为真,否则为空 |
$DUB_TEMP_BUILD |
调用了--temp-build ,则为真,否则为空 |
$DUB_PARALLEL_BUILD |
调用了--parallel ,则为真,否则为空 |
$DUB_RUN_ARGS |
包含按匹配壳格式传递给生成exe 的参数 |
除了平台相关,还可定义构建配置,用来加/覆盖
全局构建设置.用dub --config=
选一个.默认自动选目标类型/平台
匹配的第一个配置.通过加配置(configuration)
指令来定义.
如未指定配置,则dub
选择默认的"application"和"library"
配置.仅当找到以下中的一个时,才加应用
配置:
source/app.d,source/main.d,source/<包名>/app.d,source/<包名>/main.d,src/app.d,src/main.d,src/<包名>/app.d,src/<包名>/main.d
,这些地方应仅包含程序入口点(main)
,并仅加至应用
配置.
unittest
有点特殊,其表明,如存在这个配置,则在dub test
时使用它.可以通过unittest
构建类型假定有这个配置.自定义
单元测试配置覆盖默认的排除主源文件
,或增加包含
不需要在应用/库
模式下编译的额外外部测试的模块
,(自定义嘛,灵活性大).
当定义配置平台时,可随意组合构建设置
里面的项.如示例:
...
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" {
//任意平台
targetType "executable"
versions "GlutApp"
}
可用subConfiguration
对特定依赖选特定配置
...
dependency "somepackage" version=">=1.0.0"
subConfiguration "somepackage" "glut-app"
未指定,则用匹配当前平台
的第一个.
名 | 参数 | 描述 |
---|---|---|
platforms |
应用平台相关,见上平台限定 . |
dub build --build=
指定,以下是预定义
.
名 | 构建选项 |
---|---|
plain |
普通 |
debug |
"debugMode" "debugInfo" |
release |
"releaseMode" "optimize" "inline" |
release-debug |
"releaseMode" "optimize" "inline" "debugInfo" |
release-nobounds |
"releaseMode" "optimize" "inline" "noBoundsCheck" |
unittest |
"unittests" "debugMode" "debugInfo" |
docs |
"syntaxOnly" ,+ dflags "-c" "-Dddocs" |
ddox |
"syntaxOnly" ,+ dflags "-c" "-Df__dummy.html" "-Xfdocs.json" |
profile |
"profile" "optimize" "inline" "debugInfo" |
profile-gc |
"profileGC" , "debugInfo" |
cov |
"coverage" "debugInfo" |
unittest-cov |
"unittests" "coverage" "debugMode" "debugInfo" |
syntax |
"syntaxOnly" |
可自定义已有构建类型,并用全局buildType
指令加新构建类型
.低级构建设置
里面除了"dependencies", "targetType", "targetName", "targetPath", "workingDirectory", "subConfigurations"
,都可用.在此指定的构建设置稍后由包/配置
相关设置来修改/增强
.
覆盖debug
并定义新debug-profile
类型的构建类型示例如下:
name "my-package"
buildType "debug" {
buildOptions "debugMode" "debugInfo" "optimize"
}
buildType "debug-profile" {
buildOptions "debugMode" "debugInfo" "profile"
}
包可以指定工具链要求的版本
,均由版本依赖符
指定.
包中对编译器用no
而不是要求的版本
来禁止使用特定编译器
,如dmd="no"
.
标识符 | 描述 |
---|---|
"dub" |
DUB版本 |
"frontend" |
D前端版本 |
"dmd" |
DMD版本 |
"ldc" |
LDC版本 |
"gdc" |
GDC版本 |
示例:
toolchainRequirements dub=">=1.14.0" frontend=">=2.068 <2.087"
//前端在这个区间,
toolchainRequirements dmd="no" gdc="no" ldc=">=1.11.0"
//no表禁止相应编译器