pubspec.yamlの書き方

pubspec.yamlとは

依存関係を記載したファイル。
プロジェクトに関するメタデータも記載する。

pubspec.lockとは

pubspec.yamlを元にして生成される。
実際にインストールしたライブラリのバージョンが記載される。
プロジェクトで使っているバージョンはyamlファイルではなく、lockファイルに記載されているものになる。

生成されたlockファイルを見てみると最初の2行には以下のことが書かれている。

# Generated by pub
# See https://dart.dev/tools/pub/glossary#lockfile

公式サイトを見てみるとpubコマンドによってlockファイルが生成されることが分かる。

pub get、、pub upgradeまたはを実行すると、pub によってロックファイルが自動的に生成されますpub downgrade。pub には、将来の解決時> にチェックする各パッケージのコンテンツ ハッシュが含まれています。

lockファイルは自動生成されるため、自分で変更を行わないこと。

https://dart.dev/tools/pub/versioning#lockfiles

pubspec.yamlに記載される項目について

pubspec.yamlに記載されている項目はどんなものがあるのかそれぞれの項目について見ていく。

Dartの項目

• name
• version
• description
• homepage
• repository
• issue_tracker
• documentation
• dependencies
• dev_dependencies
• dependency_overrides
• environment
• executables
• platforms
• publish_to
• funding
• false_secrets
• screenshots
• topics
• ignored_advisories

name

すべてのパッケージには名前が必要です。名前は、他のパッケージがあなたのパッケージを参照する方法であり、公開した場合に世界にどのように表示されるかを表します。
名前はすべて小文字で、単語の区切りにはアンダースコアを使用する必要がありますjust_like_this。基本的なラテン文字とアラビア数字のみを使用してください[a-z0-9_]。また、名前が有効な Dart 識別子であること、つまり数字で始まっていないこと、予約語でないことを確認してください。
明確で簡潔、かつまだ使用されていない名前を選択するようにしてください。pub.devサイトでパッケージをすばやく検索して、他にその名前が使用されていないことを確認することをお勧めします。

version

すべてのパッケージにはバージョンがあります。バージョン番号は pub.dev サイトであなたのパッケージをホストするために必要ですが、 ローカル専用のパッケージでは省略できます。省略した場合、パッケージのバージョンは暗黙のうちに 0.0.0 となります。
バージョン管理は、コードを素早く進化させながら再利用するために必要です。バージョン番号は、0.2.43 のようにドットで区切られた3つの数字です。また、ビルド（+1、+2、+hotfix.opsie）やプレリリース（-dev.4、-alpha.12、-beta.7、-rc.5）の接尾辞をつけることもできます。
パッケージを公開するたびに、特定のバージョンで公開することになります。これが完了したら、そのパッケージは密閉されたと考えてください。それ以上変更を加えるには、新しいバージョンが必要になります。
バージョンを選択するときは、セマンティック・バージョニングに従ってください。

description

これはあなた自身の個人的なパッケージでは任意ですが、あなたのパッケージを出版するつもりなら、説明文を提供しなければなりません。説明文は60字から180字の比較的短いもので、カジュアルな読者があなたのパッケージについて知りたいと思うことを伝えるものでなければなりません。
説明文はあなたのパッケージの売り込み文句だと考えてください。ユーザーはパッケージを探すときにこの説明文を目にします。説明文はプレーンテキストです: マークダウンやHTMLは使いません。

homepage

これはパッケージのウェブサイトを指すURLでなければなりません。ホストされたパッケージの場合、このURLはパッケージのページからリンクされます。ホームページの提供は任意ですが、ホームページかリポジトリ (またはその両方) を提供してください。ユーザがあなたのパッケージがどこから来たのかを理解するのに役立ちます。

repository

オプションの repository フィールドには、パッケージのソースコードリポジトリの URL を入力してください (例: https://github.com/<user>/<repository>)。pub.dev サイトにパッケージを公開する場合、パッケージのページにはリポジトリの URL が表示されます。リポジトリの提供は任意ですが、リポジトリかホームページ (またはその両方) を提供してください。ユーザがあなたのパッケージがどこから来たのかを理解するのに役立ちます。

issue_tracker

オプションの issue_tracker フィールドには、パッケージの課題追跡ツールの URL を指定します。pub.dev サイトは、このフィールドの値を使用して、各パッケージの課題追跡システムへのリンクを表示しようとします。issue_tracker がなく、repository が存在し GitHub を指している場合、pub.dev サイトはデフォルトの課題追跡システム (https://github.com/<user>/<repository>/issues) を使用します。

documentation

パッケージの中には、メインのホームページや Pub が生成する API リファレンスとは別に、ドキュメントをホストするサイトを持っているものがあります。パッケージに追加のドキュメントがある場合は、その URL を記述した documentation: フィールドを追加してください。

dependencies

dev_dependencies

dependency_overrides

依存関係は pubspec の存在意義です。このセクションでは、あなたのパッケージが動作するために必要な各パッケージを列挙します。
依存関係には 2 つのタイプがあります。通常の依存パッケージは dependencies:- の下にリストされます。これらは、あなたのパッケージを使用する誰もが必要とするパッケージです。パッケージの開発フェーズでのみ必要とされる依存関係は、 dev_dependencies にリストされます。
開発プロセス中、依存関係を一時的に上書きする必要があるかもしれません。その場合は dependency_overrides を使います。
詳しくは、パッケージの依存関係を参照してください。

environment

パッケージは、その依存関係がどのバージョンに対応しているかを示すことができますが、パッケージには Dart プラットフォーム自体という別の暗黙の依存関係があります。Dart プラットフォームは時間とともに進化し、パッケージはプラットフォームの特定のバージョンでのみ動作する可能性があります。
パッケージは、SDK制約を使用してそれらのバージョンを指定できます。この制約は、pubspec内の別のトップレベル環境フィールド内にあり、依存関係と同じバージョン制約構文を使用します。

executables

パッケージは、1つ以上のスクリプトをコマンドラインから直接実行できる実行可能ファイルとして公開することができます。スクリプトを一般に公開するには、executables フィールドにそのスクリプトを列挙します。項目はキーと値のペアでリストされます

platforms

パッケージを公開すると、pub.dev はパッケージがサポートするプラットフォームを自動的に検出します。このプラットフォーム・サポート・リストが正しくない場合は、platforms を使ってパッケージがサポートするプラットフォームを明示的に宣言してください。
例えば、以下の platforms エントリを使用すると、pub.dev はそのパッケージが Android、iOS、Linux、macOS、Web、および Windows をサポートしているとリストします

publish_to

デフォルトではpub.devサイトを使用します。パッケージがパブリッシュされないようにするには、none を指定します。この設定は、発行するカスタム pub パッケージ・サーバを指定するために使用できます。

funding

パッケージ作者はfundingプロパティを使って、ユーザがそのパッケージの開発資金を援助する方法についての情報を提供するURLのリストを指定することができます。

false_secrets

パッケージを公開しようとすると、pub は秘密の認証情報、API キー、暗号キーの漏えいの可能性を検索します。pubが公開されるファイルから漏洩の可能性を検出した場合、pubは警告を発し、パッケージの公開を拒否します。
リーク検出は完璧ではありません。誤検知を避けるために、pubspecのfalse_secretsの下にgitignoreパターンを使って許可リストを作成することで、特定のファイルのリークを検索しないようにpubに指示することができます。
例えば、以下のエントリは、lib/src/hardcoded_api_key.dart ファイルと test/localhost_certificates/ ディレクトリ内のすべての .pem ファイルのリークを検索しないようにします。

screenshots

パッケージは、pub.dev ページに表示されるスクリーンショットを使って、ウィジェットやその他のビジュアル要素を紹介することができます。パッケージに表示するスクリーンショットを指定するには、screenshots フィールドを使用します。
パッケージはscreenshotsフィールドに最大10枚のスクリーンショットを掲載できます。このセクションにはロゴやその他のブランドイメージを含めないでください。各スクリーンショットには説明とパスが1つずつ含まれます。説明には、160文字以内でスクリーンショットの内容を説明します。

topics

パッケージ作者は topics フィールドを使ってパッケージを分類できます。トピックは、pub.dev のフィルタによる検索時に、発見しやすくするために使用できます。pub.dev は検索結果だけでなくパッケージページにもトピックを表示します。
このフィールドは名前のリストで構成されます。

ignored_advisories

パッケージにセキュリティ勧告の影響を受ける依存関係がある場合、pub は依存関係の解決中にその勧告について警告します。パッケージの作者は ignored_advisories フィールドを、そのパッケージには関係ない、トリガーされたアドバイザリの許可リストとして使うことができます。
アドバイザリに関する警告を抑制するには、ignored_advisories リストにアドバイザリの識別子を追加してください。

Flutterの項目

Flutter専用の設定もpubspec.yamlに記載する。

• flutter
  • uses-material-design
  • generate
  • assets
  • fonts

基本的にはflutter項目の中に記載していく。
以下はflutterプロジェクトを作成したときのpubspec.yaml内にあるflutter項目のより詳細な設定内容になります。

flutter:

  uses-material-design: true # Required if you use the Material icon font

  generate: true # Enables generation of localized strings from arb files

  assets:  # Lists assets, such as image files
    - images/a_dot_burr.jpeg
    - images/a_dot_ham.jpeg

  fonts:              # Required if your app uses custom fonts
    - family: Schyler
      fonts:
        - asset: fonts/Schyler-Regular.ttf
        - asset: fonts/Schyler-Italic.ttf
          style: italic
    - family: Trajan Pro
      fonts:
        - asset: fonts/TrajanPro.ttf
        - asset: fonts/TrajanPro_Bold.ttf
          weight: 700

uses-material-design

マテリアルアイコンフォントを使用する場合は必須。

https://qiita.com/Kurunp/items/76e13bfd03fd3dec1e27#uses-material-designフィールド

generate

arbファイルからローカライズされた文字列を生成できるようにする。

assets

画像ファイルなどのアセットのリスト

fonts

アプリがカスタムフォントを使用する場合は必須

パッケージの項目

DartとFlutterの項目以外にも使用するライブラリによってはpubspec.yamlに設定を記載することもある。
よくプロジェクトで使われるようなライブラリを紹介します。

• flutter_icons
• flutter_native_splash
• flutter_gen

flutter_icons（flutter_launcher_icons）

flutter_launcher_iconsライブラリの設定
https://pub.dev/packages/flutter_launcher_icons

0.13.1からはflutter_iconsだけでなく、flutter_launcher_iconsという名前で設定できるようになったみたい。
https://pub.dev/packages/flutter_launcher_icons/changelog#0131-15th-april-2023

flutter_icons:
    # 省略

# 0.13.1からは以下の書き方でもOK
flutter_launcher_icons:
    # 省略

詳しい設定は公式サイトを見てください。
https://pub.dev/packages/flutter_launcher_icons#mag-attributes
https://github.com/fluttercommunity/flutter_launcher_icons/blob/master/example/default_example/pubspec.yaml

flutter_native_splash

flutter_native_splashライブラリの設定
https://pub.dev/packages/flutter_native_splash

flutter_native_splash:
    # 省略

詳しい設定は公式サイトを見てください。
https://pub.dev/packages/flutter_native_splash#1-setting-the-splash-screen

flutter_gen

flutter_genライブラリの設定
https://pub.dev/packages/flutter_gen

flutter_gen:
    # 省略

詳しい設定は公式サイトを見てください。
https://pub.dev/packages/flutter_gen#configuration-file
https://github.com/FlutterGen/flutter_gen/blob/main/packages/core/lib/settings/config_default.dart

バージョンの指定方法

pubspec.yamlのdependenciesやdev_dependenciesに
記載するライブラリのバージョン指定方法について見ていきます。

伝統的な構文

キャレット構文でしか書いたことなったですが、記号を使ったバージョン指定もできるのは知らなかったです。

記載例	説明	推奨	注記
any	すべてのバージョン	No	空のバージョン制約の明示的な宣言として機能します。
記載無し	すべてのバージョン	No	anyと同様。
1.2.3	指定されたバージョンのみ	No	パッケージを使用するアプリに追加の制限が課されるため、パッケージの採用が制限されます。
>=1.2.3	指定されたバージョン以降	Yes
>1.2.3	指定されたバージョンより新しいバージョン	No
<=1.2.3	指定されたバージョンまたはそれ以前のバージョン	No
<1.2.3	指定されたバージョンより前のバージョン	No	パッケージで動作しない上限バージョンがわかっている場合にこれを使用します。このバージョンは、互換性を破る変更を導入する最初のバージョンである可能性があります。

制限を組み合わせることで、バージョン範囲を指定することもできます。
'>=1.2.3 <2.0.0'と記載することで2.0.0自体を除いて、1.2.3から2.0.0までの任意のバージョンにすることができます。

記号を使ってバージョン指定する場合は制約文字列全体を引用符で囲む必要があります。
これはYAMLがこの文字をYAMLの構文として解釈するのを防ぎます。たとえば、>=1.2.3 <2.0.0を使用しないでください。
'>=1.2.3 <2.0.0'または^1.2.3を使います。

シングルクォートでもダブルクォートでもどちらでも良いみたいです。

dependencies:
  go_router: '>=2.5.0 <3.0.0'
  shared_preferences: ">=2.0.0 <3.0.0"

記号で囲まないとYAMLの構文として解析できず、エラーになります。

dependencies:
  url_launcher: >=2.5.0 <3.0.0

Error on line 39, column 18: Expected comment or line break.
   ╷
39 │   url_launcher: >=2.5.0 <3.0.0
   │                  ^
   ╵
Please correct the pubspec.yaml file at

キャレット構文

キャレット構文は、バージョン制約を簡潔に表現するための記法です。
Dart はセマンティック・バージョニングを採用しているので、パッケージのバージョンが 1.0 以降の場合は次のメジャー・バージョン、1.0 より前の場合は次のマイナー・バージョンとなります。
伝統的な構文との比較をしてみたいと思います。

メジャーバージョン値	範囲	キャレット構文	伝統的な構文
>=1.0	次のメジャー	^1.3.0	'>=1.3.0 <2.0.0'
<1.0	次のマイナー	^0.1.2	'>=0.1.2 <0.2.0'

書き方は以下のようになります。バージョン指定が簡単に書けるようになったと思います。

dependencies:
  # Covers all versions from 1.3.0 to 1.y.z, not including 2.0.0
  path: ^1.3.0
  # Covers all versions from 1.1.0 to 1.y.z, not including 2.0.0
  collection: ^1.1.0
  # Covers all versions from 0.1.2 to 0.1.z, not including 0.2.0
  string_scanner: ^0.1.2

バージョンを固定したい場合は^(キャレット/ハット)記号を無くします。

dependencies:
  path: 1.3.0

どのようにバージョンを指定するのが最適なのか

キャレット構文を使ってバージョンを指定するのが良いと思います。

• バージョン指定が簡潔に書ける。
• メジャーバージョン以外のバージョンアップを自動で行ってくれる。

依存元の指定方法

dependenciesでライブラリを指定する際、以下の方法があります。
それぞれの方法について解説していきます。

• ホストパッケージ
• Gitパッケージ
• パスパッケージ
  

ホストパッケージ

ホストされたパッケージは、pub.dev サイト (または同じ API を使用する別の HTTP サーバー) からダウンロードできるパッケージです。

基本的にライブラリを入れる場合には、pub.devから取得することがほとんどです。
わざわざホストを指定する要件として思いつくのは、外部アクセス制限があるような場合かと思います。

その場合には、ホストを指定することで内部サーバーからライブラリを入れることができます。
事前準備として、pub.devサイトと同様のAPIサーバーを立ち上げる必要があるようです。

hosted設定にサーバーを入れてversionを指定すればライブラリが入れられるみたいです。

dependencies:
  transmogrify:
    hosted: https://some-package-server.com
    version: ^1.4.0

Gitパッケージ

最先端の環境では、まだ正式にリリースされていないパッケージを使用する必要がある場合があります。
パッケージ自体がまだ開発中で、同時に開発されている他のパッケージを使用している可能性があります。
これを簡単にするために、Gitリポジトリに保存されているパッケージに直接依存することができます。

こちらの方法は先ほどのホストパッケージと比較して割と使う指定方法だと思います。
プライバシーマニフェスト対応の時など、pub.devには公開されていないがgithubでは対応が完了している場合に
コミットIDやブランチ名を指定してライブラリを入れる方法です。

githubのリポジトリを指定する

uuid:
    git: https://github.com/Daegalus/dart-uuid

git: の後に該当するリポジトリを指定するとデフォルトブランチの最新コミットが取得できます。

2024-12-15時点のuuidをflutter pub getした場合のログです

uuid 4.5.1 from git https://github.com/Daegalus/dart-uuid at 77c3a3

リポジトリだけを指定する場合はコードが常に新しくなるため、flutter pub get をした時点のコードとなります。
あまり実用的ではないため、後述するコミットIDやタグを指定する方が一般的だと思います。

コミットIDを指定する

コミットIDを指定する方法は先ほどのリポジトリを指定することに加えてコミットIDも合わせて指定する方法になります。

若干さきほどとは指定の方法が異なります。

uuid:
  git: 
    url: https://github.com/Daegalus/dart-uuid
    ref: 615057a4375f45ce35053bdb8e0f8443872a0d06

入ったパッケージも指定したコミットIDになっていることがわかると思います。

uuid 4.5.1 from git https://github.com/Daegalus/dart-uuid at 615057

ブランチ名を指定する

ブランチ名を指定する方法は、パッケージに新機能を追加している時に
常に最新のコードを反映させたいときに使うことがありそうです。

uuid:
  git: 
    url: https://github.com/Daegalus/dart-uuid
    ref: renovate/major-all

uuid 4.5.1 from git https://github.com/Daegalus/dart-uuid at 9df099

ブランチ名を指定すると、指定したブランチの最新コミットのコードが取得できてそうです。

タグ名を指定する

pub.devには公開されていないけど、公開寸前でgithub上には次バージョンとして分かるようなタグをつけられている時に
そのタグを指定することがありそうです。

uuid:
  git: 
    url: https://github.com/Daegalus/dart-uuid
    ref: 4.5.1

uuid 4.5.1 from git https://github.com/Daegalus/dart-uuid at 1af5c2

タグを指定する場合もコードが取得できてそうです。

マルチパッケージ構成から指定する

Flutterプロジェクトはマルチパッケージになっていることがほとんどだと思います。
githubからコミットIDやブランチ名、タグ名を指定する場合にマルチパッケージになっていると
リポジトリが正しく指定されずパッケージのダウンロードに失敗することがあります。

Pub は、パッケージが Git リポジトリのルートにあることを前提としています。
リポジトリ内の別の場所を指定するには、pathリポジトリのルートへの相対パスを指定します。

これはリポジトリのルートにないことが原因です。
その場合にはpath を指定することで正しく設定することができます。

go_router:
  git:
    url: https://github.com/flutter/packages
    path: packages/go_router

go_router 14.6.2 from git https://github.com/flutter/packages at 1f28a6 in packages/go_router

パスを指定することでマルチパッケージに対応することができました。
refを使うことで、コミットIDやブランチ名、タグ名を合わせて指定することもできます。

パスパッケージ

マルチパッケージを指定するときと似ていますが、ローカル上のパッケージを指定することができます。
パッケージの開発時やmelosを使ったマルチパッケージ構成の時に使います。

transmogrify:
  path: /Users/me/transmogrify

フルパスで指定することもできるようですが、基本はマルチパッケージ構成にして、１つ上の階層から該当するパッケージを指定することが多いと思います。

my_package:
  path: ./../my_package

参考にした記事

• https://dart.dev/tools/pub/glossary#lockfile
• https://dart.dev/tools/pub/versioning#lockfiles
• https://dart.dev/tools/pub/pubspec
• https://docs.flutter.dev/tools/pubspec
• https://dart.dev/tools/pub/dependencies
• https://dart.dev/tools/pub/dependencies#version-constraints
• https://dart.dev/tools/pub/versioning#semantic-versions
• https://qiita.com/Kurunp/items/76e13bfd03fd3dec1e27
• https://zenn.dev/flutteruniv_dev/articles/20231214-054646-flutter-pubspec
• https://semver.org/spec/v2.0.0-rc.1.html
• https://dart.dev/tools/pub/custom-package-repositories
• https://www.kernel.org/pub/software/scm/git/docs/user-manual.html#naming-commits
• https://dart.dev/guides/libraries/private-files