crateをcrates.ioに公開してみる

これはRust その2 Advent Calendar 2016 - Qiita11日目の記事です。

このエントリではcrateをcrates.ioに公開する方法を紹介します。

crates.ioとは

Cargo用のセントラルパッケージリポジトリです。

https://crates.io/

Cargoはこちらから依存するcrateを取得します。 また、作成したcrateの公開もCargoから実行可能です。

crates.ioでは一度公開されたcrateが非公開化・削除されないようcrateのバージョン管理を行っています。 発行できるバージョン数に制限はありませんが、 一度発行したバージョンを上書き・削除することはできないので公開する際には注意が必要です。

それでは、crates.ioにcrateを公開する方法を紹介していきます。

crates.ioのアカウントを作成する

crateを公開するためにはcrates.ioにGithubアカウントでログインし、 APIトークン取得する必要があります。

cargo.ioのページからGithubアカウントでログインします f:id:takatorix:20161210213626p:plain

Account Settingsページに移動し、APIトークンを取得します f:id:takatorix:20161210213622p:plain

f:id:takatorix:20161210213633p:plain

取得した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に公開する方法を紹介しました。 簡単にパッケージを公開できるのでどんどん開発していきましょう!

参考