dub的sdl配置文件中文帮助

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[必填]	“<name>”	包名,_-+英文字母
description[发布时必填]	“<text>”	简要介绍
toolchainRequirements	<requirement1>[<requirement2> […]]	DUB,编译器和语言前端要求
homepage	“<url>”	主页
authors	“<author1>” ["<author2>" […]]	作者列表
copyright	“<text>”	版权
license[发布时必填]	“<license spec>”	许可
subPackage	"<path>"或{ … }	子包,用路径/原位,见子包
configuration	“<name>” { … }	指定构建配置,用--config=...,见配置.
buildType	“<name>” { … }	定义构建类型可覆盖/指定,用--build=...
x:ddoxFilterArgs	“<arg1>” ["<arg2>" […]]	实验,对--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	“<name>” …	添加单个依赖项,属性用来配置要用的版本/路径,用多个本项来表示多个依赖,不支持平台
systemDependencies	“<text>”	系统依赖,如C库,注册表上可见,链接错误时显示,不支持平台
targetType	“<type>”	目标类型.不支持平台
targetName	“<name>”	输出名,自动添加前后缀,不支持平台
targetPath	“<path>”	二进制目标路径,不支持平台
workingDirectory	“<path>”	固定工作目录,从中运行生成二进制,不支持平台
subConfiguration	“<dependency>” “<configuration>”	锁定依赖项(第一个)到特定配置(第二个),不支持平台
buildRequirements	“<requirement1>” ["<requirement2>" […]]	构建要求配置列表
buildOptions	“<option1>” ["<option2>" […]]	编译器相关构建选项标识符列表
libs	“<lib1>” ["<lib2>" […]]	外部库名,根据编译器转换成适当的链接标志,如(ssl->-L-lssl).
sourceFiles	“<pattern1>” ["<pattern2>" […]]	给编译器的其他源文件,一般源目录外添加依赖配置的额外源文件
sourcePaths	“<path1>” ["<path2>" […]]	自定义源路径,无则source/src,通常还要定义importPaths,因为sourcePaths不影响他们.
excludedSourceFiles	“<pattern1>” ["<pattern2>" […]]	排除文件,比"sourceFiles"和"sourcePaths"优先.可用通配符.
mainSourceFile	“<path>”	含main()文件,用于dub test用来区分要测试文件.不支持平台
copyFiles	“<pattern1>” ["<pattern2>" […]]	复制通配符模式文件到targetPath,递归复制.
versions	“<version1>” ["<version2>" […]]	D版本列表
debugVersions	“<version1>” ["<version2>" […]]	D调试标识符列表
importPaths	“<path1>” ["<path2>" […]]	D模块导入路径,默认为source/
stringImportPaths	“<path1>” ["<path2>" […]]	串导入路径,默认为view/,
preGenerateCommands	“<cmd1>” ["<cmd2>" […]]	生成命令前命令列表
postGenerateCommands	“<cmd1>” ["<cmd2>" […]]	生成命令后命令列表
preBuildCommands	“<cmd1>” ["<cmd2>" […]]	构建命令前命令列表
postBuildCommands	“<cmd1>” ["<cmd2>" […]]	构建命令后命令列表
preRunCommands	“<cmd1>” ["<cmd2>" […]]	运行命令前命令列表
postRunCommands	“<cmd1>” ["<cmd2>" […]]	运行命令后命令列表
dflags	“<flag1>” ["<flag2>" […]]	传递给D编译器的额外标志,与编译器相关,但一些能自动从dmd转换成目标编译器标志.
lflags	“<flag1>” ["<flag2>" […]]	传递给链接器的标志,注意与特定链接器相关.

平台相关

用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="<version-specifier>".
当不存在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	构建依赖树的根包路径
$<name>_PACKAGE_DIR	特定程序包依赖图路径,$<name>大写,且无版本串
$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=<name>选一个.默认自动选目标类型/平台匹配的第一个配置.通过加配置(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	<spec1> ["<spec2>" […]]	应用平台相关,见上平台限定.

构建类型

dub build --build=<name>指定,以下是预定义.

名	构建选项
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表禁止相应编译器