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

DUB Package file format (JSON)

More than 3 years have passed since last update.

この文書について

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

参考:Google翻訳とBing翻訳

イントロダクション

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

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

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

{
    "name": "myproject",
    "description": "A little web service of mine.",
    "authors": ["Peter Parker"],
    "homepage": "http://myproject.example.com",
    "license": "GPL-2.0",
    "dependencies": {
        "vibe-d": "~>0.7.23"
    }
}

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

グローバル設定

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

名前 説明
name [必須] string パッケージを識別するために使用される独自のパッケージの名前。"-"または"_"と小文字のASCII英数字のみで構成する必要があります。
description [公開に必要] string パッケージの簡単な説明
homepage string プロジェクトのウェブサイトのURL
authors string[] プロジェクトの作成者の一覧
copyright string 著作権の宣言文字列
license [公開に必要] string プロジェクトで使用可能なライセンス - 使用可能な値についてはライセンス仕様セクションを参照して下さい
subPackage T[] ルートプロジェクトと同じディレクトリに定義されたサブパッケージの配列を定義します。各エントリはサブフォルダのパス、またはdub.jsonファイルと同じ形式のオブジェクトのいずれかです。 - 詳細については、サブパッケージセクションを参照して下さい
configuration T[] ビルド構成のオプションのリストを指定します。(--config=...を使用してコマンドラインで選択) - 詳細については、構成セクションを参照して下さい
buildType T[string] 追加のカスタムビルドタイプを定義するか、デフォルトのものを上書きします。( --build=...を使用してコマンドラインで選択) - 実例はビルドタイプセクションを参照して下さい
-ddoxFilterArgs string[] --build=ddoxのフィルタの動作を制御する為に使用可能なコマンドラインフラグのリストを指定します [実験的]

サブパッケージ

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

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

dub.json
{
    "name": "mylib",
    "targetType": "none",
    "dependencies": {
        "mylib:component1": "*",
        "mylib:component2": "*"
    },
    "subPackages": [
        "./component1/",
        "./component2/"
    ]
}
/component1/dub.json
{
    "name": "component1",
    "targetType": "library"
}

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

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

/dub.json
{
    "name": "mylib",
    "targetType": "none",
    "dependencies": {
        "mylib:component1": "*",
        "mylib:component2": "*"
    },
    "subPackages": [
        {
            "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"

ビルド設定

ビルド設定は、コンパイラとリンカに渡されたコマンドラインオプションに影響を与えます。全ての設定は任意です。

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

{
    "versions": ["PrintfDebugging"],
    "dflags-dmd": ["-vtls"],
    "versions-x86_64": ["UseAmd64Impl"]
    "libs-posix": ["ssl", "crypto"],
    "sourceFiles-windows-x86_64-dmd": ["lib/win32/mylib.lib"],
}
名前 説明
dependencies T[string] "<name>" : <version-spec>の対として与えられたプロジェクトの依存関係のリスト - バージョン仕様がどのように見えるかは次のセクションを参照して下さい。
systemDependencies string パッケージが必要とする、必要なシステム依存関係(外部Cライブラリ)のテキスト記述。これはレジストリ上で見える時、リンカエラーが発生した場合に表示されます。
targetType string 特定のターゲットタイプを指定します。 - この設定はプラットフォームサフィックスをサポートしていません。
targetName string 出力ファイルのベース名を設定します。タイプおよびプラットフォーム固有のpre-およびサフィックスが自動的に追加されます。 - この設定はプラットフォームサフィックスをサポートしていません。
targetPath string 出力バイナリの宛先パス - この設定はプラットフォームサフィックスをサポートしていません。
workingDirectory string 生成された実行可能ファイルを実行する所定の作業ディレクトリ - この設定はプラットフォームサフィックスをサポートしていません。
subConfigurations string[string] 特定の構成に依存関係をロックします。パッケージ名に構成名から図解は、構成セクションも参照して下さい。 - この設定はプラットフォームサフィックスをサポートしていません。
buildRequirements string[] ビルドプロセスのために必要な設定のリスト。 - 詳細については、ビルド要件セクションを参照して下さい。
buildOptions string[] (コンパイラフラグに対応する)ビルドオプションの識別子のリスト。 - 詳細については、ビルドオプションセクションを参照して下さい。
libs string[] 外部ライブラリのリスト - コンパイラに応じてこれらは適切なリンカフラグに変換されます(例えば、"ssl"は"-L-lssl"に変換される可能性があります)。
sourceFiles string[] コンパイラに渡される追加ファイル - 一般のソースフォルダに含まれていない特定の構成に依存するソースファイルを追加するのに便利です。
sourcePaths string[] ソースファイルを検索する場所のパスをカスタマイズする事ができます。(sourcePathsが指定されていない場合は、任意のフォルダ"source"または"src"が自動的にソースパスとして使用されます。) - あなたは通常、"importPaths""sourcePaths"を定義する必要がある時、それらに影響を与えないという点に注意して下さい。
excludedSourceFiles string[] 既に追加されているソースファイルの中から、除外する必要のあるファイル("sourceFiles"と"sourcePaths"よりも優先されます) - Glob matchingを使用して複数のファイルを一度にパターンマッチすることができます。
mainSourceFile string main()関数を含むファイルを指定します。この設定は、別のmain関数が定義されている状況で、そのファイルを除外するためにdubで使用することが出来ます。(例えば "dub test") - この設定はプラットフォームサフィックスをサポートしていません。
copyFiles string[] targetPathにコピーするファイルやディレクトリのgropsマッチングリスト。一致するディレクトリを再帰的にコピー、すなわち"copyFiles": ["path/to/dir"]" dirを再帰的にコピー。一方、"copyFiles": ["path/to/dir/*"]" dir内のファイルのみコピー
versions string[] コンパイル時に定義されるDバージョンのリスト
debugVersions string[] コンパイル時に定義されるDのデバッグ識別子のリスト
importPaths string[] Dモジュールを検索する追加のインポートパス(source/フォルダが存在する場合、ソースフォルダとしてデフォルトで使用されます。)
stringImportPaths string[] 文字列 imports/viewsを検索する追加のインポートパス(views/フォルダが存在する場合、文字列のインポートフォルダとしてデフォルトで使用されます。)
preGenerateCommands string[] プロジェクトの生成を開始する前に実行されるジェルコマンドのリスト
postGenerateCommands string[] プロジェクトの生成が完了した後に実行されるシェルコマンドのリスト
preBuildCommands string[] プロジェクトをビルドする前に必ず実行されるシェルコマンドのリスト
postBuildCommands string[] プロジェクトがビルドされた後に必ず実行されるシェルコマンドのリスト
dflags string[] Dコンパイラに渡す追加のフラグ - これらのフラグは通常、使用しているコンパイラ固有である事に注意して下さい。しかし、セットされたフラグは自動的にDMDから選択されたコンパイラ用に変換されます。
lflags string[] リンカに渡す追加のフラグ - これらのフラグは通常、使用するリンカ固有である事に注意して下さい。

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

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

バージョン仕様

バージョン仕様は単純な宣言またはより複雑なバリアント、より多くの制御を可能にすることができます。

  • 簡単なバリアント "<name>" : "<version-specifier>" これは、依存関係を指定する通常の方法です。
  • 複雑なバリアント "<name>" : { "<attribute>": "<value>"[, ...] } 次の属性は、依存関係を解決する方法を制御するために使用できます。
    • "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>を使用します。デフォルトでは、最初の構成に一致するターゲットタイプとビルドプラットフォームが自動的に選択されます。構成は、"configurations" セクションを追加することによって定義されます。

もし、構成が指定されていない場合、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",
    "configurations": [
        {
            "name": "metro-app",
            "targetType": "executable",
            "platforms": ["windows"],
            "versions": ["MetroApp"],
            "libs": ["d3d11"]
        },
        {
            "name": "desktop-app",
            "targetType": "executable",
            "platforms": ["windows"],
            "versions": ["DesktopApp"],
            "libs": ["d3d9"]
        },
        {
            "name": "glut-app",
            "targetType": "executable",
            "versions": ["GlutApp"]
        }
    ]
}

あなたは、"subConfigurations"セクションを使用して、特定の依存関係のための具体的な構成を選択することが出来ます:

{
    ...
    "dependencies": {
        "somepackage": ">=1.0.0"
    },
    "subConfigurations": {
        "somepackage": "glut-app"
    }
}

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

構成ブロック固有の設定

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

名前 説明
name [必須] string 構成の名前
platforms string[] 構成を適応するプラットフォームを制限するプラットフォームサフィックス(ビルド設定の為に使用されるような)のリスト

ビルドタイプ

デフォルトでは、事前に定義されたビルドタイプのセットが既に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"

{
    "name": "my-package",
    "buildTypes": {
        "debug": {
            "buildOptions": ["debugMode", "debugInfo", "optimize"]
        },
        "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