Dartで開発する上でpubは欠かせないツールですが、pubを利用するプロジェクト（以後 pubパッケージ と呼ぶ）内のディレクトリ構成に大きく依存しています。これは自分の作ったパッケージをpubに公開する、しないにかかわらず重要なポイントなので、一度きちんとおさらいしておこうと思います。
この記事では公式ドキュメントのPub Package Layout Conventionsに書かれている内容を和訳して注釈を入れつつまとめていきます。
基本構成
pubパッケージの最小構成は以下になります。
enchilada/
pubspec.yaml
pubspec.lock
pubspec.yamlさえあれば一応pubに公開することが出来ます。他にもLICENSEやAUTHORS等のファイルはこの階層（トップレベル）においておくことが推奨されます。
README.md
pubに公開するパッケージにはMarkdown形式のREADMEを含めることが推奨されています。
enchilada/
...
README.md
トップレベルに置かれたREADME.mdはpub.dartlang.orgで見ることができるので、なるべくパッケージの内容や使い方がすぐに分かるような内容を心がけるといいですね。ちなみにAngularDartのREADMEはこのようになっています。
CHANGELOG.md
READMEと同様に、CHANGELOGもpubのページで見ることができるので、ぜひ書きましょう。
enchilada/
...
CHANGELOG.md
ちなみにunittestパッケージのCHANGELOGはこちら
公開ライブラリ
公開ライブラリは以下のようにlibディレクトリ内に配置します。
enchilada/
lib/
enchilada.dart
tortilla.dart
公開ライブラリとは？
公開ライブラリとは、そのパッケージをpub installで導入した後、import文で読み込むことが出来るdartファイル群のことを指します。AngularDartであればangular/angular.dart等が公開ライブラリに含まれています。
どう使えばいいの？
ライブラリとして公開する
そのままですが、pubにライブラリを公開する際は、公開ライブラリとして配置しなければなりません。
シンボリックリンクの生成に利用する
こちらのほうが実は重要で、pub getを実行すると、pubspec.yamlに書かれた依存関係を解決するだけでなく、 『公開ライブラリとして配置されたlib以下のコードへのシンボリックリンクをpackages以下に貼り、擬似的にpubでインストールしたように見せる』 ことができます。これが何を意味するかというと、ライブラリ用のパッケージと、ユニットテスト用のパッケージを分けることができるということです。テストに関する配置に関してはまた後述します。
リファレンス用パッケージ
公開したアプリケーションのデモ用のページを含めることがよくあります。pubパッケージでは次のように配置します。
myapp/
example/
one/
sub/
index.html
exampleに配置するのはあくまでライブラリの動作サンプル等であり、Webアプリケーションは後述するwebディレクトリ内で開発します。
公開アセット
pubに公開されているのはdartライブラリだけではなく、boostrap_for_pubのように、cssやhtml、jsのセットだけを提供しているものも多くあります。そのようなdartファイル以外のものを アセット と呼びますが、ライブラリとして公開したいアセットは以下のようにlibディレクトリに配置します。
enchilada/
lib/
guacamole.css
このように配置されたアセットを利用する場合は次のようにhtmlから参照可能です。
<link href="packages/enchilada/guacamole.css" rel="stylesheet">
実装ファイル（非公開コード）
公開ライブラリとして公開しているコードではimportしているが、外部からはされたくないということはよくあることです。以下のようにlib/src内に配置したdartファイルはlib内でのみ公開されます。
enchilada/
lib/
src/
beans.dart
queso.dart
Webファイル
Webアプリケーションを作る際はhtml等を以下のようにwebディレクトリ内に配置します。
enchilada/
web/
index.html
main.dart
style.css
webディレクトリ内に配置されたファイル群はpub buildやpub serveのビルド対象になります。
コマンドラインアプリ
コマンドラインで直接実行するタイプのアプリケーションを公開する際は以下のようにbinディレクトリに実行ファイルを配置します
enchilada/
bin/
enchilada
テスト・ベンチマークコード
テストコードは以下のようにtestディレクトリ内に配置します。
enchilada/
test/
enchilada_test.dart
tortilla_test.dart
testディレクトリから読み込むことが出来るのはpackagesディレクトリだけなので、テストを行いたいコードは、先述のlibディレクトリに配置してpub getでシンボリックリンクを生成しておく必要があります。逆に言うと、 libフォルダ以外に置いたdartファイルはテスト出来ません。
また、テスト用のファイルはテスト対象のファイル_test.dartにするのが慣例です。
ベンチマーク用のコードは以下のようにbenchmark以下に配置します。
enchilada/
benchmark/
make_lunch.dart
余談
テストに用いるunittestパッケージは有名ですが、ベンチマーク用にもDart開発チームがbenchmark_harnessというパッケージを公開しています。使い方はこちらで、同じコードを10回実行した時の平均時間をレポートしてくれたりとけっこう便利なパッケージのようです。
ドキュメント
ドキュメントファイルは以下の用にdocディレクトリ内に配置します。
enchilada/
doc/
getting_started.md
ちなみにDartSDKにはdocgenというツールが内蔵されていて、$ docgenを実行するとdocsディレクトリ内にlib以下のコードをドキュメントにしたjsonファイルが発行されますが、docディレクトリのものとは別なので注意してください。docディレクトリに置くのはdocgenで吐き出されるAPIリファレンスを補足するためのチュートリアルやガイド、その他手書きのドキュメントです。
サンプルコード
Dartライブラリの使い方としてサンプルコードを公開する際は以下のようにexampleディレクトリ内に配置します。
enchilada/
example/
lunch.dart
内部ツール・スクリプト
開発に使うツールやスクリプトは以下のようにtoolディレクトリ内に配置します。
enchilada/
tool/
generate_docs.dart
binディレクトリとの違いは、toolディレクトリはパッケージ開発者向けであって、外部に公開されるものではないということです。
これでpubパッケージのディレクトリ構成についての解説は全てです。実際に使うのはlib、web、testくらいのもので、全部を使うことはないと思いますが、覚えておくといざというときに役に立つと思います。