親愛なるシリアルパッケージクリエイターのみなさま、ごきげんよう（ｷｭｱﾎｸｿｴﾑです）。一人前のシリパクになるべく修行中です。Rパッケージを作成する際に避けては通れない（必ず作成する必要がある、mandatoryな）DESCRIPTIONファイルについて今更ながら調べてみました。
@yutannihilationさんが書いてくださいました。実際、このEncodingはreadrでも使われています。
コード内に日本語を含むパッケージはDESCRIPTIONにEncode:UTF-8って書いとかないといけないっぽい - Technically, technophobic.
DESCRIPTIONファイルとは何か
Writing R Extensionsの内容からざっくり引っ張ってくるとこんな感じ。
- DESCRIPTIONファイルはパッケージについての簡単な情報を含む
- 統一されたフォーマット（Debian Control File）で書かれる
- コロンとスペース（例えば
Title: hoge）を挟んで各項目について記述する - 複数行に渡る項目（Descriptionなど）についてはタブやスペースによる文字送りをおこなう
- 項目名は大文字と小文字を区別する（頭文字は大文字にするべし）
DESCRIPTIONに記載されるべき項目
必須なものと任意に適宜記載するものがあります。以下にあげるものがすべてではないので注意
| 項目名 | 概要 | 必要性 |
|---|---|---|
Package |
パッケージ名（英数字およびドットが使用可）。パッケージの説明はPackageやTitleではなくDescriptionに記載すべし |
必須 |
Version |
ドットあるいはハイフン区切りの３桁あるいは２桁からなる数値によるバージョン表記。下記でも説明 | 必須 |
License |
ライセンス | 必須 |
Title |
簡単なパッケージの説明。単語は大文字にする（いわゆるcapitalization rules） | 必須 |
Description |
パッケージの概要を細かく記載。 | 必須 |
Authors@R |
person()を使用した作成者の表記 |
必須？ |
Author |
パッケージ作成者。複数人いる場合はそれぞれの役割を記載すると良い | 必須 |
Maintainer |
パッケージの代表管理者（一人）。名前のあとにメールアドレスを記載する。bug.report()を使用したバグ報告にはこのアドレスが使用される？ |
必須 |
Depends |
パッケージが依存しているR本体のバージョンやパッケージ | 任意 |
Imports |
このパッケージ本体が明示的に依存している（関数やデータセットを使用する）パッケージ | 任意 |
Suggests |
パッケージ内で使用しないが、testやvignettesで使うパッケージ | 任意 |
BugReports |
Maintainerへのバグ報告の代わりとして、用意されているバグ報告先。GitHubのissuesへのリンクがしばしば利用される | 任意 |
URL |
適宜参照してほしいURL。複数ある場合にはカンマかスペースで区切って記載する | 任意 |
LazyData |
遅延評価をおこなうがどうかを真偽値で記載 | 任意 |
VignetteBuilder |
vignettesのビルド方法（例. knitr） |
任意 |
Copyright |
著作権の所持者 | 任意 |
Date |
リリースした日付。YYYY-MM-DD表記 |
任意 |
バージョンの付け方
3桁からなるバージョン表記は次のような構造となっている。 ref) http://ja.wikipedia.org/wiki/バージョン#.E3.82.B3.E3.83.B3.E3.83.94.E3.83.A5.E3.83.BC.E3.82.BF.E3.83.BB.E3.82.BD.E3.83.95.E3.83.88.E3.82.A6.E3.82.A7.E3.82.A2
<メジャーバージョン>.<マイナーバージョン>.<メンテナンスバージョン>
著名なggplot2パッケージがメジャーバージョン1.0.0となったのは去年の話。GitHubへのコミット開始から６年以上の歳月を経てのリリースとなっている。それまでは正式なリリースではないというのも恐ろしい話。
またggplot2の開発者であるHadley Wickhamは開発版パッケージのバージョン表記については、.9000で開始する4桁での表記を推奨している（熱心な羽鳥信者であればパッケージ名の表記をこのようにしている。私自身はこれを忘れることが多い）。devtools::create()を使ったパッケージの新規作成を行った場合、DESCRIPTIONファイルのバージョン表記は0.0.0.9000となっていて良いのですが、RStudioの新規パッケージ作成機能を使うと、表記が0.1.0なので注意です。
ライセンスの付け方
ライセンスの表記は利用者や開発者のために必ず記載しましょー。Rパッケージで使用されている主要なライセンスとしてGPL-2, GPL-3, LGPL-2, LGPL-2.1, LGPL-3, AGPL-3, Artistic-2.0, BSD_2_clause, BSD_3_clause, MITがあります。適切なライセンスを選ぶようにすると良いでしょう。
ライセンスの付け方で迷うときはこちらを参考にすると良いです。
- ライセンスの選択を恐れる必要はありません - Qiita
- [GPL][MIT]ライセンスについて基本中の基本的なこと | tomotomo Snippet
- たくさんあるオープンソースライセンスのそれぞれの特徴のまとめ | コリス
- MITライセンスってなに？どうやって使うの？商用でも無料で使えるの？ | WisdomMingle.com（ウィズダムミングル・ドットコム）
別途ライセンスの表記をおこなう場合はMIT + file LICENSEのようにしてLICENSEファイルを用意してください。
AuthorとAuthors@R
ここがよくわかっていないですが...。
比較的最近のパッケージではAuthors@Rという項目が使用されています。これはperson()関数を使用したパッケージ作成者の表記であり、人間さんにとって読みやすいAuthorに対して、Rさんが読みやすいように用意されたものと思われます。
person()関数は次のようになっています。
person(given = NULL, family = NULL, middle = NULL,
email = NULL, role = NULL, comment = NULL,
first = NULL, last = NULL)
ここで重要なのはrole引数で、パッケージ作成における個々人の役割を明記することが推奨されています。role引数に渡す値は次のものがあります。
| 値 | 役割 |
|---|---|
| aut | Author: パッケージの著者。パッケージの引用時に明示されるべき人 |
| com | Compiler: パッケージのコードについてとりまとめをおこなう人 |
| ctb | Contributor: パッケージ作成において貢献してくれた人 |
| cph | Copyright holder: 著作権の保持者 |
| cre | Creator: パッケージの管理者 |
| ths | Thesis advisor: パッケージが論文の一部である場合の指導教員 |
| trl | Translator: コンピュータ言語の翻訳者 |
ImportsとSuggestsの区別
ImportsとSuggestsは依存性の強さで区別されます。ざっくり言うとつぎのような関係です。
-
Imports: パッケージ内の関数内で使用する外部パッケージ。それがないと関数が動作しない。そのため、パッケージのインストール時にはImportsに記載されたパッケージも併せてインストールされる -
Suggests: パッケージ内の関数本体では使用しないが、vignettesやtest環境で用いているパッケージ。パッケージインストール時にはこれらのパッケージはインストールされない
これらの項目はアルファベット順に、一行に一つのパッケージを記載すると良い。特定のバージョンに依存する場合は、比較演算子を用いて明示します。
また、多くのテスト環境を用意する場合、testthatパッケージを使用するかと思います。そのような場合には、Suggests項目にtestthatを明記するのを忘れないようにしましょう。
Imports:
dplyr,
ggvis
Suggests:
MASS (>= 7.3.0),
testthat
シリパク的.Rprofileの設定
毎度毎度、Authorを書くのは面倒ですよね。というわけで個人用の設定を.Rprofileに記載しておくと良いです。というのは実際、devtoolsのREADMEにも書いてある。
Hadleyの言うことに従いました。
ここにある内容に従うと、devtools::create()したときやRStudioで新規パッケージ作成をおこなった際に用意されるDESCRIPTIONファイルに設定を反映できるので便利です。
人の振り見て我が振り直せ
能書きはさておき、実際のパッケージを見てみるのが勉強になることもあります。
昔のパッケージは上記の規則に従っていないものもあるみたいですが、最近のパッケージだとCRANのチェックが厳しいのか、規則通りにDESCRIPTIONファイルが書かれているものが多い印象があります。各パッケージのDESCRIPTIONはlibrary(help = "ggplot2")のようにするかhttp://cran.r-project.org/web/packages/testthat/index.html のようなページで見れます。GitHubにリポジトリがあるパッケージは、そちらも参照すると良いでしょう。
シリアルパッケージクリエイターになりたくなったら
まだシリアルパッケージクリエイターではないけど、少しでも興味を持たれた方は次のページを読むと良いでしょう。シリパクの楽しさが伝わると思います。
- Rパッケージ作成ハドリー風: devtools, roxygen2, testthatを添えて: パッケージ作成に目覚めるきっかけとなった発表資料。パッケージ作成の手順が詳細に！
- 2分でパッケージを作ってインストールする: おにいさん1。パッケージを作って公開するまでの手順
- 東京R非公式おじさんが教える本当に気持ちいいパッケージ作成法: おにいさん2。パッケージ作成の今昔物語。ハンズオンでパッケージの作成する
- Hadley Wickham: Impact the world by being useful « IMS Bulletin: シリパクの心得的な...胸熱
参考
- Writing R Extensions: ちょくちょく改訂されているみたい。本家CRANの指示書き
- Welcome · R packages: Hadley Wickhamの聖書の一つ。シリパクユーザー必見
- Rの拡張を書く （R 2.15.2）: Rバージョン 2.15.2なので古い情報もある