crateをcrates.ioに公開してみる
これはRust その2 Advent Calendar 2016 - Qiita11日目の記事です。
このエントリではcrateをcrates.ioに公開する方法を紹介します。
crates.ioとは
Cargo用のセントラルパッケージリポジトリです。
Cargoはこちらから依存するcrateを取得します。 また、作成したcrateの公開もCargoから実行可能です。
crates.ioでは一度公開されたcrateが非公開化・削除されないようcrateのバージョン管理を行っています。 発行できるバージョン数に制限はありませんが、 一度発行したバージョンを上書き・削除することはできないので公開する際には注意が必要です。
それでは、crates.ioにcrateを公開する方法を紹介していきます。
crates.ioのアカウントを作成する
crateを公開するためにはcrates.ioにGithubアカウントでログインし、 APIトークン取得する必要があります。
cargo.ioのページからGithubアカウントでログインします
Account Settingsページに移動し、APIトークンを取得します
取得したAPIトークンをCargoに登録するために、以下のコマンドを実行します。
$ cargo login <APIトークン>
このコマンドはローカルの~/.cargo/config
にトークンを保存しています。
Cargo.tomlに情報を追加する
cargo new で生成されたCargo.tomlファイルには以下の情報が記載されます。
[package] name = "rawst" version = "0.1.0" authors = ["takatori <takatorix@gmail.com>"]
上記の情報のみでもcrateを公開することが可能ですが、 より検索に引っかかりやすいようメタデータを追加していきます。
[package] name = "rawst" version = "0.1.0" authors = ["takatori <takatorix@gmail.com>"] license = "MIT" description = "The interactive tool for AWS CLI written in Rust" repository = "https://github.com/takatori/rawst" readme = "README.md" keywords = ["rawst", "aws"]
この他に、homeページやdocumentページを指定することもできます。
また、バージョン管理システムでignoreされているファイルは自動的にパッケージから除外されますが、 excludeで除外するファイル・ディレクトリを明示的に指定することもできます。
[package] # ... exclude = [ "public/assets/*", "videos/*", ]
逆に、includeでpackageに含めるものを指定することもできます。
crateの名前は先着順に割り当てられるため、すでに使用されているものは使えないので気をつけてください。
パッケージング
次にcrate.ioにアップロードできるフォーマットにcrateをパッケージングします。
$ cargo package
このコマンドを実行するとtarget/package
ディレクトリに.crate
ファイルが生成されます。
.crate
ファイルは現在のとろこ、最大10MBまでしかアップロードできないのでサイズの大きな画像ファイルなどはexclude指定すると良いでしょう。
また、コミットされていないファイルがある場合以下のようなエラーが出ます。
error: 1 dirty files found in the working directory:
すべてのファイルをcommitまたはstashするか--allow-dirty
フラグを付けることでパッケージングできるようになります。
公開する
それではcrateをcrates.ioにアップロードします。
$ cargo publish
この段階で依存crateのバージョンをワイルドカードで指定している場合、以下のようなエラーが発生します。
error: api errors: wildcard (`*`) dependency constraints are not allowed on crates.io.
ワイルドカードは許可されていないので、明示的にバージョンを指定する必要があります。
publishが成功すると以下のようにcrates.io-index
リポジトリにindexが登録されていることが確認できます。
https://github.com/rust-lang/crates.io-index/blob/master/ra/ws/rawst#L1
発行したバージョンを取り下げる
誤ってバージョンを発行してしまった場合yank
コマンドで取り下げることができます。
$ cargo yank --vers 1.0.1
このコマンドはcrates.ioに公開されたデータを削除するのではなく、 指定したバージョンを新たに使用できないようにします。 すでにこのバージョンを指定しているプログラムからは引き続き使用することができます。
一度発行してしまったバージョンはどうあがいても変更できませんので、 誤ってクレデンシャル等の情報を含めて発行してしまった場合、クレデンシャルの方を即座に変更する必要があります。
まとめ
cargoを使ってcrateをcrates.ioに公開する方法を紹介しました。 簡単にパッケージを公開できるのでどんどん開発していきましょう!