[Flutter] pubspec.yaml の文法/チートシート

## 1. はじめに

Flutterのプロジェクト設定ファイルである`pubspec.yaml`の書き方についてまとめています。常に書いたり、更新するようなファイルではないのですぐ忘れてしまいがちのため、備忘録としてすぐに参照して思い出せるようにしたいと思っています。

常時更新していますので、間違いや不明点などあればコメントにてお知らせください。

## 2. YAMLファイル

フォーマットは当然、`YAML`形式です。各フィールドを階層構造で記述する場合、インデントは必ずスペース2にして下さい。


## 3. パッケージ情報

```yaml:例
name: sample_app
description: Flutter music player example application.
publish_to: 'none'
version: 1.0.0+1
```

### nameフィールド

パッケージ名を指定します。Pluginなど第三者にリリースするときには必須で必要ですので、適切な名前を付けるようにしてください。使用可能な文字は`[a-z0-9_]`です。

### descriptionフィールド

このパッケージについての説明を自由に記載します。

### publish_toフィールド

パッケージをPublishする時に必要になるオプションです。通常のアプリケーション開発ではテンプレート通り、`none`を指定しておけば良いですが、Pluginとして[pub.dev](https://pub.dev/)にリリースする場合にはこのオプションは削除する必要があります。

### versionフィールド

パッケージのバーションを指定します。通常、`1.0.24`のように3つの数値をドットで区切るような形でバージョンを指定します。指定がない場合は`0.0.0`とみなされる様子です。

また、`1.0.0-beta.7`などのように開発フェーズに応じたバージョン付けも可能です。プレフィックスには、`-dev.数値`, `-alpha.数値`, `-beta.数値`, `-rc.数値`が指定可能です。

## 4. パッケージビルド環境

`environment`フィールドには、ビルド環境に関する各種設定を行います。

### バージョンの指定方法

yamlファイルを書く上でのバージョン記述の文法は以下の通りです。

|フィールド|説明|
|-------|----|
|0.1.2|0.1.2のみ許可|
|>=0.1.2|0.1.2以上のバージョンを許可|
|>=0.1.2 <1.0.0|0.1.2以上、1.0.0未満のバージョンを許可|
|<0.1.2|0.1.2未満のバージョンを許可|
|^0.1.2|0.1.2以上、0.2.0未満のバーションを許可。つまり、指定されたバージョン以上でマイナーバージョンが同じであれば許可|
|any|バージョン指定なし|
| (空白)|any指定時同様、バージョン指定なし|

### dart-sdkのバージョンを指定する

dart-sdkのバージョンを指定することが出来ます。例えば、dart-sdkが`2.7.0`以上かつ`3.0.0`を要求する場合には以下のように記述します。

```yaml:例
environment:
  sdk: ">=2.7.0 <3.0.0"
```

### Flutter SDKのバージョンを指定する

Flutter (SDK) のバージョンを指定したい場合には、`flutter`フィールドを利用します。

```yaml:例
environment:
  flutter: ^0.1.2
```

## 5. 外部ライブラリの利用

`dependencies`フィールドには利用するライブラリの情報を記載していきます。一番よく更新するフィールドだと思います。

### flutterフィールド

これは必須です。FlutterアプリであればFlutter SDKは必須ですので、必ず書くものとして覚えておきましょう。

```yaml:必ず必要
dependencies:
  flutter:
    sdk: flutter
```

### cupertino_iconsライブラリ

iOSアプリスタイルのUIを作成するためにCupertinoIconsクラスを利用する場合にはこの指定が必須です。

```yaml:例
dependencies:
  cupertino_icons: ^1.0.2
```

### gitのリポジトリを直接参照する方法

ライブラリとして、gitのリポジトリにあるパッケージを直接指定することも可能です。

```yaml:例
dependencies:
  パッケージ名: # パッケージ名を指定する
    git:
      url: https://github.com/jlouage/flutter-carousel-pro.git # repoを指定
      ref: ^1.0.0 # バージョンもしくはブランチ名などを指定
```

### ローカルのパッケージもしくはライブラリを参照する

ライブラリとして、ローカルにあるパッケージを直接指定することも可能です。主に別プロジェクトにしたプラグインの場合にこれを利用すると思います。

```yaml:例
  menubar: # パッケージ名を指定する
    path: ../plugins/menubar # パッケージのパスを指定する
  window_size:
    path: ../plugins/window_size
```

## 6. 開発時用途のライブラリの利用

`dev_dependencies`フィールドには開発時に利用するライブラリ（リリースビルドされる成果物には使わない、例えばテストやLint系など）を指定します。

### ライブラリの指定方法

`dependencies`フィールドの場合と同じです。

```yaml:例
dev_dependencies:
  build_runner: ^1.10.2
  json_serializable: ^3.4.1
```

### テストライブラリ

これもほぼテンプレートとして必須だと覚えておきましょう。

```yaml:各種テストコマンドで必要
dev_dependencies:
  flutter_test:
    sdk: flutter
```

## 7. アセットの設定

`flutter`フィールドには、アプリのバンドル（アセット）として含むファイル（例えば、アイコンや画像など）やフォントの指定などを行ます。

### uses-material-designフィールド

[Material icons](https://material.io/resources/icons/?style=baseline)を利用する場合にtrueを指定します。デフォルト設定で有効になっていますが、基本的にどのアプリでもこのまま利用すると思います。

```yaml:
flutter:
  uses-material-design: true
```

### assetsフィールド

アプリのアセットとして含む画像ファイルなどを指定します。ファイル一つ一つを指定しても良いですが、ディレクトリ単位でも指定可能です。

```yaml:
flutter:
  assets:
    - images_a/
    - images_b/1.jpeg
    - images_b/2jpeg
```

### fontsフィールド

利用するフォントファイルとその設定を行ます。AndroidやiOSなどのようにシステムデフォルトなフォントを持たないデスクトップアプリ（Windows/Linux/macOS)の場合には設定が必須です。これを行わないと文字が正常に表示されません。

`family`フィールドには、Dartソースコードの`TextStyle(fontFamily: 'Schyler'),`で指定する名前を付けておきます。

各フォントファイルアセットの`family`プロパティには、Dartソースコードの`TextStyle(fontStyle: FontStyle.italic)`のように指定された時に選択されるフォントファイルを指定するために利用します。

各フォントファイルアセットの`family`プロパティには、Dartソースコードの`TextStyle(ffontWeight: FontWeight.w700)`のように指定された時に選択されるフォントファイルを指定するために利用します。weightは100から900までの値を100刻みで指定することが可能です。


```yaml:
flutter:
  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
```

## 8. 参考文献

- [The pubspec file](https://dart.dev/tools/pub/pubspec)