macでBuf CLIを使用する - 1

:::note info
本記事はBuf CLIの使い方 1回目です
:::

# 概要

本記事ではBuf CLIのチュートリアルを通して使い方を理解していきたいと思います。

# Buf CLI

Buf CLIはProtobufスキーマの管理に役立つツールです。コード生成、変更検出、リンティング、書式設定などさまざまな機能を提供し、Protobufの開発と保守を支援します。お好みのプラグインや言語で動作し、Buf Schema Registryにある認定プラグインの膨大なライブラリにアクセスできます。
参照: https://buf.build/docs/cli/

# Buf CLIのインストール

Homebrewを使用してインストールできます

```terminal
brew install bufbuild/buf/buf
```

このインストールには以下も含まれます。

- `buf` , `protoc-gen-buf-breaking` , `protoc-gen-buf-lint` のバイナリ
- `buf` の Bash 補完
- `buf` の Fish 補完
- `buf` の Zsh 補完

参照: https://buf.build/docs/cli/installation/

正常にインストールできていれば以下のコマンドでバージョンを確認できます。

```terminal
buf --version
```

```terminal:例
% buf --version
1.50.0
```

# チュートリアル

## buf-tourのリポジトリのクローン

以下のコマンドでbuf-tourをクローンします

```terminal
git clone git@github.com:bufbuild/buf-tour.git
```

GitHub CLI ghをインストールしている場合は以下でも大丈夫です。

```terminal
gh repo clone bufbuild/buf-tour
```

このリポジトリは `start` ディレクトリと `finish` ディレクトリがあり、`start` ディレクトリでファイルを操作して、最終的に `finish` ディレクトリの状態に一致します。

今回は `start/getting-started-with-buf-cli` を使用するのでワーキングディレクトリを変更します。

```terminal
cd buf-tour/start/getting-started-with-buf-cli
```

## ワークスペースの構成

設定の初期化を実施します。

```terminal:~/.../buf-tour/start/getting-started-with-buf-cli
buf config init
```

以下のようなbuf.yamlが生成されます。

```yaml:buf.yaml
# For details on buf.yaml configuration, visit https://buf.build/docs/configuration/v2/buf-yaml
version: v2
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE
```

buf.yamlファイルはワークスペースのルートに置かれ、このファイルが定義するワークスペースは、すべてのBuf操作のデフォルト入力となります。

## ディレクトリパスの更新とモジュールのビルド

生成された buf.yaml ファイルは、カレントディレクトリにパスが設定された1つのモジュールを持つワークスペースのように振る舞います。ワークスペース内のモジュールを明示的に定義するには、.proto ファイルを含むディレクトリのパスを指定します。
modules キーを使用して、buf.yaml ファイルに proto ディレクトリを追加します。


```yaml:buf.yaml
version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE
```

続行する前に、すべてが正しくセットアップされ、モジュールがビルドされることを確認してください。エラーがなければ、Bufモジュールは正しくセットアップされています。

```terminal:~/.../buf-tour/start/getting-started-with-buf-cli/
buf build
```

## コードの生成

モジュールの設定が終わったので、次はローカルコード生成を設定するための buf.gen.yaml ファイルを作成します。
buf.gen.yaml ファイルは、buf generate コマンドが与えられたモジュール上でどのように protoc プラグインを実行するかを制御します。
このファイルを使って、各protocプラグインが結果を書き込む場所を設定したり、各プラグインのオプションを指定したりできます。

カレントディレクトリに以下の内容のファイルを作成します。

```yaml:buf.gen.yaml
version: v2
managed:
  enabled: true
  override:
    - file_option: go_package_prefix
      value: github.com/bufbuild/buf-tour/gen
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen
    opt: paths=source_relative
  - remote: buf.build/connectrpc/go
    out: gen
    opt: paths=source_relative
inputs:
  - directory: proto
```

buf.gen.yamlファイルが設定できたので、PetStoreService APIに関連するConnect RPCとGoコードを生成できます。
以下のコマンドを実行します。

```terminal:~/.../buf-tour/start/getting-started-with-buf-cli
buf generate
```

生成が成功したら、 `gen` ディレクトリとその中に幾つかのファイルが作成されます。

```
getting-started-with-buf-cli
├── buf.gen.yaml
├── buf.yaml
├── gen
│   ├── google
│   │   └── type
│   │       └── datetime.pb.go
│   └── pet
│       └── v1
│           ├── pet.pb.go
│           └── petv1connect
│               └── pet.connect.go
└── proto
    ├── google
    │   └── type
    │       └── datetime.proto
    └── pet
        └── v1
            └── pet.proto
```
ここまでで上記のような構成になっているはずです。

今回はここまでとします。

# 参考

- https://buf.build/docs/cli/
- https://buf.build/docs/cli/installation/
- https://buf.build/docs/cli/tutorial/