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[必填] |
“ |
包名,_-+英文字母 |
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表禁止相应编译器