「Arch パッケージガイドライン」の版間の差分

2023年6月24日 (土) 19:21時点における最新版

Arch Linux のためにパッケージを作成するときは―特に新しいパッケージを Arch Linux に貢献するのが目的のときは以下のパッケージガイドラインを守って下さい。PKGBUILD や makepkg の man ページも見て下さい。

1 PKGBUILD プロトタイプ
2 パッケージエチケット
3 パッケージの命名
4 パッケージのバージョン管理
5 パッケージの依存関係
6 パッケージ関係
7 パッケージソース
8 アップストリームとの連携
9 ディレクトリ
10 Makepkg が行うこと
11 アーキテクチャ
12 ライセンス
13 パッケージを AUR に投稿する
14 再現性のあるビルド
15 追加ガイドライン

PKGBUILD プロトタイプ

# Maintainer: Your Name <youremail@domain.com>
pkgname=NAME
pkgver=VERSION
pkgrel=1
pkgdesc=""
arch=()
url=""
license=('GPL')
groups=()
depends=()
makedepends=()
optdepends=()
provides=()
conflicts=()
replaces=()
backup=()
options=()
install=
changelog=
source=($pkgname-$pkgver.tar.gz)
noextract=()
md5sums=() #autofill using updpkgsums

build() {
  cd "$pkgname-$pkgver"

  ./configure --prefix=/usr
  make
}

package() {
  cd "$pkgname-$pkgver"

  make DESTDIR="$pkgdir/" install
}

他にも pacman や abs パッケージからのプロトタイプが /usr/share/pacman にあります。

パッケージエチケット

パッケージは /usr/local にインストールしてはいけません
パッケージがそれなしではビルドできないという状態を除いて、PKGBUILD ビルドスクリプトに新しい変数を使ってはいけません。makepkg で使われている変数と衝突する恐れがあるからです。新しい変数がどうしても必要な時は、 変数の名前の前にアンダーバーを付けて下さい (_), 例:
```
_customvariable=
```
いかなるものにも /usr/libexec/ を使うことは避けてください。代わりに /usr/lib/${pkgname}/ を使って下さい。
パッケージメタファイルの packager フィールドはパッケージ作成者が /etc/makepkg.conf 内の適切なオプションを修正するか、~/.makepkg.conf を作成して上書きすることでカスタマイズすることができます
重要なメッセージは全てインストール中に .install ファイルを使って表示してください。例えば、パッケージを動作させるのに追加のセットアップが必要な時は、説明を加えて下さい。
それがなくても動作したり、一般的な機能には必要ない提案パッケージ(任意依存パッケージ)を含めてはいけません; そうした情報は optdepends に追加してください:
```
optdepends=('cups: printing support'
            'sane: scanners support'
            'libgphoto2: digital cameras support'
            'alsa-lib: sound support'
            'giflib: GIF images support'
            'libjpeg: JPEG images support'
            'libpng: PNG images support')
```
上記のサンプルは extra の wine パッケージです。optdepends の情報はインストールやアップグレードのときに自動で表示されます。従ってこの種の情報は .install ファイルに記入してはいけません。
パッケージのパッケージ説明を作る時は、パッケージの名前を繰り返さないで下さい。例えば、"Nedit is a text editor for X11" はシンプルに "A text editor for X11" にできます。また、説明は80文字以下に抑えて下さい。
PKGBUILD 内の行の長さは100文字以下にしてください。
できるだけ、PKGBUILD から空の行を削除してください (provides, replaces, etc.)
PKGBUILD の項目は上記の順番を守るのが常識になっています。ただし、これは強制ではありません、中身が正しい bash 構文なら大丈夫です。

パッケージの命名

パッケージの名前は英数字だけでなくてはなりません; 全ての文字は小文字でなくてはなりません。
パッケージのバージョンは作者によってリリースされたバージョンと同じでなくてはなりません。必要ならばバージョンには文字を入れることもできます (例, nmap のバージョンは 2.54BETA32)。バージョンタグにハイフンを含めることはできません!文字、数字およびピリオドのみです。
パッケージリリースは Arch Linux のパッケージ特有のものです。パッケージビルドの新旧をユーザーが見分けられるようにするためにあります。新しいパッケージバージョンがリリースされたとき、リリースカウントは1から始まります。修正や最適化がなされるたびに、パッケージは Arch Linux ユーザーに再リリースされリリース番号が増加します。新しいバージョンが出ると、リリースカウントは1にリセットします。パッケージのリリースタグはバージョンタグと同じ命名規則に従います。

パッケージのバージョン管理

パッケージのバージョン (つまり PKGBUILD#pkgver) は、作成者がリリースしたバージョンと同じである必要があります。必要に応じて、バージョンには文字を含めることができます (例: nmap 2.54BETA32) バージョンタグにはハイフンを含めることはできません! 文字、数字、ピリオドのみ。
パッケージリリース (つまり PKGBUILD#pkgrel) は、Arch Linux パッケージに固有 です。これらにより、ユーザーは新しいパッケージビルドと古いパッケージビルドを区別できるようになります。新しいパッケージバージョンが最初にリリースされると、リリースカウントは 1 から始まります その後、修正と最適化が行われると、パッケージは Arch Linux 一般向けに再リリース され、リリース番号が増加 します。新しいバージョンがリリースされると、リリース数は 1 にリセットされます。パッケージのリリースタグは、バージョンタグと同じ命名制限 に従います。

パッケージの依存関係

いずれかの PKGBUILD#依存関係推移的依存関係 に依存しないでください。依存関係の 1 つが更新されると壊れる可能性があります。
すべての直接ライブラリ依存関係をリストします。それらを識別するには、find-libdeps(1) (devtools の一部) を使用できます。

パッケージ関係

$pkgname は PKGBUILD#provides に追加しないでください。これは常にパッケージによって暗黙的に提供されるためです。
PKGBUILD#provides 内のパッケージのすべての外部共有ライブラリをリストします (例: 'libsomething.so') それらを識別するには、find-libprovides(1) (devtools の一部) を使用できます。

パッケージソース

HTTPS ソース (tarball の場合は https://、git ソースの場合は git+https://) を可能な限り使用する必要があります
ソースは可能な限り PGP 署名を使用して検証する必要があります (アップストリームが tarball ではなくコミットとタグに署名する場合、ソース tarball ではなく git タグからのビルドが必要になる可能性があります)
git タグからビルドする場合は、タグ名の代わりに git rev-parse から取得したオブジェクトハッシュを使用します。

_tag=1234567890123456789012345678901234567890 # git rev-parse "v$pkgver"
source=(git+https://$url.git?signed#tag=$_tag)

pkgver() {
    cd "$pkgname"
    git describe
}

このアプローチの例は、gitea パッケージにあります。この方法を実行する理由は、タグが強制的にプッシュされて、タグが指しているコミットを変更し、ビルドされたパッケージが変更される可能性があるためです。タグを強制的にプッシュするとハッシュが変更されるため、タグオブジェクトハッシュを使用すると、ソースの整合性が保証されます。pkgver() 関数を使用すると、_tag を更新せずに誤って pkgver を実行してしまうことを防ぎます。

パッケージのセキュリティや有効性を低下させないでください (例: チェックサムチェックを削除するか、PGP 署名検証を削除することによって)、アップストリームリリースが破損しているか、特定の機能が突然欠落しているため (例:PGP 署名が欠落しているなど) 新しいリリース)
ソースは srcdir 内で一意である必要があります (ダウンロード時に名前の変更が必要になる場合があります、例: "${pkgname}-${pkgver}.tar.gz::https:/) /${pkgname}.tld/download/${pkgver}.tar.gz")
利用できなくなる可能性があるため、特定のミラー (sourceforge など) を使用してダウンロードすることは避けてください。

アップストリームとの連携

可能な限りアップストリームと緊密に連携することがベストプラクティスと考えられます。これには、パッケージの構築とテストに関する問題の報告が伴います。

問題をすぐにアップストリームに報告してください。
可能な限りアップストリームパッチ。
関連する (アップストリームの) バグトラッカーチケットへのリンクを含むコメントを PKGBUILD に追加します (これは、他のパッケージャーが変更を理解し、パッケージを操作できるようにするため、特に重要です)

新しい安定リリースについての情報を得るには、nvchecker や urlwatch などのツールを使用してアップストリームを追跡することをお勧めします。

ディレクトリ

設定ファイル は、/etc ディレクトリに配置する必要があります。複数の構成ファイルがある場合は、/etc 領域をできるだけクリーンに保つために サブディレクトリを使用 するのが一般的です。/etc/pkg を使用します。ここで、pkg はパッケージの名前です (または、適切な代替手段、たとえば Apache は /etc/ を使用します) httpd/)
パッケージファイルは以下の一般ディレクトリガイドラインに従って下さい:

`/etc`	システムの重要な設定ファイル
`/usr/bin`	バイナリ
`/usr/lib`	ライブラリ
`/usr/include`	ヘッダーファイル
`/usr/lib/pkg`	モジュール、プラグインなど
`/usr/share/doc/pkg`	アプリケーションのドキュメント
`/usr/share/info`	GNU Info system ファイル
`/usr/share/licenses/pkg`	アプリケーションライセンス
`/usr/share/man`	Manpages
`/usr/share/pkg`	アプリケーションのデータ
`/var/lib/pkg`	アプリケーションの永続的なストレージ
`/etc/pkg`	pkg の設定ファイル
`/opt/pkg`	大型の自己完結型パッケージ

パッケージに以下のディレクトリを含めてはいけません。
- /bin
- /sbin
- /dev
- /home
- /srv
- /media
- /mnt
- /proc
- /root
- /selinux
- /sys
- /tmp
- /var/tmp
- /run

Makepkg が行うこと

パッケージをビルドするのに makepkg が使われると、makepkg は以下のことを自動で行います:

パッケージの依存パッケージや提案パッケージがインストールされているかチェック
サーバーからソースファイルをダウンロード
ソースファイルの整合性を確認
ソースファイルを解凍
必要なパッチの適用
fake root 環境でのソフトウェアのビルドとインストール
バイナリからシンボルを除去
ライブラリからデバッグ用のシンボルを除去
manual や info ページを圧縮
それぞれのパッケージに含まれるパッケージメタファイルを生成
fake root を圧縮してパッケージファイルを生成
パッケージファイルを指定されたディレクトリに保存 (デフォルトでは cwd に保存)

アーキテクチャ

arch 行にはビルドできるアーキテクチャによって 'i686' や 'x86_64' を入力します。アーキテクチャに依存しないパッケージには 'any' を使うこともできます。

ライセンス

公式リポジトリでは license 行が使われています、同じようにあなたのパッケージでも使うべきです。使い方は次の通り:

[core] の licenses パッケージはよく使われるライセンスを /usr/share/licenses/common に保存します。例: /usr/share/licenses/common/GPL。パッケージのライセンスがここに保存されているライセンスのどれかのときは、ディレクトリの名前を設定してください、例: license=('GPL')
適切なライセンスが公式の licenses パッケージに含まれていない場合は、やる必要があることがいくつかあります:
1. ライセンスファイルを次のディレクトリに含めなくてはなりません: /usr/share/licenses/$pkgname/ , 例: /usr/share/licenses/dibfoo/LICENSE。次の一行でこれを行えます:
```
install -D -m644 LICENSE "${pkgdir}/usr/share/licenses/${pkgname}/LICENSE"
```
2. ソース tarball にライセンスの詳細が含まれずウェブサイトなど他のところで示されている場合は、ライセンスをファイルにコピーしてそのファイルを含めて下さい。
3. license 行に 'custom' を加えて下さい。任意で、'custom' を 'custom:"name of license"' に置き換えることもできます。
あるライセンスが ([community] を含む) 公式リポジトリの2つ以上のパッケージで使われると、licenses パッケージに入れられます。
特別な事例として BSD, MIT, zlib/png, Python ライセンスは通常の licenses パッケージに含められていません。license 行の目的のために、一般的なライセンス (license=('BSD'), license=('MIT'), license=('ZLIB'), license=('Python')) として扱われておきながらそれぞれ固有の copyright 行を持っているために技術的にカスタムライセンスになっています。これら4つのライセンスを使っている全てのパッケージは /usr/share/licenses/pkgname 内にそのライセンスを保存しておく必要があります。
パッケージによってはライセンスがひとつだけではないこともあります。そのような場合は、license 行に複数のエントリを書くことができます、例: license=("GPL" "custom:some commercial license")。パッケージの大多数は、一度に適用されるのでなく、異なるケースでライセンスが適用されます。pacman にライセンスでフィルターをかける機能ができたら(つまり、"GPL と BSD ライセンスのソフトウェアだけが欲しい"などと言える)デュアルライセンスは pacman によって AND ではなく OR で扱われます。他のライセンスが挙げられているのかかわらず、pacman は上記のサンプルを GPL ライセンスのソフトウェアだと認識します。
(L)GPL には多くのバージョンと組み合わせが存在します。(L)GPL ソフトウェアで使えるのは:
- (L)GPL - (L)GPLv2 もしくはそれ以降のバージョン
- (L)GPL2 - (L)GPL2 のみ
- (L)GPL3 - (L)GPL3 もしくはそれ以降のバージョン

パッケージを AUR に投稿する

AUR にパッケージを投稿する前に以下のことに注意してください:

いかなる場合でも既に公式のバイナリリポジトリにあるアプリケーションをビルドする PKGBUILD を投稿してはいけません。このルールの唯一の例外は公式のものに対して新しい機能やパッチがパッケージに加えられている場合です。そのようなときは、pkgname 行は異なっている必要があります。例: サイドバーパッチを含んだ GNU screen の PKGBUILD は screen-sidebar などの名前にして投稿してください。さらに、公式パッケージとの衝突を避けるために provides=('screen') を使わなくてはなりません。
AUR に投稿するパッケージのセキュリティを保証するために、md5sum を正しく入力するようにしてください。md5sum の値は updpkgsums コマンドを使って生成できます。
次のフォーマットに従って PKGBUILD ファイルの一番上にコメント行を追加するようにお願いします。スパム避けのためにあなたのメールアドレスを偽装することを覚えておきましょう:
```
# Maintainer: Your Name <address at domain dot com>
```
既存の PKGBUILD のメンテナーを引き継ぐときは、以前のメンテナーを Contributor に変えて、あなたの名前を上記の通りに追加してください:
```
# Maintainer: Your Name <address at domain dot com>
# Contributor: Previous Name <address at domain dot com>
```
パッケージの依存関係を確認してください (例: 動的な実行ファイルで ldd を実行して必要なツールを確認する、など)。 TU チームは Jason Chu によって書かれた namcap ユーティリティを使ってパッケージのサニティを分析することを強く推奨します。namcap は不正なパーミッション、欠けている依存パッケージ、不必要な依存パッケージなどの一般的な手違いを警告します。namcap パッケージは pacman でインストール可能です。 pkg.tar.gz ファイルと PKGBUILD の両方をチェックできる namcap を覚えておいて下さい
よくあるパッケージングの誤りとして依存関係の誤りがあります。Namcap は検知の助けになりますが、いつでも正しいわけではありません。ソースドキュメントやプログラムのウェブサイトを見て依存関係を確認してください。
Ethereal が Wireshark になったときなど、パッケージの名前が変わったとき以外は replaces を使わないで下さい。パッケージが既存のパッケージの別バージョンのときは、conflicts (パッケージが他のパッケージから必要とされているときは provides) を使って下さい。主な違いは: replaces は pacman を同期させた後すぐにインストール済みの'邪魔な'パッケージを置き換えますが; conflicts はパッケージをインストールするときにだけ調査されます。通常これは侵襲性が低いときの望ましい挙動になります。
AUR にアップロードする全てのファイルは PKGBUILD と追加のビルドファイル (patches, install, ...) を含んだディレクトリの圧縮された tar ファイルである必要があります。
```
foo/PKGBUILD
foo/foo.install
foo/foo_bar.diff
foo/foo.rc.conf
```
アーカイブの名前はパッケージの名前を含めてください例: foo.tar.gz。
makepkg --source を使うことで全ての必要なファイルが入った tarball を簡単に作成することができます。このコマンドでは $pkgname-$pkgver-$pkgrel.src.tar.gz という名前の tarball が作成され、これはこのまま AUR にアップロードすることができます。
tarball にファイルリストに含まれるバイナリや makepkg で作成したバイナリの tarball を含めてはいけません

再現性のあるビルド

Arch はすべてのパッケージを再現可能にすることに取り組んでいます。パッケージャーは、devtools の makerepropkg または archlinux-repro の repro を使用して、パッケージが再現可能かどうかを確認できます。

$ makerepropkg $pkgname-1-1-any.pkg.tar.zst

もしくは、

$ repro -f $pkgname-1-1-any.pkg.tar.zst

ビルド時にタイムスタンプが必要な場合は、環境変数 SOURCE_DATE_EPOCH を使用します。形式はアップストリームで文書化

追加ガイドライン

最初に上記のガイドラインを読んで下さい - このページで挙げた重要なポイントは、以下のガイドラインページでは繰り返しません。以下のガイドラインはこのページのスタンダードへの追加として存在します。

パッケージ作成ガイドライン

32ビット – CLR – クロス – Eclipse – Electron – Free Pascal – GNOME – Go – Haskell – Java – KDE – カーネル – Lisp – MinGW – Node.js – ノンフリー – OCaml – Perl – PHP – Python – R – Ruby – Rust – VCS – ウェブ – Wine