メインコンテンツにスキップ
目次

パッケージレイアウトの規約

目次 keyboard_arrow_down keyboard_arrow_up
more_horiz

pubパッケージを作成する際には、このページで説明する規約に従うことをお勧めします。これらは、パッケージ内のファイルとディレクトリの構成方法、および名前の付け方について説明しています。

これらのガイドラインのすべての要素を使用した、完全なパッケージ（enchiladaという名前）は次のようになります。

enchilada/
  .dart_tool/ *
  pubspec.yaml
  pubspec_overrides.yaml **
  pubspec.lock ***
  LICENSE
  README.md
  CHANGELOG.md
  benchmark/
    make_lunch.dart
  bin/
    enchilada
  doc/
    api/ ****
    getting_started.md
  example/
    main.dart
  hook/
    build.dart
  integration_test/
    app_test.dart
  lib/
    enchilada.dart
    tortilla.dart
    guacamole.css
    src/
      beans.dart
      queso.dart
  test/
    enchilada_test.dart
    tortilla_test.dart
  tool/
    generate_docs.dart
  web/
    index.html
    main.dart
    style.css

* .dart_tool/ ディレクトリは、dart pub get を実行した後に存在します。ソース管理にコミットしないでください。詳細については、ツールのプロジェクト固有キャッシュを参照してください。

** pubspec_overrides.yaml ファイルが存在する場合、pubspec.yaml の特定の側面をオーバーライドします。通常、ソース管理にコミットする必要はありません。

*** pubspec.lock ファイルは、dart pub get を実行した後に存在します。パッケージがアプリケーションパッケージでない限り、ソース管理から除外してください。

**** doc/api ディレクトリは、dart doc を実行した後にローカルに存在します。api ディレクトリをソース管理にコミットしないでください。

pubspec

#
enchilada/
  pubspec.yaml
  pubspec.lock

すべてのパッケージには、パッケージのルートディレクトリにpubspec、つまりpubspec.yamlという名前のファイルがあります。これがパッケージである所以です。

パッケージでdart pub get、dart pub upgrade、またはdart pub downgradeを実行すると、pubspec.lockという名前のロックファイルが作成されます。パッケージがアプリケーションパッケージの場合は、ロックファイルをソース管理にコミットしてください。それ以外の場合は、コミットしないでください。

詳細については、pubspecページを参照してください。

LICENSE

#
enchilada/
  LICENSE

パッケージを公開する場合は、LICENSE という名前のライセンスファイルを含めてください。他の人があなたの作品を再利用できるように、OSI承認ライセンス（例：BSD-3-Clause）を使用することをお勧めします。

README.md

#
enchilada/
  README.md

オープンソースで非常に一般的なファイルは、プロジェクトを説明するREADMEファイルです。これはpubでは特に重要です。pub.devサイトにアップロードすると、README.mdファイルがパッケージのページにMarkdownとしてレンダリングされて表示されます。これは、人々があなたのコードを紹介するのに最適な場所です。

優れたREADMEの書き方については、パッケージページの作成を参照してください。

CHANGELOG.md

#
enchilada/
  CHANGELOG.md

パッケージの各リリースごとにセクションがあり、ユーザーがパッケージをアップグレードするのに役立つノートが含まれているCHANGELOG.mdファイルを含めてください。パッケージのユーザーは、バグ修正や新機能を発見したり、最新バージョンへのアップグレードにかかる労力を判断するために、しばしば変更履歴を確認します。

CHANGELOG.mdを解析するツールをサポートするために、次の形式を使用してください。

  • 各バージョンには、見出し付きの独自のセクションがあります。
  • バージョン見出しは、すべてレベル1またはすべてレベル2です。
  • バージョン見出しテキストには、パッケージバージョン番号が含まれ、オプションで「v」がプレフィックスとして付いています。

パッケージをpub.devサイトにアップロードすると、パッケージのCHANGELOG.mdファイル（存在する場合）がChangelogタブに表示され、Markdownとしてレンダリングされます。

以下はCHANGELOG.mdファイルの例です。例に示すように、サブセクションを追加できます。

markdown
# 1.0.1

* Fixed missing exclamation mark in `sayHi()` method.

# 1.0.0

* **Breaking change:** Removed deprecated `sayHello()` method.
* Initial stable release.

## Upgrading from 0.1.x

Change all calls to `sayHello()` to instead be to `sayHi()`.

# 0.1.1

* Deprecated the `sayHello()` method; use `sayHi()` instead.

# 0.1.0

* Initial development release.

公開ディレクトリ

#

パッケージ内の2つのディレクトリは、他のパッケージに対して公開されます：libとbin。libには公開ライブラリを、binには公開ツールを配置します。

公開ライブラリ

#

以下のディレクトリ構造は、enchiladaのlib部分を示しています。

enchilada/
  lib/
    enchilada.dart
    tortilla.dart

多くのパッケージは、他のパッケージがインポートして使用できるDartライブラリを定義しています。これらの公開Dartライブラリファイルは、libという名前のディレクトリ内に配置します。

ほとんどのパッケージは、ユーザーがインポートできる単一のライブラリを定義しています。その場合、その名前は通常、パッケージの名前と同じになります。たとえば、ここの例ではenchilada.dartです。ただし、パッケージにとって意味のある任意の名前で他のライブラリを定義することもできます。

そうすると、ユーザーは次のように、パッケージ名とライブラリファイルの名前を使用してこれらのライブラリをインポートできます。

dart
import 'package:enchilada/enchilada.dart';
import 'package:enchilada/tortilla.dart';

公開ライブラリを整理したい場合は、lib内にサブディレクトリを作成することもできます。その場合、ユーザーはインポート時にそのパスを指定します。以下のファイル階層があるとします。

enchilada/
  lib/
    some/
      path/
        olives.dart

ユーザーは次のようにolives.dartをインポートします。

dart
import 'package:enchilada/some/path/olives.dart';

lib内にはライブラリのみを配置することに注意してください。エントリポイント—main()関数を持つDartスクリプト—はlibに配置できません。lib内にDartスクリプトを配置すると、それらが含むpackage:インポートが解決されないことがわかります。代わりに、エントリポイントは適切なエントリポイントディレクトリに配置する必要があります。

パッケージの詳細については、パッケージの作成を参照してください。

公開ツール

#

binディレクトリ内に配置されたDartスクリプトは公開されます。パッケージのディレクトリ内にいる場合、dart runを使用して、パッケージが依存する他のパッケージのbinディレクトリにあるスクリプトを実行できます。任意のディレクトリから、dart pub global activateを使用してアクティブ化したパッケージのスクリプトを実行できます。

パッケージが依存されることを意図しており、スクリプトをパッケージにプライベートにしたい場合は、トップレベルのtoolディレクトリに配置してください。パッケージが依存されることを意図していない場合は、スクリプトをbinに置いたままにすることができます。

公開アセット

#
enchilada/
  lib/
    guacamole.css

ほとんどのパッケージはDartコードの再利用を目的としていますが、他の種類のコンテンツも再利用できます。たとえば、Bootstrapのパッケージには、パッケージのコンシューマーが使用できる多数のCSSファイルが含まれる場合があります。

これらはトップレベルのlibディレクトリに配置されます。そこには任意の種類のファイルを配置し、サブディレクトリを使用して自由に整理できます。

実装ファイル

#
enchilada/
  lib/
    src/
      beans.dart
      queso.dart

lib内のライブラリは公開されており、他のパッケージは自由にインポートできます。しかし、パッケージのコードの多くは、パッケージ自体によってのみインポートおよび使用されるべき内部実装ライブラリです。これらはlibのサブディレクトリであるsrc内に配置します。整理に役立つ場合は、そこにサブディレクトリを作成できます。

同じパッケージ内の他のDartコード（libの他のライブラリ、binのスクリプト、テストなど）からlib/srcに存在するライブラリをインポートすることは自由ですが、他のパッケージのlib/srcディレクトリからインポートすることは絶対に避けてください。これらのファイルはパッケージの公開APIの一部ではなく、コードを壊す可能性のある方法で変更される場合があります。

自分のパッケージ内のライブラリをインポートする方法は、ライブラリの場所によって異なります。

例

lib/beans.dart
dart
// When importing from within lib:
import 'src/beans.dart';
test/beans_test.dart
dart
// When importing from outside lib:
import 'package:enchilada/src/beans.dart';

ここで使用する名前（この例ではenchilada）は、pubspecでパッケージに指定する名前です。

Webファイル

#
enchilada/
  web/
    index.html
    main.dart
    style.css

Webパッケージの場合、エントリポイントコード（main()を含むDartスクリプトや、CSSやHTMLなどのサポートファイル）はwebの下に配置してください。必要に応じてwebディレクトリをサブディレクトリに整理することもできます。

ライブラリコードはlibの下に配置します。ライブラリがwebの下のコードや他のパッケージによって直接インポートされない場合は、lib/srcの下に配置します。Webベースの例はexampleの下に配置します。アセット（画像など）の配置場所に関するヒントについては、公開アセットを参照してください。

コマンドラインアプリ

#
enchilada/
  bin/
    enchilada

一部のパッケージは、コマンドラインから直接実行できるプログラムを定義しています。これらはシェルスクリプトや、Dartを含む他のスクリプト言語である可能性があります。

パッケージがこの種のコードを定義している場合は、binという名前のディレクトリに配置してください。dart pub globalで設定すれば、コマンドラインのどこからでもそのスクリプトを実行できます。

テストとベンチマーク

#
enchilada/
  test/
    enchilada_test.dart
    tortilla_test.dart

すべてのパッケージにはテストが必要です。pubでは、これらのほとんどはtestディレクトリ（または必要に応じてその中のディレクトリ）に配置され、ファイル名の末尾に_testが付くという規約があります。

通常、これらはtestパッケージを使用します。

enchilada/
  integration_test/
    app_test.dart

Flutterアプリパッケージには、integration_testパッケージを使用する特別な統合テストも含まれる場合があります。これらのテストは、独自のintegration_testディレクトリに配置されます。

他のパッケージは同様のパターンに従って、遅い統合テストを単体テストから分離することを選択できますが、デフォルトではdart testはこれらのテストを実行しないことに注意してください。dart test integration_testで明示的に実行する必要があります。

enchilada/
  benchmark/
    make_lunch.dart

パフォーマンスが重要なコードを持つパッケージには、ベンチマークも含まれる場合があります。これらは、正確性ではなく速度（またはメモリ使用量、または他の経験的メトリック）のためにAPIをテストします。

ドキュメント

#
enchilada/
  doc/
    api/
    getting_started.md

コードとテストがある場合、次に必要となるのは優れたドキュメントです。これはdocという名前のディレクトリ内に配置します。

dart docツールを実行すると、APIドキュメントはデフォルトでdoc/apiの下に配置されます。APIドキュメントはソースコードから生成されるため、ソース管理に含めるべきではありません。

生成されたapi以外の、作成するドキュメントの形式や構成に関するガイドラインはありません。好みのマークアップ形式を使用してください。

例

#
enchilada/
  example/
    main.dart

コード、テスト、ドキュメント、ユーザーは他に何を求めるでしょうか？あなたのパッケージを使用するスタンドアロンのサンプルプログラム、もちろん！これらはexampleディレクトリ内に配置します。例が複雑で複数のファイルを使用する場合は、各例にディレクトリを作成することを検討してください。それ以外の場合は、各例をexampleの直下に配置できます。

例では、package:を使用して自分のパッケージのファイルにインポートしてください。これにより、パッケージ内の例コードがパッケージ外のコードと同じように見えることが保証されます。

パッケージを公開する可能性がある場合は、次のいずれかの名前の例ファイルを作成することを検討してください。

  • example/example[.md]
  • example[/lib]/main.dart
  • example[/lib]/package_name.dart
  • example[/lib]/package_name_example.dart
  • example[/lib]/example.dart
  • example/README[.md]

上記ファイルの1つ以上を含むパッケージを公開すると、pub.devサイトはExampleタブを作成し、最初に見つかったファイル（上記のリストの順序で検索）を表示します。たとえば、パッケージのexampleディレクトリの下に多くのファイルがあり、README.mdという名前のファイルが含まれている場合、パッケージのExampleタブにはexample/README.mdの内容が表示されます（Markdownとして解析）。

内部ツールとスクリプト

#
enchilada/
  tool/
    generate_docs.dart

成熟したパッケージには、パッケージ自体の開発中に人々が実行する小さなヘルパースクリプトやプログラムがよくあります。テストランナー、ドキュメントジェネレーター、その他の自動化ビットなどを考えてください。

binのスクリプトとは異なり、これらはパッケージの外部ユーザー向けではありません。これらがある場合は、toolという名前のディレクトリに配置してください。

フック

#
enchilada/
  hook/
    build.dart

パッケージは、DartおよびFlutter SDKによって呼び出されるフックを定義できます。これらのフックには定義済みのCLIがあり、存在する場合はSDKツールによって呼び出されます。

これらのフックは実行およびビルド時にdartおよびflutterツールによって呼び出されるため、これらのフックの依存関係は通常の依存関係である必要があり、dev_dependenciesであってはいけません。

ツールのプロジェクト固有キャッシュ

#

.dart_tool/ ディレクトリは dart pub get を実行したときに作成され、いつでも削除される可能性があります。さまざまなツールがこのディレクトリをプロジェクト固有および/またはローカルマシン固有のファイルをキャッシュするために使用します。.dart_tool/ ディレクトリは、ソース管理にコミットしたり、マシン間でコピーしたりしないでください。

.dart_tool/ ディレクトリを削除しても一般的に安全ですが、一部のツールはキャッシュされた情報を再計算する必要がある場合があります。

例: dart pub get ツールは、依存関係をグローバルな $PUB_CACHE ディレクトリにダウンロードして展開し、次にパッケージ名をグローバルな $PUB_CACHE ディレクトリ内のディレクトリにマッピングする .dart_tool/package_config.json ファイルを書き込みます。 .dart_tool/package_config.json ファイルは、アナライザーやコンパイラなどの他のツールが import 'package:foo/foo.dart' のようなステートメントを解決する必要がある場合に使用されます。

プロジェクト固有のキャッシュを必要とするツールを開発する場合、ほとんどのユーザーが .gitignore で無視しているため、 .dart_tool/ ディレクトリの使用を検討してください。ユーザーの .dart_tool/ ディレクトリにツール用のファイルをキャッシュする場合、一意のサブディレクトリを使用する必要があります。衝突を避けるために、 .dart_tool/<tool_package_name>/ の形式のサブディレクトリは、 <tool_package_name> という名前のパッケージ用に予約されています。ツールが pub.devサイトを介して配布されていない場合、一意の名前を予約するためにプレースホルダーパッケージを公開することを検討してください。

例: package:build は、コード生成ステップを作成するためのフレームワークを提供します。これらのビルドステップを実行すると、ファイルは .dart_tool/build/ にキャッシュされます。これにより、ビルドステップの将来の再実行が高速化されます。

別途記載がない限り、このサイトのドキュメントは Dart 3.8.1 を反映しています。ページは2025-02-28に最終更新されました。 ソースを表示 または 問題を報告。