Flutter - Create Library Packages (日本語訳)

Create Library Packages の日本語訳

Create Library Packages

ライブラリは簡単に共有できるモジュラーコードを作成する良い方法です。Dart エコシステムではライブラリはパッケージとして作成、配布されます。Dart には2種類のパッケージがあります: アプリケーションパッケージ （ローカルライブラリを含む）と ライブラリパッケージ です。

このドキュメントではライブラリパッケージの作り方とその他の関連リソースを示します。ライブラリの使い方については Install Shared Packages や言語ツアーの Libraries and visibility セクションを参照してください。

What makes a library package

以下の図は最もシンプルなライブラリパッケージを表しています:

ライブラリの最小の要件は:

pubspec フィアル

ライブラリの pubspec.yaml ファイルはアプリケーションパッケージのためのものと同じです。それがライブラリパッケージであることを示すもものは何もありません。

lib ディレクトリ

ご想像のとおり、ライブラリのコードは lib ディレクトリ以下にあり、他のパッケージに対してい公開されます。必要に応じて lib ディレクトリ以下に階層構造を作ることができます。慣例として実装コードは lib/src 以下に置かれます。lib/src 以下のコードはプライベートであるとみなされ、他のパッケージが src/... をインポートすることはありません。 lib/src 以下の API を公開するためには lib/src のファイルを lib 以下のファイルから export します。

Note: library ディレクティブが指定されなかった場合、ユニークなタグがそれぞれのライブラリのパスとファイル名にもとづいて生成されます。したがって、ライブラリレベルドキュメントを生成するつもりがなければ library ディレクティブを指定しないことを推奨します。

Organizing a library package

ミニライブラリとして独立した小さなライブラリパッケージを作る場合、それをメンテナンス、拡張、テストするのは簡単です。二つのクラスが強く関連してない場合、ほとんどのケースでそれぞれのクラスはそれらのミニライブラリに配置するべきです。

Note: part ディレクティブについて聞いたことがあるかもしれません。それは一つのライブラリを二つの Dart ファイルに分割します。part ディレクティブを使わず、かわりにミニライブラリを作ることをお勧めします。

lib/.dart に全てのパブリックAPIを export する "main" ライブラリファイルを作成します。ユーザーは一つのファイルをインポートすることで全ての機能にアクセスできるようになります。

lib ディレクトリは import 可能な他のもの（コードではないものや、ライブラリ）を含むこともあります。例えば、あなたの main ライブラリは各プラットフォームで動作するけれども、dart:io や dart:html に依存する分割されたライブラリを作りたい場合。いくつかのパッケージはプレフィックスを伴って import することを意図された分割されたライブラリを含んでいます。

実際のライブラリがどうやってるかを見てみましょう。shelf パッケージは Dart を使って簡単に Web サーバーを作る方法を提供します。そして Dart パッケージでよくありがちな構成になっています。

lib ディレクトリ以下のメインライブラリファイル shelf.dart が lib/src 以下のいくつかのファイルを export しています:

export 'src/cascade.dart';
export 'src/handler.dart';
export 'src/handlers/logger.dart';
export 'src/hijack_exception.dart';
export 'src/middleware.dart';
export 'src/pipeline.dart';
export 'src/request.dart';
export 'src/response.dart';
export 'src/server.dart';
export 'src/server_handler.dart';

shelf ライブラリはさらにミニライブラリ shelf_io を含んでいます。このアダプタは dart:io の HttpRequest オブジェクトを処理します。

Tip for web apps: dartdevc で開発する際、ベストパフォーマンスを得るために 実装ファイル を別のどこかに置く代わりに /lib/src に配置します。さらに package:package_name/src/... のような import をしないようにします。

Importing library files

ライブラリファイルをインポートするとき、ファイルの URI を指定するために package: ディレクティブを使うことができます。

import 'package:utilities/utilities.dart';

両方のファイルが lib 以下にある場合、または両方のファイルが lib の外にある場合、相対パスを使って import することができます。しかし、インポートするファイルが内と外にリーチする場合は package: を使わなければなりません。迷ったら package: を使いましょう。どのケースでもうまくいきます。

以下のグラフは lib/foo/a.dart を lib と web それぞれでインポートする方法を示しています:

Note: lib の lib/bar/b.dart では相対インポート (import '../foo/a.dart') を使っていますが、代わりに package: ディレクティブ (import 'package:my_package/foo/a.dart') を使うこともできます。

Providing additional files

よくデザインされたライブラリはテストが簡単です。test パッケージを使ってテストを書くことを推奨します。パッケージ直下の test ディレクトリにテストを置きます。

一般に公開するコマンドラインツールを作る場合、それらを bin ディレクトリに置きます。pub global activate を使ってツールをコマンドラインから実行可能にします。executables section にそのツールを指定することでユーザーが pub global run を呼ばなくてもそれを直接実行できるようになります。

ライブラリの利用例を含めると便利でしょう。パッケージ直下の example ディレクトリに置きます。

tool ディレクトリに置いたファイル（開発中に作ったツールや実行可能な何か）は公開されません。

pub.dartlang.org にライブラリを公開する場合、その他のファイル（README と CHANGELOG）が必要になります。README と CHANGELOG については Publishing a Package で説明されています。パッケージのディレクトリ構造についての追加の情報について Pub Package Layout Conventions も参照してください。

Documenting a library

dartdoc ツールを使って API ドキュメントを生成することができます。 Dartdoc はソースコードをパースして documentation comments （/// シンタックスを伴う）を探します:

/// The event handler responsible for updating the badge in the UI.
void updateBadge() {
  ...
}

ドキュメントの生成例: self documentation

Note: 生成されるドキュメントにライブラリドキュメントを含めるためには library ディレクティブを指定する必要があります。See issue 1082

Distributing an open source library

もしあなたのライブラリがオープンソースなら、それを pub.dartlang.org で共有することをお勧めします。ライブラリの公開と更新に pub publish （パッケージのアップロード、作成、更新を行う）を使います。例えば、 shelf パッケージは pub.dartlang.org/packages/shelf に公開されています。パッケージを公開するにあたっての準備の詳細については Publishing a Package を参照してください。

pub site はあなたのパッケージをホストするだけではありません。API ドキュメントの作成も行います。最後に生成されたドキュメントへのリンクは About セクションにあります。例えば shelf パッケージの API ドキュメントはここにあります pub.dartlang.org/documentation/shelf。以前のバージョンのドキュメントはパッケージページの Versions タブにあります。

パッケージの API ドキュメントが pub site できちんと見えるようにするために以下のステップに従ってください:

• パッケージをパブリッシュする前に、ドキュメントが期待通りに作成されるかを確認するために dartdoc を実行する
• パッケージをパブリッシュした後、Versions タブをチェックしてドキュメントが生成されたとこを確認する
• もしドキュメントが生成されなかった場合、Versions タブの faild をクリックして dartdoc のアウトプットを確認する

Resources

ライブラリパッケージに関するさらなる詳細については以下を参照してください:

• Libraries and visibility in the language tour covers using library files.

• The pub documentation is useful, particularly Pub Package Layout Conventions.
• What Not to Commit covers what should not be checked into a source code repository.
• The newer library packages under the dart-lang organization tend to show best practices. Consider studying these examples: dart_style, path, shelf, source_gen, and test.