Help us understand the problem. What is going on with this article?

DUB Package file format (SDLang)

More than 3 years have passed since last update.

この文書について

これは、DUB - The D package registryPackage file format (SDLang)の翻訳です。

参考:Google翻訳とBing翻訳

TODO:
uniquely = 一意の、独自の?
stack stompingって何?
Glob matchingのglobって何?
意味不明なのでstringImportPathsについて調べる
termとpostfixの訳

イントロダクション

注釈:これはSDLangバージョンのパッケージファイル形式について説明しています。JSONに基づいた仕様も参照して下さい。

全てのDUBパッケージには、そのルートフォルダにdub.sdl(またはdub.json)ファイルが含まれている必要があります。このファイルには、プロジェクトとその依存関係に関するメタ情報が含まれています。この情報は、プロジェクトを構築するため、レジストリを使用してそれを展開するために使用されます。次のセクションでは、設定の認識とその意味の概要を示します。未知の設定は、後方互換性のために無視されることに注意して下さい。

ここで説明するパッケージ形式は、無駄のない構文、タグを利用したXMLのような構造、属性および値を持つ単純な宣言型言語SDLang[mirror]に基いています。JSONベースのフォーマットとは対照的に、次のセクションで説明する全てのディレクティブは複数回使用する事ができ、その意味に応じてオーバーライドしたり、値が追加されます。

プラットフォーム固有の構成を必要としない単純なアプリケーションの典型的な例:

// dub.sdl には、コメントを含めることが出来ます!
name "myproject"
description "A little web service of mine."
authors "Peter Parker"
homepage "http://myproject.example.com"
license "GPL-2.0"
dependency "vibe-d" version="~>0.7.23"

パッケージはDで書かれていることを事実とし、簡潔な説明(100文字より多くない)と不明確な情報を含めない事を保って下さい。同様にパッケージ名について - すべてのDUBパッケージはDで書かれているので、例えばC/C++ライブラリ周りの高レベルなラッパーである場合を除き、通常は、Dについて明示的に言及するのを避けたほうが良いでしょう。

グローバル設定

ここに記載されている設定に加え、全てのビルド設定は、グローバルスコープで許可されています。

名前 引数 説明
name [必須] "<name>" パッケージを識別するために使用される独自のパッケージの名前。"-"または"_"と小文字のASCII英数字のみで構成する必要があります。
description [公開に必要] "<text>" パッケージの簡単な説明
homepage "<url>" プロジェクトのウェブサイトのURL
authors "<author1>" ["<author2>" [...]] プロジェクトの作成者の一覧(推奨される形式は、"Peter Parker"または、"Peter Parker ≶pparker@example.com>")
copyright "<text>" 著作権の宣言文字列
license [公開に必要] "<license spec>" プロジェクトで使用可能なライセンス - 使用可能な値については、ライセンス仕様セクションを参照して下さい。
subPackage "<path>" or { ... } サブディレクトリのパス、または適切な場所のいずれかを使用してサブパッケージを定義します。- 詳細についてはサブパッケージセクションを参照して下さい。
configuration "<name>" { ... } ビルド構成を指定します (--config=... を使用してコマンドラインで選択) - 詳細については構成セクションを参照して下さい。
buildType "<name>" { ... } 追加のカスタムビルドタイプを定義するか、デフォルトの構成の1つを上書きします。 (--build=... を使用してコマンドラインで選択)- 実例は、ビルドタイプセクションを参照して下さい。
x:ddoxFilterArgs "<arg1>" ["<arg2>" [...]] --build=ddoxのフィルタの動作を制御するために使用可能なコマンドラインフラグのリストを指定します。[実験的]

サブパッケージ

パッケージは、追加公開されているパッケージを任意の数含むことができます。これらのパッケージは、メインのdub.sdlファイルのsub packagesディレクティブを使用して定義することが出来ます。これらは区切り文字としてコロンを使用して、メインパッケージの名前と自分の名前を連結して参照することが出来ます(すなわち、 "main-package-name:sub-package-name")。

この機能の一般的な用途は、異なるコードリポジトリに分解せず、部品の数にライブラリを分割することです:

/dub.sdl
name "mylib"
targetType "none"
dependency "mylib:component1" version="*"
dependency "mylib:component2" version="*"
subPackage "./component1/"
subPackage "./component2/"
/component1/sub.sdl
name "component1"
targetType "library"

サブディレクトリ /component1と/component2は、通常のパッケージが含まれており、外のプロジェクトから"mylib:component1"と"mylib:component2"と呼ぶことが出来ます。同じリポジトリ内のサブパッケージを参照するには"*"バージョン指定しを使用します。

また、ルートパッケージファイル内にサブパッケージを定義することも可能です。ただし、同じソースフォルダに複数のサブパッケージを置くことは一般的に推奨されない事に注意して下さい。そうすることで、明示的に"dependencies"セクションに記載されていないサブパッケージの隠れた依存関係に繋げることが出来ます。これらの隠された依存関係は、その後、特定のビルドモードまたは依存関係ツリーでビルドエラーが発生する可能性がありますが、それを理解するのは難しいかもしれません。

dub.sdl
name "mylib"
targetType "none"
dependency "mylib:component1" version="*"
subPackage {
    name "component1"
    targetType "library"
    sourcePaths "component1/source"
    importPaths "component1/source"
}

ライセンス仕様

ライセンスの設定は、可能ならば標準ライセンス識別子のいずれか1つが含まれている必要があります。後の時点で、DUBは依存関係の階層で適切なライセンスを検証し、ライセンスが一致しない場合に、警告を出力するためにこの情報を使用する可能性があります。複数のライセンスは、名辞"or"とバージョン管理ライセンスを使用して分離することができ、接尾辞 "or later" は同じライセンスのそれ以降のバージョンが含まれる事を許可します。

標準ライセンスは以下の通りです: public domain, AFL-3.0 (Academic Free License 3.0), AGPL-3.0 (Affero GNU Public License 3.0), Apache-2.0 , APSL-2.0 (Apple Public Source License), Artistic-2.0 , BSL-1.0 (Boost Software License), BSD 2-clause , BSD 3-clause , EPL-1.0 (Eclipse Public License), GPL-2.0 , GPL-3.0, ISC , LGPL-2.1 , LGPL-3.0 , MIT , MPL-2.0 (Mozilla Public License 2.0), MS-PL (Microsoft Public License), MS-RL (Microsoft Reciprocal License), OpenSSL (OpenSSL License), SSLeay (SSLeay License), Zlib (zlib/libpng License)

その他の値は、他のライセンスとの互換性が無いことが想定され、独自のライセンスであると考えられます。このリストに含まれる必要があるライセンスがある場合は、迅速なバグレポートを提出して下さい。
C/C++の純粋なDバインディングは、より厳格な互換性のあるライセンスを使用することができますが、元のライブラリと同じライセンスを指定する必要がある事に注意して下さい。

いくつかのライセンス仕様の例:

"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>" ... 指定された名前の単一の依存関係を追加し、属性はバージョン/パスを指定するために使用されます。 - バージョン仕様がどの様に見えるかについては、次のセクションを参照して下さい。複数の依存関係を追加する為に、複数のdependencyディレクティブを使用します。
systemDependencies "<text>" パッケージが必要とする、必須のシステム依存関係(外部Cライブラリ)の原文記述
targetType "<type>" 特定のターゲットタイプを指定します。 - この設定は、プラットフォーム属性をサポートしていません。
targetName "<name>" 出力ファイルのベース名を設定します。タイプ及びプラットフォーム固有の pre- および、接尾辞が自動的に追加されます - この設定は、プラットフォーム属性をサポートしていません。
targetPath "<path>" バイナリ出力先のパス - この設定は、プラットフォーム属性をサポートしていません。
workingDirectory "<path>" 出力された実行ファイルを動作させる所定の作業ディレクトリ - この設定は、プラットフォーム属性をサポートしていません。
subConfiguration "<dependency>" "<configuration>" 特定の構成(第2引数)への依存性(最初の引数)をロックします。 構成セクションを参照して下さい。 - この設定は、プラットフォーム属性をサポートしていません。
buildRequirements "<requirement1>" ["<requirement2>" [...]] ビルドプロセスに必要な設定のリスト。詳細についてはビルド要件セクションを参照して下さい。
buildOptions "<option1>" ["<option2>" [...]] ビルドオプション識別子のリスト(コンパイラフラグに対応) - 詳細についてはビルドオプションセクションを参照して下さい。
libs "<lib1>" ["<lib2>" [...]] 外部ライブラリ名のリスト - コンパイラによってこれらは(例えば、"ssl"を"-L-lssl"と訳されるかもしれません。)、適切なリンカフラグに変換されます。
sourceFiles "<pattern1>" ["<pattern2>" [...]] コンパイラに渡される追加ファイル - 一般的なソースフォルダに含まれていない特定の構成に依存するソースファイルを追加する為に役立つことがあります。
sourcePaths "<path1>" ["<path2>" [...]] ソースファイルを検索する場所のパスをカスタマイズする事ができます。(sourcePathsが指定されていない場合は、任意のフォルダ"source"または"src"が自動的にソースパスとして使用されます。) - あなたは通常、"importPaths""sourcePaths"を定義する必要がある時、それらに影響を与えないという点に注意して下さい。
excludedSourceFiles "<pattern1>" ["<pattern2>" [...]] 既に追加されているソースファイルの中から、除外する必要のあるファイル("sourceFiles"と"sourcePaths"よりも優先されます) - Glob matchingを使用して複数のファイルを一度にパターンマッチすることができます。
mainSourceFile "<path>" main()関数を含むファイルを指定します。この設定は、別のmain関数が定義されている状況で、そのファイルを除外するためにdubで使用することが出来ます。(例えば "dub test") - この設定はプラットフォームサフィックスをサポートしていません。
copyFiles "<pattern1>" ["<pattern2>" [...]] targetPathにコピーするファイルやディレクトリのgropsマッチングリスト。一致するディレクトリを再帰的にコピー、すなわち"copyFiles": ["path/to/dir"]" dirを再帰的にコピー。一方、"copyFiles": ["path/to/dir/*"]" dir内のファイルのみコピー
versions "<version1>" ["<version2>" [...]] コンパイル時に定義されるDバージョンのリスト
debugVersions "<version1>" ["<version2>" [...]] コンパイル時に定義されるDデバッグ識別子のリスト
importPaths "<path1>" ["<path2>" [...]] Dモジュールを検索する追加のインポートパス(source/フォルダが存在する場合、ソースフォルダとしてデフォルトで使用されます。)
stringImportPaths "<path1>" ["<path2>" [...]] 文字列 imports/viewsを検索する追加のインポートパス(views/フォルダが存在する場合、文字列のインポートフォルダとしてデフォルトで使用されます。)
preGenerateCommands "<cmd1>" ["<cmd2>" [...]] プロジェクトの生成を開始する前に実行されるジェルコマンドのリスト
postGenerateCommands "<cmd1>" ["<cmd2>" [...]] プロジェクトの生成が完了した後に実行されるシェルコマンドのリスト
preBuildCommands "<cmd1>" ["<cmd2>" [...]] プロジェクトをビルドする前に必ず実行されるシェルコマンドのリスト
postBuildCommands "<cmd1>" ["<cmd2>" [...]] プロジェクトがビルドされた後に必ず実行されるシェルコマンドのリスト
dflags "<flag1>" ["<flag2>" [...]] Dコンパイラに渡す追加のフラグ - これらのフラグは通常、使用しているコンパイラ固有である事に注意して下さい。しかし、セットされたフラグは自動的にDMDから選択されたコンパイラ用に変換されます。
lflags "<flag1>" ["<flag2>" [...]] リンカに渡す追加のフラグ - これらのフラグは通常、使用中のリンカ固有である事に注意して下さい。

Build setting値内では、ドル記号を使用した変数を使用することが可能です。事前に定義された名前と一致しない任意の変数は、プログラム環境から取得されます。リテラルのドル記号を表すために、 $$ を使用します。事前に定義された変数は次の通りです。

変数 内容
$PACKAGE_DIR パッケージ自体へのパス
$ROOT_PACKAGE_DIR ビルド依存関係ツリーのルートパッケージへのパス
$<name>_PACKAGE_DIR パッケージ名 <name> へのパス

プラットフォーム仕様

プラットフォーム固有の設定は、フィールド名のサフィックスを使用することによりサポートされています。
サフィックスは、ダッシュ記号で区切られたプラットフォーム識別子で、D言語リファレンスで定義されていますが、小文字に変換されます。これらのサフィックスの順序はos-architecture-compilerで、これらのパーツのいずれかをオフにしておくことが出来ます。例:

// 全てのプラットフォームで使用
versions "PrintfDebugging"
// DMDでコンパイルされた場合のみ適応される
dflags "-vtls" platform="dmd"
// X86-64用にビルドする場合のみ使用
versions "UseAmd64Impl" platform="x86_64"
// POSIXシステム(Linux, OS X, FreeBSD etc.)でのみ使用されます
libs "ssl" "crypto" platform="posix"
// DMDでWindowsのX86_64向けにコンパイルされた場合に適用
sourceFiles "lib/win32/mylib.lib" platform="windows-x86_64-dmd"

バージョン仕様

バージョン仕様では、いくつかの属性、主に”version”属性で構成されます:

  • version="<version-specifier>" - 単純なフォームのために使用されるバージョン指定 バージョン指定は"path"属性が存在しない時、または古いバージョンのDUB(< 0.9.22)との互換性が必要な場合にのみ指定して下さい。
  • path="<path-to-package>" - パッケージをソースフォルダから使用します。 特定のパスのパッケージを参照します。これは、パッケージの特定のコピーが使用される必要がある状況で使用することができます。この例は、 GITサブモジュールまたは、メインパッケージのサブフォルダ内のパッケージ、サンプルプロジェクトなどのパッケージが含まれます。
  • optional=true - オプションの依存性を示します。 これは、指定するとローカルマシン上で既に利用可能な場合の依存関係にのみ使用されます。

バージョン指定子は許容できるパージョンの範囲を定義します。これらは、次のいずれかの方法で指定することが出来ます。

  • 特定のマイナーバージョンに制限: "~>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"

番号付きのバージョンはセマンティック バージョニング仕様に従ってフォーマットされ比較されます。
バージョンを指定する推奨方法は、柔軟なアップグレードとコード破損の危険性を減らすバランスの取れた方法として、~>演算子を使用しています。

同じリポジトリ内の(サブ)パッケージを参照するたびに、"any version"指定子を使用します: "*"

ターゲットタイプ

以下の値がtargetType設定で認識されます:

説明
"autodetect" 自動的にターゲットタイプを検出します。これがデフォルトのグローバル値であり、DUBは、"application"と"library"構成の生成を試みます。その他の値の使用は、2つの自動生成された構成のいずれかを制限します。この値は構成ブロックの内部で許可されていません。
"none" 出力ファイルを生成しません。これは、 "dependencies"セクションを使用して、他のパッケージに引き込む事になっているパッケージに使用すると便利です。
"executable" 実行可能なバイナリを生成します。
"library" ライブラリの実際の型を制限すること無く、ライブラリとして使用するパッケージを指定します。これは、ほとんどのライブラリのデフォルトの設定にする必要があります。
"sourceLibrary" このターゲットタイプはバイナリを生成するのではなく、むしろ、依存プロジェクトと同じコンパイラ呼び出しに直接全てのソースファイルを追加することをDUBに強制します。
"staticLibrary" 強制的に静的ライブラリコンテナとして出力します。
"dynamicLibrary" 強制的に動的/共有ライブラリとして出力します。

ビルド要件

以下の値が"buildRequirements"設定の配列項目として認識されます:

説明
"allowWarnings" 警告でコンパイルを中断しません。
"silenceWarnings" 警告を表示しません。
"disallowDeprecations" 非推奨の機能を使用すると、コンパイルを中止します。
"silenceDeprecations" 非推奨の警告を表示しません。
"disallowInlining" リリースビルドにおいても、関数のインライン展開を避けます。
"disallowOptimization" リリースビルドにおいても、最適化を避けます。
"requireBoundsCheck" 常に境界チェックを実行します。
"requireContracts" リリースビルドで、アサーションを残し契約を有効にします。
"relaxProperties" 厳格なプロパティ処理を適用しません。(-propertyスイッチを削除します。) [非推奨 - DUBの最近のバージョンは、-propertyを発行する事はありません]
"noDefaultFlags" ビルドタイプの特定のフラグを送りません(例えば、-debug、-cov または -unittest)。このフラグをリリースパッケージに使用するべきではありません。そして、純粋に開発/デバッグツールとして意図されているという事に注意して下さい。"-build=plain"を用いて、より適切な代替としても良いでしょう。

ビルドオプション

"buildOptions" 設定は、一般的なコンパイラオプション/フラグを指定する、コンパイラに依存しない方法を提供します。これらのオプションの多くは、暗黙的に"buildRequirements"設定によって管理され、他のほとんどは通常、buildTypesブロックで存在することに注意して下さい。これは、次の値をサポートします:

説明 対応するDMDフラグ
"debugMode" デバッグモードでコンパイルします。(契約を可能にします) -debug
"releaseMode" リリースモードでコンパイルします。(アサーションと境界チェックを無効にします) -release
"coverage" コードカバレッジ解析を有効にします。 -cov
"debugInfo" シンボリックデバッグ情報を有効にします。 -g
"debugInfoC" C互換形式のシンボリックデバッグ情報を有効にします。 -gc
"alwaysStackFrame" 常にスタックフレームを生成します。 -gs
"stackStomping" スタック踏みを実行します。 -gx
"inline" 関数のインライン展開を実行します。 -inline
"noBoundsCheck" 全ての境界チェックを無効にします。 -noboundscheck
"optimize" 最適化を有効にします。 -O
"profile" プロファイリングコードを出力します。 -profile
"unittests" 単体テストをコンパイルします。 -unittest
"verbose" 冗長なコンパイラ出力 -v
"ignoreUnknownPragmas" コンパイル時に未知のpragmaを無視します。 -ignore
"syntaxOnly" オブジェクトファイルを生成しません。 -o-
"warnings" 警告を有効にします。デフォルトで有効(この設定を制御するために"buildRequirements"を使用) -wi
"warningsAsErrors" 警告をエラーとして扱います。(この設定を制御するために"buildRequirements"を使用) -w
"ignoreDeprecations" 非推奨の機能の使用に関する警告を表示しません。(この設定を制御するために"buildRequirements"を使用) -d
"deprecationWarnings" 非推奨な機能の使用について警告します。デフォルトで有効 -dw
"deprecationErrors" 非推奨の機能を使用時にコンパイルを停止します。 -de
"property" プロパテイ構文を強制します。 - 非推奨 -property

構成

プラットフォーム固有のビルド設定に加えて、ビルド構成を定義することが可能です。ビルド構成を追加またはグローバルなものにビルド設定をオーバライドします。設定を選択するには、--config=<name>を使用します。デフォルトでは、最初の構成に一致するターゲットタイプとビルドプラットフォームが自動的に選択されます。構成は、"configuration" ディレクティブを追加することによって定義されます。

もし、構成が指定されていない場合、DUBは自動的に"application"と"library"の2つのデフォルト設定を検出しようとします。次のファイルの少なくともひとつが検出された場合、"application"構成にのみ追加されます: source/app.d, source/main.d, source/<package name>/app.d, source/<package name>/main.d, src/app.d, src/main.d, src/<package name>/app.d, src/<package name>/main.d これらのファイルは、 アプリケーションのエントリポイント(通常、main())のみ含み、また "application"構成にのみ追加されるはずです。

プラットフォームの構成を定義する場合、ビルド設定に記載されている指定子のいずれかは、必要に応じて特定の構成と組み合わせても良いです。

次の例では、"metro-app" および "desktop-app"構成はWindows上でのみ使用可能で、
"glut-app"構成は全てのプラットフォームで利用可能です。

...
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" {
    // works on any platform
    "targetType": "executable"
    "versions": "GlutApp"
}

あなたは、"subConfiguration"ディレクティブを使用して、特定の依存関係のための具体的な構成を選択することが出来ます:

    ...
    dependency "somepackage" version=">=1.0.0"
    "subConfiguration" "somepackage" "glut-app"

パッケージ設定を指定芝居場合、現在のプラットフォームに一致する最初の一つが選択されます(以下の"platforms"設定を参照して下さい)。

構成ブロック固有の設定

通常のビルド設定に加えて、以下の設定は構成ブロックの内部で認識されます:

名前 引数 説明
platforms "<spec1> ["<spec2>" [...]] 設定が適応されるプラットフォームを制限する、プラットフォーム仕様のリスト

ビルドタイプ

デフォルトでは、事前に定義されたビルドタイプのセットが既にDUBによって提供されておりdub build --build=<name>を使用して指定することが出来ます:

名前 ビルドオプション
plain
debug "debugMode" "debugInfo"
release "releaseMode" "optimize" "inline"
unittest "unittests" "debugMode" "debugInfo"
docs "syntaxOnly"に加えて dflags "-c" "-Dddocs"
ddox "syntaxOnly"に加えて dflags "-c" "-Df__dummy.html" "-Xfdocs.json"
profile "profile" "optimize" "inline" "debugInfo"
cov "coverage" "debugInfo"
unittest-cov "unittests" "coverage" "debugMode" "debugInfo"

既存のビルドタイプをカスタマイズすることができます。グローバルな"buildTypes"ディレクティブを使用して、新しいビルドタイプを追加できます。"buildTypes"の各エントリは低レベルのビルド設定のいずれかを使用することが出来ます("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"
}
lunatea
大宇宙っ~☆
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away