パッケージレイアウト規則

目次 keyboard_arrow_down keyboard_arrow_up

pubspec
LICENSE
README.md
CHANGELOG.md
公開ディレクトリ
- 公開ライブラリ
- 公開ツール
公開アセット
実装ファイル
Webファイル
コマンドラインアプリ
テストとベンチマーク
ドキュメント
例
内部ツールとスクリプト
フック
ツールのためのプロジェクト固有のキャッシング

more_horiz

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

これらのガイドラインのあらゆる側面を使用する完全なパッケージ（名前：enchilada）の例を示します。

enchilada/
  .dart_tool/ *
  pubspec.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.lockファイルは、dart pub getを実行した後に作成されます。パッケージがアプリケーションパッケージでない限り、ソース管理から除外してください。

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

enchilada/
  pubspec.yaml
  pubspec.lock

すべてのパッケージには、パッケージのルートディレクトリにpubspec.yamlという名前のpubspecがあります。これがパッケージをパッケージたらしめるものです。

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

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

enchilada/
  LICENSE

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

enchilada/
  README.md

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

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

enchilada/
  CHANGELOG.md

パッケージの各リリースごとにセクションがあり、パッケージのユーザーがアップグレードするのに役立つメモを含むCHANGELOG.mdファイルを含めてください。パッケージのユーザーは、変更ログを確認してバグ修正や新機能を確認したり、パッケージの最新バージョンにアップグレードするのに必要な労力を判断したりすることがよくあります。

CHANGELOG.mdを解析するツールをサポートするには、次の形式を使用します。

各バージョンには、見出し付きの独自のセクションがあります。
バージョン見出しは、すべてレベル1かすべてレベル2です。
バージョン見出しテキストには、パッケージのバージョン番号が含まれ、オプションで「v」を接頭辞として付けることができます。

pub.devサイトにパッケージをアップロードすると、パッケージのCHANGELOG.mdファイル（存在する場合）が変更ログタブに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）。ただし、パッケージにとって意味のある名前を持つ他のライブラリを定義することもできます。

その場合、ユーザーはパッケージ名とライブラリファイル名を使用してこれらのライブラリをインポートできます。例：

dartimport '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に配置できません。Dartスクリプトをlibに配置すると、そこに含まれる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/ ディレクトリの内側または外側を参照する場合（lint: lib/の内側または外側へのアクセス（lint: avoid_relative_lib_imports））、package: を使用してください。
それ以外の場合は、相対パスによるインポートを優先してください。

例

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でパッケージに指定する名前です。

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

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

ライブラリコードはlibディレクトリ下に配置します。ライブラリがweb下のコードまたは他のパッケージから直接インポートされない場合は、lib/srcディレクトリ下に配置します。ウェブベースの例は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ディレクトリ下にREADME.mdという名前のファイルを含む多くのファイルがある場合、パッケージの「例」タブには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.5.3を反映しています。最終更新日：2024年5月6日。ソースを表示または問題を報告する。

パッケージレイアウト規則

pubspec

LICENSE

README.md

CHANGELOG.md

公開ディレクトリ

公開ライブラリ

公開ツール

公開アセット

実装ファイル

Webファイル

コマンドラインアプリ

テストとベンチマーク

ドキュメント

例

内部ツールとスクリプト

フック

ツールのためのプロジェクト固有のキャッシング