LoginSignup
52
25

More than 3 years have passed since last update.

cargo publish する前に埋めておきたい Cargo.toml の項目に関するメモ

Last updated at Posted at 2020-03-08

正直試行錯誤しないと https://crates.io 挙動が良くわからんかったのでメモを書いておく。

name, version, authors, edition の4つは cargo new の際にでデフォルトで書かれる。

[package]
name = "hoge"
version = "0.1.0"
authors = ["Hideyuki Tanaka <tanaka.hideyuki@gmail.com>"]
edition = "2018"

licenselicense-file の項目は必須。所定のコードを入れるか、license-file にライセンスファイルのファイル名を入れる。

ライセンスのコードは https://spdx.org/licenses/Identifier の項目を入れれば多分良いはず。

license = "MIT"
# または
license-file = "LICENSE"

description と (repository または homepage) も(多分)必須。
repositoryhomepage はあれば http://crates.io のパッケージのページにリンクが張られる。
最初は repository だけで、万が一パッケージが成長して公式ページができたら homepage に書けば良いのでは。

description = "Hoge library"
repository = "https://github.com/tanakh/hogehoge"
homepage = "..."

documentation のURLもパッケージのページからリンクが張られるが、この項目がない場合、自動生成された https://docs.rs のドキュメントへのリンクが自動的にパッケージのリンクに貼られるので、よほどこだわりがないかドキュメントの自動ビルドに失敗するような場合以外は空にしておいた方が良いのでは。

documentation = "..."

readme にパッケージ内へのファイル名を指定しておけば、それをパッケージのページの "About This Package" みたいなところにレンダリングしてくれる(とりあえずMarkdownはしてくれた)。正直これがあるとないとでは見栄えが全然違うのでこれは指定しておいた方が良いと思う。

readme = "README.md"

ところで、README.md を書くのは面倒、というか、crateのドキュメントと同じ事を書きたいことが多いはず。そして、同じテキストを複数のファイルに書くのはドキュメントの同期を取るのが面倒すぎる。

こういう意識は世の中にも当然あるみたいで、cargo-readmeというcrateのドキュメントからREADME.mdを生成するツールがある。なので、README.md はこれを使って生成するのが良いだろう。

このツールはCargo.toml[badges]セクションを見て、README.mdの先頭にバッジを置いてくれるので、ここも埋めておくのが良いだろう。詳しい書き方はhttps://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-sectionこの辺にある。

[badges]
github = { repository = "tanakh/hogehoge", workflow = "Rust" }

categorieskeywords は埋めておくとページにそれぞれカテゴリーとキーワードへのリンクを付けてくれる。
パッケージを見つけてもらいやすくなるんだと思う。

categories の方は https://crates.io/category_slugs の中から選択で、keywords は好きな単語を書けば良いんじゃないかと思う(https://crates.io/keywords の人気の高いのを書くと見つけられやすくなるのかも知れない)。

categories = ["algorithms"]
keywords = ["graph"]

まとめ

cargo publish するときに設定しておいた方が良い項目のまとめ:

[package]
# `cargo new` が自動生成するやつ
name = "..."
version = "..."
authors = ["..."]
edition = "2018"

# `cargo publish` するときに最初から埋めて置いた方が良い項目
description = "..."
repository = "<url-to-repository>"
license = "MIT" # <https://spdx.org/licenses/> から選択
readme = "README.md" # `cargo-readme` で生成するのが便利

# お好みで
categories = ["..."] # <https://crates.io/category_slugs> から選択
keywords = ["..."] # 好きに書けるけど <https://crates.io/keywords> から選ぶとよさそう

# あれば
homepage = "<url-to-homepage>"

# デフォルトで docs.rs へのリンクが作られるからあまり要らないのでは
documentation = "<url-to-documentation>"

# バッジを埋めておくと `cargo-readme` がバッジを埋めてくれる
[badges]
github = { repository = "tanakh/hogehoge", workflow = "Rust" }
52
25
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
52
25