開発編

Pub パッケージ・マネージャ

読者が開発したDartパッケージを取り扱うためのpubツールがSDKに含まれている。

注意： Flutter SDKではパッケージの管理と更新のための独自のコマンドを有している。これに関してはFlutterのウェブ・サイトのUsing Packagesのほうを読まれたい。

pubコマンドはIntelliJ IDEAのようなIDEから、或いはコマンド行として直接アクセスできる。どちらを使うかは読者がもっとも使い勝手の良い手段を選択すればよい。この解説ではIntelliJ IDEAを用いている。

Dartコードの中には通常その最初のところに例えば次のようなimport文が置かれる：

import 'dart:io';
import 'package:args/args.dart';
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;
import 'package:shelf_static/shelf_static.dart';

これはサーバにミドルウエアのshelfを使ったコードの例であるが、これらの中にはDartのAPI参照に含まれていないdart:ではなくてpackage:というサフィックスが付いているライブラリが指定されている。これはpubパッケージ・マネージャを使ってインポートされることを想定している。このパッケージはhttps://pub.dartlang.org/というリポジトリの中に含まれている。このリポジトリは現在大規模なものに成長し続けており、Dartのユーザには貴重な財産になっている。

pubパッケージ・マネージャはアプリケーションの中に含まれるpubspec.yamlという特別なファイルを見て、そこに記載されているそのアプリケーションに必要なpubライブラリ（依存物：dependency）をhttps://pub.dartlang.org/から取り込み、packagesというフォルダに収容する。

PubはDartの為のパッケージ・マネージャのシステムである。これはおなじレポジトリ・システムのGithubの影響を強く受けており、互換性がとられている。これによりプログラマたちは既存のDartコードの再利用ができ、他の人たちとの共有と再利用の為にDartのアプリケーションたちとライブラリたちをバンドル出来るようになる。Pubはバージョン管理と依存物(dependancy)管理をするので、自分のアプリケーションが確実に他のマシン上でも自分のマシン上で走ると同じように走らせることができる。

従って自分のパッケージをhttps://pub.dartlang.org/にパブリッシュするといった、より習熟したユーザはGithubのアカウントを持つことが必須となる。

Pubの概要

最初に自分が開発しているDartアプリのパッケージにたいし、pubをどのように利用するかを概説する。

手順は次のようになろう：

pubspec.yamlファイル（ヤムル・ファイルと言う：YAML形式で書かれたテキストのファイル）を作る。これはこのパッケージが依存している他のパッケージたち(dependencies)、及び自分のパッケージの名前等のメタデータのリストを記入したファイルである
自分のパッケージの依存物たちを取り込むのにpubを使用する
取り込んだライブラリたちをimport文でインポートする

pubspecの作成

pubspec.yamlファイルをまず作らねばならない。このファイルは自分のアプリのトップのディレクトリ内に置かねばならない。

最も簡単なものは自分のパッケージの名前をリストアップすることである：

name: my_app

次にpubspecは依存物たちとそのどのバージョンが必要かを記入する。次の例を見てみよう：

name: my_app
dependencies:
  js: ^0.3.0
  intl: ^0.12.4

ここではPubのサイトにホストされているjsパッケージを指定していて、次に Dart SDKに入っているintlパッケージを指定している。その詳細は pubspecドキュメンテーションと自分が使いたいパッケージのドキュメンテーションを参照のこと。

パッケージのインストール

これは「依存物たちの取得(getting the dependencies)」とも呼ばれる。

これはコマンド行では自分のアプリのトップ・ディレクトリから次のように指定する：

cd <path-to-my_app>
pub get

IDE上ではpubspec.yamlファイルをコード・ビュー上で開くと次のように使えるアクションが表示されるので、Get dependenciesをクリックすればよい：

pub getコマンドは自分のアプリが依存しているパッケージたちを判断してそれをシステム・キャッシュ（自分のPCのOSが管理するキャッシュ）に置く。gitに置かれている依存物たちの場合は,pubはそのgitリポジトリのクローンを作る。Pubのサイトにホストされている依存物たちに対してはpubはPubのサイトからダウンロードする。過渡的な依存物たちも含まれる。例えば、もしjsパッケージがtestパッケージに依存している場合は、pubはその双方を取り込む。

pubは.packagesファイルを生成する。これはそのパッケージ名とシステム・キャッシュ内のパッケージとのマップである。

パッケージから必要なライブラリをインポートする

パッケージたちに入っているライブラリをインポートするにはpackage: プレフィックスの形式を使う：

import 'package:js/js.dart' as js;
import 'package:intl/intl.dart';

Dartのランタイムはpackage:のあとに続くものを調べ、自分のアプリの.packagesファイル内を検索する。

この書式で自分自身のパッケージからのライブラリをインポートすることも可能である。

次のようなpubspecファイルを考えてみよう。これは（仮想のものだが）transmogrify（変形）というパッケージに依存している：

name: my_app
dependencies:
  transmogrify:

自分のパッケージが次のような構成になっているとしよう：

transmogrify/
  lib/
    transmogrify.dart
    parser.dart
  test/
    parser/
      parser_test.dart

parser_test.dartファイルは以下のようにparser.dartをインポートできよう：

import '../../lib/parser.dart';

しかしこれは相対パスを使っているので好ましくない。 parser_test.dartファイルが別のディレクト内に移ったら、この相対位置関係が崩れ、このコードを修正しなければならなくなる。そうしないで、次のように書くことが可能である：

import 'package:transmogrify/parser.dart';

こうすればインポートするファイルが何処に位置するかに関わらずこのインポート文は常にparser.dartを取り込むことが可能である。

依存物のアップグレード

自分のパッケージに新規の依存物を最初に取得する際は、pubは自分の他の依存物たちと互換性がある最新のバージョンをダウンロードする。次にlockファイルを作って自分のパッケージが常にそのバージョンを使うよう自分のパッケージをロックする。このファイルは pubspec.lockというファイルで、pubはpubspecの隣にストアする。これは自分のパッケージが使っている各依存物たちの特定のバージョンのリストである。

アプリのパッケージの場合は、ソース・コードの管理にはこのファイルを調べる必要がある。これにより自分のアプリの開発に携わっている各自がこれらのパッケージの総てで同じバージョンのものを使っているようになる。更にこのアプリを現用に配備する際、確実に同じバージョンが使われるようになる。

もし自分の依存物たちを最新のものにアップグレードしたいときには、以下のように実行する：

$ pub upgrade

IDEの場合は前図に示されているUpgrade dependenciesをクリックする：

これはpubに対し自分のパッケージの依存物たちが使える最新のバージョンのものを使ったロック・ファイルを作り直すよう指示している。もし特定の依存物だけをアップグレードしたいときは次のように指定できる：

$ pub upgrade transmogrify

この場合はtransmogrifyを最新のものにアップグレードするが、他の依存物たちはそのままにしておく。

Pubパッケージのレイアウト規約 (Layout Conventions)

ライブラリは容易に他の人たちと共有できるモジュール構成のコードを作る素晴らしい手段である。Dartのエコシステム内では、ライブラリたちはパッケージとして作成・配布されている。Pubにおけるパッケージは、コードだけでなく画像などのリソース、ドキュメント、またテストに必要なファイルなどそのアプリケーションに必要ないろんな形式のファイルを含めたディレクトリといえる。再使用可能なライブラリなどもまたパッケージである。

＊＊＊以下は基本的にGoogleのパッケージ・レイアウト規約の翻訳である＊＊＊

Dartには2種類のパッケージがある：即ちローカルのライブラリを含み得るアプリケーション・パッケージとライブラリのパッケージである：

アプリケーション・パッケージ(application package)

他のパッケージたちを使うものの、それ自身は再使用されないパッケージをいう。
ライブラリ・パッケージ(library package)

他のパッケージたちによって再使用されることを意図したパッケージ。他の人たちが使用できるようにどこかにホストされる。通常他のパッケージをインポートしたコードを含む。ライブラリ・パッケージは依存物(dependancy)として使われる。

殆どの場合これらの相違は無く、単に「パッケージ」と呼ばれる。相違が問題になる場合は「アプリケーション・パッケージ」または「ライブラリ・パッケージ」と区別している

パッケージのレイアウト

ライブラリ・パッケージは多くの人たちが利用するものであるので、Googleはパッケージのレイアウトやファイルの名前付けに関し以下の規約に従うことを求めている。今後開発されるであろういろんなツールもこの規約にあったパッケージを対象にすることになろう。

全体像を把握しやすいように規約に本準拠した完全なパッケージ（便宜的にメキシコ料理のenchiladaという名前がつけられている）の例を示す：

enchilada/
  pubspec.yaml
  pubspec.lock *
  README.md
  LICENSE
  bin/
    enchilada
    packages/ **
  doc/
    getting_started.md
  example/
    lunch.dart
    packages/ **
  lib/
    enchilada.dart
    tortilla.dart
    src/
      beans.dart
      queso.dart
  packages/ **
  test/
    enchilada_test.dart
    tortilla_test.dart
    packages/ **
  tool/
    generate_docs.dart
  web/
    index.html
    main.dart
    style.css

各要素を説明すると：

enchilada/
  pubspec.yaml
  pubspec.lock *

各パッケージはそのルート・ディレクトリにpubspec（すなわちpubspec.yamlというヤムル・ファイル）を持つ。このパッケージで一旦インストール(pub install)や更新(pub update)を実行するとロック・ファイル(pubspec.lock)が作られる。そのパッケージがアプリケーション・パッケージの場合は、ソース・コードの管理に使われる。

enchilada/
  packages/
    ...

Pubインストールを実行するとpackagesというディレクトリが作られる。これはユーザが気にする必要はない。（IDEの場合は.packagesというファイルが作られる）

enchilada/
  README.md

オープン・ソースの世界では一般的にプロジェクトのトップ・レベルにREADME、LICENSE、AUTHORSなどのファイルを置く。そのなかでもREADMEは極力置くことが求められる。Gitでお馴染みのマークダウン記法によるREADME.mdファイルが一般的である。

パブリックなライブラリ・パッケージ

enchilada/
  lib/
    enchilada.dart
    tortilla.dart

多くのパッケージはライブラリ・パッケージで、これらは他のパッケージがインポートして使用するためのDartのライブラリを含む。これらのDartライブラリは上の例で示したようにlibというディレクトリに収容されている。

ほとんどのライブラリ・パッケージは単一のDartライブラリを指定するものなので、その場合はパッケージ名は通常そのDartのライブラリ名と同じものを使用する。別の名前が使われる場合は、ユーザはそのライブラリをパッケージ名とライブラリ・ファイルの名前を使ってインポートすることになる。以下はそれらの例である：

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

もし自分のパブリックなライブラリたちの編成を変えたい場合が出たときには、libの中にサブ・ディレクトリを作ることもできる。その場合は、ユーザはそれらをインポートするときはそのパスを指定することになる。例えば次のようなディレクトリ階層を作ったとしよう：

enchilada/
  lib/
    some/
      path/
        olives.dart

その場合は、ユーザがolives.dartをインポートするときは次のように指定する：

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

ライブラリたちのみがlibディレクトリに置かれねばならないことに注意のこと。エントリ点（即ちmain()関数を持ったDartコード）はlibには置けない。そのようなDartコードをlibに置くと、それが含んでいるpackage: インポートは解決できないことを読者は判るだろう。エントリ点はbin、example、test、tool、あるいはwebといったしかるべきディレクトリに置かれねばならない。

実装ファイル (Implementation files)

これは「自分のライブラリ・パッケージを作る」の節でも解説するが、

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

のようにsrcと呼ばれるlibのサブディレクトリ内部に置かれる。

ウェブ・ファイル (Web files)

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

Dartはウェブの世界を対象にした言語であるので、多くのpubパッケージはウェブの要素を扱う。即ちHTML、CSS、画像、及びおそらくはJavaScriptも扱うことを意味する。これらの総ては皆さんのパッケージのwebディレクトリに収容される。このディレクトリ中身をどのように構成するかは自由である。従ってそのほうが良ければサブ・ディレクトリたちを設けても構わない。

そして重要なことであるが、Dartのどのwebのエントリ点（言い換えれば<script>タグのなかで参照されているDartのスクリプトたち）はlibではなくてwebディレクトリに入る。これにより近くにpackagesディレクトリがあってそれにより確実にpackage:インポートたちが正しく解決されるように出来る。

（「自分のウェブ・ベースのサンプル・プログラムを何処におこうか？programsそれともweb？」と自問する事態になったときは、exampleディレクトリに収容すると良い）

コマンド行アプリケーション (Command-line apps)

enchilada/
  bin/
    enchilada

一部のパッケージはコマンド行から直接実行できるプログラムを定義している。そのようなプログラムはシェル・スクリプトまたはDartを含むその他のスクリプト言語であり得る。pubアプリケーションそれ自身もひとつの例であり、これはpub.dartを呼び出す簡単なスクリプトである。

もし読者のパッケージがそのようなものを定義しているときは、それをbinという名前のディレクトリに収容する。

何時かの時点でpubは読者のシステム・パスにそのディレクトリを自動的に付加して、これらのスクリプトが簡単に呼び出せるようになろう（訳者注：IDEではそうなっている）。

テスト

Tests#
enchilada/
  test/
    enchilada_test.dart
    tortilla_test.dart

まともなパッケージはテストを持っていなければならない。pubの場合は、その規約はそれらをtestディレクトリ（あるいはそのほうが良ければその中の何らかのディレクトリ）に置き、それらのファイル名の終わりに_testが付くということである。

一般的にこれらはunittestパッケージを使っているが、その他のテストのためのシステムを使うことも自由である。

ドキュメンテーション (Documentation)

enchilada/
  doc/
   getting_started.md

コードとテストを作ったら次に行うことは、良いドキュメンテーションで自分の開発物の影響力を最大化することである。ドキュメントはdocという名前のディレクトリ内に置かれる。現時点ではこのなかの構成や書式に関する指針は無い。好みのマークアップ書式を使ってドキュメントを作成するとよい。

このディレクトリは単にIntelliJ上でdartdocを使って自分のソース・コードから自動的に生成されたドキュメントを収容するだけではいけない。それはそのパッケージ内で既にそのコードから直接得られるものなので、単にそれをここに置くのは冗長である。そうではなくて、このディレクトリは生成されたAPI参照に加えてチュートリアル、ガイド、およびその他の作成者が自分で書いたドキュメンテーションのためのものである。

サンプル (Examples)

enchilada/
  example/
    lunch.dart

この時点で皆さんは恵まれた機会を持とうとしている。コード、テスト、ドキュメント、それ以外にユーザは何を望むだろうか？無論それは皆さんのパッケージを使ったスタンドアロンのサンプル・プログラムである。これらのプログラムはexampleディレクトリの中に置かれる。そのサンプルが複雑で複数のファイルが使われているときは、各サンプルのためにディレクトリを作ることを検討されたい。そうでないときは、各々をexapleの中に置くことができる。

自分自身のパッケージ内からファイルをインポートするのにpackage:を使う際に検討する場所としてここは重要である。package:を使うことで自分のパッケージ内のサンプル・コードは自分のパッケージ外で使われるコードとまさしく同じにすることができる。

内部ツールとスクリプト (Internal tools and scripts)

enchilada/
  tool/
    generate_docs.dart

枯れたパッケージではしばしば小規模なヘルパ・スクリプトとプログラムを有しており、これによりそのパッケージ自身を開発中にそれを実行できるようにしている。テスト・ランナ、ドキュメンテーション生成ツールその他のオートメーション・ツールの類である。

binのなかのスクリプトとは違って、これらはそのパッケージの外部ユーザの為のものではない。これらはtoolという名前のディレクトリに置かれる。

Pubspecの書式 (Pubspec Format)

＊＊＊以下は基本的にGoogleのPubspec Formatというドキュメントの翻訳である＊＊＊

各pubパッケージはその依存物たち (dependencies)を指定できるような何らかのメタデータが必要である。他の人たちと共有できるpubパッケージはまた、そのユーザたちがこれらを発見できるような何らかのその他の情報を用意してやる必要がある。このメタデータの総てがこのパッケージのpubspec：即ちYAML言語で書かれたpubspec.yamlというファイル名のファイルに収容される。

対応しているフィールド (Supported fields)

pubspecには以下のフィールドを記入できる：

name

各パッケージごとに必要

version

Pubサイトでホストされるパッケージには必要

description

Pubサイトでホストされるパッケージには必要

authorまたはauthors

オプショナル

homepage

オプショナル。このパッケージのホームページ（またはgitのようなソース・コードのリポジトリ）の場所のURL

repository

オプショナル。このパッケージのgitのようなソース・コードのリポジトリの場所のURL

issue_tracker

オプショナル。このパッケージの問題追跡の場所のURL

documentation

オプショナル。自動的にドキュメンテーションを生成のに使われる

dependencies

自分のパッケージが依存物を使っていないときは省略可

dev_dependencies

自分のパッケージがdev依存物を使っていないときは省略可

dependency_overrides

どの依存物もオーバライドする必要がないときは省略可

environment

Dart 2では必要

executables

オプショナル。自分のPATH上にあるパッケージの実行可能物を置くのに使われる

publish_to

オプショナル。あるパッケージをどこにパブリッシュするかを指定する

Pubはそれ以外の総てのフィールドを無視する。

Flutterに関する注意：Flutterアプリの為のpubspecは資産管理の為の幾つかのフィールをを持てる。

シンプルではあるが完全なpubuspecは以下のようなものになる：

name: newtify
version: 1.2.3
description: >-
  Have you been turned into a newt?  Would you like to be?
  This package can help. It has all of the
  newt-transmogrification functionality you have been looking
  for.
author: Natalie Weizenbaum <nweiz@google.com>
homepage: https://example-pet-store.com/newtify
documentation: https://example-pet-store.com/newtify/docs
environment:
  sdk: '>=2.0.0 <3.0.0'
dependencies:
  efts: ^2.0.4
  transmogrify: ^0.4.0
dev_dependencies:
  test: '>=0.6.0 <0.12.0'

以下各フィールド毎に詳細に説明する。

name

各パッケージには名前が必要である。これは他のパッケージが自分のパッケージを参照するか、そしてそれをパブリッシュしたら世界中でどう見えるかということである。

名前は総て小文字で分離用のアンダスコア(_)で構成される（例えばjust_like_this）。ベーシックなラテン文字とアラビア数字のみを使う：[a-z0-9_]。また、その名前が確実に有効なDartの識別子であるようにする。即ち数字で始まったりDartのキーワードであったりしてはいけない。

明確で簡潔で且つ既に使われていない名前を選択する。Pubのサイトにあるパッケージたちの名前を検索して、自分の名前が他の誰も使っていないことを確認することが推奨される。

version

各パッケージはバージョンを持つ。Pubのサイトで自分のパッケージをホストするにはバージョン番号が必要であるが、ローカルだけで使われるものでは省略可能である。これが省略されていると、そのパッケージは暗示的に0.0.0というバージョンが付される。

バージョン付けはどんどんバージョン・アップできるようにしつつもそのコードを再利用するには必要である。バージョン番号は0.2.43といったようにドットで分離された3個の数字である。これはまたオプショナルとしてbuild (+hotfix.oopsie)またはpre-release (-alpha.12)のサフィックスを持てる。

自分のパッケージをパブリッシュするたびに、特定のバージョンをパブリッシュすることになる。一旦それが終わったら、それは密封されたと考えられたい：もはやそれに触れることはできない。更に変更をしたいときには新しいバージョンが必要である。

バージョンを選択する際は、semantic versioningに従うこと。

description

これは自分のパーソナルなパッケージの場合はオプショナルだが、そのパッケージをパブリッシュするつもりなら、そのパッケージの記述(description)を用意してやらねばならない。これは比較的短いもの（数フレーズ）、おそらくパラグラフ全体のもので、自分のパッケージがカジュアルな読者に対し知りたいものであるよう告げるようにする。

この記述は自分のパッケージの宣伝文句だと考えること。ユーザはパッケージを検索するときにこれを見る。これはシンプルなテキストで、マークダウンやHTMLであってはならない。READMEはそのためにある。

author/authors

自分のパッケージにauthor(s)を記述するフィールドを使ってコンタクト情報を提供することが推奨される。自分のパッケージの作成者がひとりのときはauthorを使い、複数の場合はauthorsを使いYAMLリストでそれを記述する。各作成者は単一の名前(Natalie Weizenbaum)または名前とメール・アドレス(Natalie Weizenbaum <nweiz@google.com>)で記述する。例えば：

authors:
- Natalie Weizenbaum <nweiz@google.com>
- Bob Nystrom <rnystrom@google.com>

もし誰かが自分のパッケージをPubサイトにアップロードすると、自分のアドレスは公開される。

homepage

これは自分のパッケージの為のウェブサイトを指すURLであること。ホストされたパッケージの場合は、このURLはそのパッケージのページからリンクされる。homepageはオプショナルではあるが、それまたはrepository（或いは双方）を記して頂きたい。ユーザたちは自分のパッケージが何処から来ているのかを理解する助けとなる。

repository

このオプショナルなrepositoryフィールドは自分のパッケージのソース・コード・リポジトリのURLを記す--例えばhttps://github.com/<user>/<repository>。自分のパッケージをPubのサイトにパブリッシュすると、自分のパッケージのページにはそのリポジトリのURLが表示される。repositoryはオプショナルではあるが、それまたはhomepage（或いは双方）を記して頂きたい。ユーザたちは自分のパッケージが何処から来ているのかを理解する助けとなる。

issue_tracker

このオプショナルな issue_trackerフィールドにはそのパッケージの問題追跡（既存のバグが見れ、また新しいバグが登録できる）のURLを記す。Pubサイトはこのフィールドの値を使って各パッケージの問題追跡へのリンクを表示する。もしissue_trackerフィールドがないもののrepositoryのフィールドが存在しGitHubを指しているときは、Pubはデフォルトの問題追跡(https://github.com/<user>/<repository>/issues)を使う。

documentation

一部のパッケージはメインのホームページとは別のドキュメンテーションをホストするサイトを持っている場合がある。自分のパッケージがそのような場合は、そのURLを持ったdocumentation:フィールドを付加できる。その場合は自分のページ上でそこへのリンクが表示される。

documentation:のフィールドがブランクのままだと、ドキュメンテーションは自動的に生成され、そこへのリンクはPubのサイトにリンクされる。

dependencies

そもそもdependencies（依存物たち）こそがpubspecが存在する理由である。ここでは自分のパッケージが動作するに必要とする各パッケージをリストする。

dependenciesはふたつのタイプに分けられる。通常の依存物たちはdependencies:の下にリストされる：これらは自分のパッケージを使う誰もが必要とするパッケージである。このパッケージ自身の開発段階でのみ必要な依存物たちは dev_dependencies：の下にリストされる。

注意：ウェブ・アプリの開発ではコマンド行ツールのwebdev buildあるいはIDEでのBuildコマンドはdev_dependencies：を参照しているので、このフィールドは必須である

開発段階中にある依存物を一時的にオーバライドしなければならない場合があるかもしれない。その場合は dependency_overridesを使ってそうする。

より詳細は Pub Dependenciesを参考のこと。

なおdependenciesのバージョン指定記述には次のようなキャレット(^)を使った構文が良く使われるが、あまり推奨できない構文である：

dependencies:
path: ^1.3.0
collection: ^1.1.0
string_scanner: ^0.1.2

例えば^1.2.3 は'>=1.2.3 <2.0.0'と等価であり、^0.1.2 は'>=0.1.2 <0.2.0'と等価である。

Executables

パッケージにはコマンド行から直接実行できる実行物としてのひとつ或いはそれ以上のスクリプトを公開することもあろう。あるスクリプトを公に使えるようにするには、このexecutablesフィールドの下にそれをリストする。エントリはキー/値のペアでリストする：

<name-of-executable>: <Dart-script-from-bin>

例えば、以下のpubspecエントリは2つのスクリプトをリストしている：

executables:
  polymer-new-element: new_element
  useful-script:

一旦このパッケージがpub global activateを使って活性化されたら、 polymer-new-elementとタイプすると bin/new_element.dartを実行する。 useful-scriptとタイプすると bin/useful-script.dartを実行する。この値を指定しないときは、それはこのキーから推論される。

更なる情報はpub globalを参照のこと。

publish_to

デフォルトはPubサイトである。noneと指定すると、パブリッシュできなくなる。この設定はパブリッシュするのにカスタムのpubパッケージ・サーバを指定するのに使われる。

publish_to: none

SDK制約

パッケージは依存物たちのどのバージョンがそれをサポートするかを指定できるが、パッケージには別の暗示的な依存物：即ちDartのプラットホームそれ自体を持っている。Dartのプラットホームは時とともに進化しており、パッケージによってはこのプラットホームのあるバージョンでのみ動くこともあり得る。

例えば、以下の制約は2.0.0版またはそれ以上のどのDart 2 SDKでもこのパッケージは動作すると言っている：

environment:
  sdk: '>=2.0.0 <3.0.0'

注意：SDK制約にはキャレット構文(^)は使ってはいけない。また上限制約(<3.0.0, 通常)を入れること。詳細はDart 2のページを読まれたい。

Flutter SDKの制約

Dart 1.19.0の時点では、pubは以下のenvironment:フィールドのもとでのFlutter SDK制約に対応している。

environment:
  sdk: '>=1.19.0 <3.0.0'
  flutter: ^0.1.2

flutter実行物のコンテキスト内でpubが走っており、Flutter SDKのバージョン・ファイルが与えられたversion制約に合致するときに限り Flutter SDK制約は満足される。そうでないときは、このパッケージは選択されない。

Flutter SDK制約があるパッケージをパブリッシュする際は少なくとも1.19.0の最小バージョンの Dart SDK制約を指定し、それよりも古いバージョンのpubはFlutterが必要なパッケージを偶発的にインストールしないようにしなければならない。

自分のライブラリ・パッケージを作る

本節はGoogleの「ライブラリ・パッケージを作る」という資料に基づいている。

この章ではライブラリ・パッケージをどのように作成するかを説明するが、アプリケーション・パッケージも基本的には同じであるが「Install Shared Packages」に更に詳しく記されている。

ライブラリ・パッケージの構成要素

以下の例では最もシンプルなライブラリ・パッケージのレイアウトを示している：

root directory/
    lib/
        file.dart
    pubspec.yaml

root directoryはlib/file.dart及びpubspec.yamlの2つのファイルを含んでいる。

あるライブラリの最小要求事項は：

pubpecファイル

あるライブラリの為のpubspec.yamlファイルはアプリケーション・パッケージと同じであるーーそのパッケージがライブラリであることを示す特別の指定はない
libディレクトリ

予想されているかも知れないが、ライブラリのコードはlibディレクトリの下に置かれ、他のパッケージたちに対しパブリックである。必要ならlibの下に任意の階層を持たせても良い。慣例として実装コードは lib/srcの下に置かれる。パッケージのコードの多くは内部実装ライブラリ(internal implementation libraries)たちであって、そのパッケージ自身によってインポートされ使われるべきものである。それらのファイルはsrcと呼ばれるlibのサブディレクトリ内部に置かれる。srcのなかにサブディレクトリを作ることもそれが有意義なら構わない。 lib/srcはプライベートと考えられる；他のパッケージたちは絶対src/....をインポートする必要はない。但しlib/src のなかのAPIたちをパブリックにする為に、lib/srcファイルたちを直接libの下にあるファイルからエクスポートすることは可能である。

注意：libraryディレクティブが指定されていないときは、そのパスとファイル名に基づいて各ライブラリの為の固有なタグが生成される。従って、自分がライブラリ・レベルのドキュメンテーションを作る経過である場合を除いて、自分のコードからlibraryディレクティブを外すことを提案する。

ライブラリ・パッケージを構成する

ミニ・ライブラリと称される小さな個別のライブラリたちを作る際は、ライブラリ・パッケージは最も維持、拡張、及びテストが簡単になる手段である。二つのクラスが密に結びついている状況でない限り、殆どの場合は各クラスがそれ自身ミニ・ライブラリであるべきである。

注意：あるライブラリを複数のDartファイルに分割することを許すpart指令を耳にしたことがあろうかと思う。我々はpartの使用を避け、代わりにミニ・ライブラリたちを作ることを推奨している。

libの下に直接“メイン”のライブラリ・ファイルのlib/<package-name>.dartを作り、パブリックなAPIたちの総てをエクスポートするようにする。これによりユーザは単一のファイルをインポートするだけでそのライブラリの機能の総てを取得できるようになる。

このlibディレクトリはまた他のインポートできない non-srcのライブラリも含み得る。例えば、多分読者のメインのライブラリがプラットホームたちにわたって機能するが、 dart:ioまたは dart:htmlに依存する分離したライブラリたちを作る場合もある。メインのライブラリがそうでないのに、一部のパッケージはプレフィックスつきでインポートされることを意図した別々のライブラリたちを持つこともある。

現実の世界のパッケージ：shelfの構成を眺めてみよう。このshelfパッケージ（リポジトリ及びpub）はDartを使ってウェブ・サーバを作る簡便な手段を提供するもので、Dartライブラリ・パッケージで一般的に使われる構成となっている。

Shelf root directory/
    example/
        example_server.dart
    lib/
        src/
            handlers/
                logger.dart
            body.dart
            cascade.dart
            …
            util.dart
        shelf.dart
        shelf_io.dart
    test/
        a variety of tests
    tool/
        travis.sh

直接libの下のメインのライブラリ・ファイルであるshelf.dartがlib/srcからの幾つかのファイルをエクスポートしている：

export 'src/cascade.dart';
export 'src/handler.dart';
export 'src/hijack_exception.dart';
export 'src/middleware.dart';
export 'src/middleware/add_chunked_encoding.dart';
export 'src/middleware/logger.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オブジェクトたちを取り扱う。

ウェブ・アプリでのポイント： dartdevcで開発中にパフォーマンスを最大化するには、/libの下のどこかに置く代わりに実装ファイルたちを/lib/srcの下に置くようにする。また、package:package_name/src/....のインポートを避ける。

ライブラリ・ファイルのインポート

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

import 'package:utilities/utilities.dart';

双方のファイルがlibの内側にあるとき、或いは双方のファイルがlibの外部にあるときは、相対パスを使ってのライブラリのインポートができる。しかしながら、libの内側あるいは外側に届くファイルをインポートするときはpackage:を使わねばならない。疑わしい場合は、package:を使う。これは総ての場合で機能する。

以下の図は lib/foo/a.dartをlib及びwebからどのようにインポートするかを示している：

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

付加的ファイルたちを用意する

良く設計されたライブラリ・パッケージはテストし易くなっている。我々は testパッケージを使ったテストを書き、このパッケージのトップのtestディレクトリにそのテスト・コードを置くことを推奨する。

パブリックな消費を意図した何らかのコマンド行のツールを作る際は、パブリックなbinディレクトリ内にそれらを置く。あるツールをコマンド行からpub global activate を使って走らせることを可能とする。pubspecのexecutableの区間にこのツールをリストすることで、ユーザはpub global runを呼ぶことなく直接それを走らせることができるようになる。

このライブラリの使い方の例を含めることができればユーザの助けになる。これはこのパッケージのトップのexampleディレクトリに入る。

開発中に作成するパブリックの使用の為ではない実行可能物はtoolディレクトリ内に収容する。

README及びCHANGELOGのようなPubサイトに自分のライブラリをパブリッシュする際に必要なファイルたちは「パッケージのパブリッシュ」の節に記されている。また「Pubパッケージのレイアウト規約」はどのようにパッケージのレイアウト構造をつくるかを解説している。

ライブラリのドキュメンテーション

dartdocツールを使って自分のライブラリのAPIドキュメントを生成できる。 Dartdocはソース・コードを解析する際///構文を使ったドキュメンテーション・コメントを探す：

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

生成されたdocsのサンプルとしては、shelfのドキュメンテーションを見て頂きたい。

注意：生成されたdocsのなかに何らかのライブラリ・レベルのドキュメンテーションを含めるには、library ディレクティブを指定しなければならない。 issue 1082を参照のこと。

オープン・ソースのライブラリの配布

読者のライブラリがオープン・ソースのものなら、それをPubのサイトで共有することをお勧めする。そのライブラリをパブリッシュまたは更新するときは pub publishをつかう。このコマンドは読者のパッケージをアップロードし、そのページを作成または更新する。例として、shelfパッケージのページを見て頂きたい。パブリッシュにあたってどう自分のパッケージを準備するかの詳細は次節の「パブリッシング手順」に記されている。

Pubのサイトは単に読者のパッケージをホストするだけではなく、そのパッケージのAPI参照docsを生成しホストする。例えばshelfパッケージのAPI docsを見ると、最新の生成されたdocsのリンクはそのパッケジのAboutのボックスにある。これまでのバージョンのdocsへのリンクはこのパッケージのページの Versionsタブの中にある。

pubのサイト上で自分のパッケージのAPI docsが良くできているようにするには以下のステップに従うこと：

自分のパッケージをパブリッシュする前に、自分のdocsが正しく生成され、予想したとおりになっているかを確認するのに dartdocツールを走らせる
自分のパッケージをパブリッシュしたら、 Versionsタブをチェックしてdocsが成功裏に生成されていることを確認する
もしそのdocsが全く生成されていないときは、dartdoc出力を見るのにVersionsタブの中のfailedをクリックする

参考資料

ライブラリ・パッケージに関してもっと詳しく学ぶには、以下の資料を使用する：

ライブラリ・ファイルの使用法は言語編の「ライブラリと可視性」
Pubのドキュメンテーションは有用であり、特に「Pubパッケージのレイアウト規約」
What Not to Commitはソース・コードのリポジトリでなにを含めてはいけないかが記されている
dart-lang組織のもとでの新しいライブラリ・パッケージではベスト・プラクティスを示す傾向がある。以下のサンプルの学習をお勧めする：dart_style, path, shelf, source_gen,及び test.

パブリッシング手順

この節では自分が作成したパッケージをどのように pub publishを使ってPubにパブリッシュするかをより具体的に説明する。

Pubは単に他の人たちのパッケージを使用するためのものではない。これは読者のパッケージを世界中の人たちと共有できるようにする。もし読者が有用なプロジェクトに携わっていて、他の人が使えるようにしたいと思うときは pub publishコマンドを使うことを推奨する。

注：Pubのサイト以外の場所にパブリッシュしたいとき、あるいはそこ以外のへのパブリケーションをさせないようにするには、pubspecで定められている publish_toフィールドを使用する。

準備

パッケージのパブリッシングにあたって、「pubspecの書式」と「パッケージのレイアウト規約」に準拠することが重要である。これらの一部は他の人たちが自分のパッケージを使えるようにするために必要なものである。それ以外はユーザが理解しまたそのパッケージで作業し易くするのに寄与する助言でもある。いずれの場合でもpubはどう変更すればDartのエコシステムのなかで読者のパッケージがより寄与できるようにするのに寄与するかを指摘することで読者を助けようと試みる。パッケージのアップロードにあたっての幾つかの必要事項がある：

オープン・ソースのライセンスが記されているライセンス・ファイル（LICENSE、COPYING、或いはその種の名前のファイル）が含まれていなければならない。我々はBSDライセンスを推奨するが、これはDart自身が使っているものである。また自分のパッケージと一部としてアップロードしたなにかを再配布する法的権利も読者は持っていなければならない。
そのパッケージはgzip圧縮後で10MB以下のサイズでなければならない。もし大きすぎるサイズである場合は、複数のパッケージに分割するか、含まれているリソースやサンプルの数を減らすことを検討する。

そのパッケージはホストされた依存物たち以外の依存物を含めてはいけない。Gitのリポジトリの依存物は許されるが、そうしないことを強調したい。Dartを使っている誰もがGitをインストールしている訳ではなく、またGitの依存物たちはホストされた依存物に適用されているバージョン解決をサポートしていない。

読者のGoogleのアカウントに結び付けられているメール・アドレスが、読者がアップロードした他のパッケージとともにPubサイトで表示されてしまうことに気を付けて頂きたい。

自分のパッケージをパブリッシュする

最初に予行演習(dry run)を試みることができる：

$ pub publish --dry-run

Pubはそのパッケージが pubspec書式とパッケージ・レイアウト規約に従っていることを確認するためのチェックを実施するので、次にそれをPubのサイトにアップロードする。Pubはまたパブリッシュする予定のファイルの総てを示してくれる。以下は transmogrify（化けさせる）という名前のパッケージをパブリッシュしている例である：

Publishing transmogrify 1.0.0
    .gitignore
    CHANGELOG.md
    README.md
    lib
        transmogrify.dart
        src
            transmogrifier.dart
            transmogrification.dart
    pubspec.yaml
    test
        transmogrify_test.dart
Package has 0 warnings.

自分のパッケージがパブリッシュ可能になったら、--dry-run引数を外す：

$ pub publish

自分のパッケージが成功裏にPubサイトにアップロードされた後は、どのPubのユーザもそれをダウンロードする、或いはそのユーザのプロジェクトで依存したり出来るようになる。例えば、自分のバージョン 1.0.0のtransmogrifyパッケージをパブリッシュ

したら、別のDartのデベロッパがそれを彼の pubspec.yamlのなかでそれを依存物として追加できる：

dependencies:
transmogrify: ^1.0.0

どんなファイルがパブリッシュされるのか？

以下の例外を除いた総てのファイルがパブリッシュされたパッケージに含められる：」

packagesディレクトリ
自分のパッケージのロックファイル（例：pubspec.lock）
Gitを使っていない場合は、総ての隠しファイル（即ちファイル名が . で始まるファイル）
Gitを使っているときは、自分の.gitignoreファイルで無視されている総てのファイル

必ず自分が含めて欲しくない入るは削除する（あるいは.gitignoreにそのファイル名を追加する）こと。 pub publishは自分のパッケージをアップロードする前にパブリッシュされようとしている総てのファイルをリストするので、自分のアップロードを完了させる前にそのリストを注意深く調べること。

著者対アップローダ

pubspec.yamlファイルの中でリストされたパッケージの著者たちは、そのパッケージをパブリッシュするのを認可された人たちのリストは異なる。何らかのパッケージの最初のバージョンのパブリッシャが誰であろうと、自動的にそのパッケージのそれ以降のバージョンをアップロードするために認可された最初で唯一の人物となる。アップロードするバージョンに対し他の人を許すか許さないかは pub uploaderコマンドを使う。

注意：アップローダはGoogleのアカウントで識別されるので、GmailまたはGoogle Appsの電子メール・アドレスを使用する。

オプション

総てのpubコマンドに適用されるオプションたちに関しては Global optionsに記されている。

なおpubに関する問題は Troubleshooting Pubに記されている。