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表禁止相应编译器