doc/ja_JP.eucJP/man/man7/release.7

.\" Copyright (c) 2002 Murray Stokely <murray@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" %FreeBSD: src/share/man/man7/release.7,v 1.47.2.4 2005/03/23 16:18:10 jhb Exp %
.\" $FreeBSD$
.\"
.\" WORD: clean system	まっさらのシステム[release.7]
.\"
.Dd September 6, 2004
.Dt RELEASE 7
.Os
.Sh 名称
.Nm release
.Nd "リリース構築基盤"
.Sh 解説
.Fx
は、ユーザが
.Fx
オペレーティングシステムのリリース全てを作成できるような完全な構築環境を
提供しています。
リリースを構築するために必要なツールの全ては、 CVS リポジトリ中の
.Pa src/release
に揃っています。
実のところ、
CD-ROM を焼く際に使える ISO イメージ、インストール用フロッピ、
FTP インストール用ディレクトリの生成をはじめとして、完全なリリースを
コマンド一発で構築できます。
このコマンドは、
.Dq Li "make release"
と、うまい名前が付けられています。
.Pp
リリースを構築する前に、
.Xr build 7
の内容によく馴染んでおいてください。
また、ソースからのシステムアップグレードの経験も必須です。
リリース構築プロセスでは、
現在動作しているカーネルに対応したソースから、そのシステム上で
.Dq Li "make buildworld"
によってコンパイルされた結果を、
.Pa /usr/obj
に置いておくことが必要です。
完全なシステムのためのオブジェクトファイルを、まっさらの
.Xr chroot 8
環境にインストールできるようにするために、これが必要となります。
リリースを進めるには、
.Xr md 4
(メモリディスク) デバイスドライバがカーネルに存在する
(コンパイル済み、またはモジュールとして利用可能のいずれも可)
ことも必要です。
.Pp
この文書は、ソースコード管理、品質管理など、
リリースエンジニアリングプロセスに関するその他の側面は扱いません。
.Sh ターゲット
リリース用 makefile
.Pq Pa src/release/Makefile
は、かなり難解です。
ほとんどの場合、
.Cm release
ターゲットのことを考えるだけで済むと思います。
.\" XXX: Some sort of introduction to this list?  All the others have one.
.Bl -tag -width ".Cm package-split"
.It Cm release
.Dq Li "make installworld"
を用いて、ファイルシステムの
.Xr chroot 8
環境にまっさらのシステムをインストールします。
指定したバージョンのソースコードをチェックアウトし、
.Dq Li "make buildworld"
を用いて、まっさらの環境に完全なシステムを再構築します。
そのあとに、ディストリビューション別のパッケージング(まとめ上げ)、
インストール用フロッピディスクの構築、リリース文書の構築などの
細かいステップが続きます。
.Pp
このターゲットは、
.Va kern.securelevel
sysctl を \-1 (デフォルト)
とした root で構築する必要があります。
.It Cm rerelease
このターゲットは、リリース構築作業の結果を手で修正し、前の
.Dq Li "make release"
の中間結果を使い、最小のステップ数でリリースを再構築することを
想定したものです。
.It Cm floppies
新規のブートおよび fixit フロッピの組を作成します。
.Cm release.4 ,
.Cm release.8 ,
.Cm floppies.1 ,
.Cm floppies.2 ,
.Cm floppies.3
ターゲットを呼び、直前の
.Dq Li "make release"
のフロッピイメージを再作成します。
このターゲットは、カスタムブートフロッピの作成にもっとも良く使用されます。
.It Cm package-split
ディスク 1 およびディスク 2 のイメージの、パッケージ関連部分を作成します。
ports チームが提供するパッケージビルドからパッケージを取り出して適切に編成するため、
.Pa src/release/package-split.py
スクリプトから作られる必要なパッケージのリストを使用します。
この結果得られるディレクトリは、
.Cm iso.1
ターゲットで適切なパッケージ関連素材とともに ISO イメージを構築するように、
.Va CD_PACKAGE_TREE
変数を介して
.Dq Li "make release"
に渡すことができます。
.El
.Pp
.Dq Li "make release"
により呼び出されるターゲットは次のとおりです。
.Bl -tag -width ".Cm fetch-distfiles"
.It Cm release.1
ディレクトリ
.Pa ${CHROOTDIR}/R
をまっさらにし、
.Xr mtree 8
を用いてシステム用のディレクトリ階層を構築します。
.It Cm release.2
システムをディストリビューション用ディレクトリにインストールします。
.It Cm release.3
.Pa GENERIC
カーネルを作り、インストールします。
同時に
.Va KERNELS
にリストされた他のカーネルも、作成しインストールします。
.It Cm release.4
.Xr crunchgen 1
を用いて、インストール用フロッピに収容する
.Dq crunched
バイナリを構築します。
.It Cm release.5
合成ディストリビューションを構築し、
また、作成されたディストリビューションツリーを掃除しきれいにします。
.It Cm release.6
組み立てられたディストリビューションツリーの tarball を
生成します。
.It Cm release.7
ソースディストリビューションを作成します。
.It Cm release.8
MFS root ファイルシステムを生成します。
.It Cm floppies.1
boot と kernel フロッピを生成します。
.It Cm floppies.2
fixit フロッピを生成します。
.It Cm floppies.3
.Pa ${CHROOTDIR}/R/ftp/stage/floppies
ステージディレクトリでの作業の仕上げをします。
.It Cm ftp.1
FTP インストールに適切な領域を
.Pa ${CHROOTDIR}/R/ftp
に整えます。
.It Cm cdrom.1
live ファイルシステム CD-ROM イメージ用の配置を、
.Pa ${CHROOTDIR}/R/cdrom
以下に作成します。
.It Cm cdrom.2
1 枚目および 2 枚目の CD-ROM イメージ用の配置を作成します。
.It Cm cdrom.3
ブート専用 CD-ROM イメージおよびブート専用 UFS miniroot
イメージ用の配置を作成します。
.It Cm iso.1
CD-ROM リリース領域から ISO イメージを構築します (インストール用と
.Dq live
ファイルシステムの 2 つ)。
デフォルトでは無効になっています。
以下の
.Va MAKE_ISOS
を参照してください。
.It Cm fetch-distfiles
リリースビルドに必要な distfile で
.Va RELEASEDISTFILES
にはまだ無いものを取得します。
.It Cm doc.1
.Fx
ドキュメンテーションプロジェクトのソースドキュメント (SGML, XML) を
リリースに含める HTML / テキストドキュメントに変換するために
必要なツール全てを構築します。
また、現在存在するユーザドキュメントも構築、インストールします。
これには、Handbook, FAQ, article などが含まれます。
.It Cm doc.2
リリースドキュメントを構築します。
これには、リリースノート、ハードウェアガイド、インストール作業説明書
(installation instructions) が含まれます。
.El
.Sh 環境変数
指定しなければならない環境変数は以下のとおりです。
.Bl -tag -width ".Va BUILDNAME"
.It Va BUILDNAME
構築するリリースの名前。
この名前は、
.Pa sys/conf/newvers.sh
の中で
.Va RELEASE
の値を設定するのに使用します。
この値は
.Xr uname 1
の出力を変更します。
.It Va CHROOTDIR
.Xr chroot 8
環境として、全リリース構築に使用するディレクトリ。
.\" XXX: I recommend against hardcoding specific numbers like "2.3" here;
.\" XXX: perhaps it should be replaced with something to the effect of
.\" XXX: "we do not know how much space you'll need, but make sure you have
.\" XXX: at least 3 GB to be safe" (I know i'm still hardcoding a number,
.\" XXX: but at least it looks less like a decree and more like an estimate.
i386 アーキテクチャの場合、これが存在するファイルシステムには
少なくとも 3.2GB の空き領域が必要です。
.It Va CVSROOT
.Fx
CVS リポジトリの位置です。
このパス名は、実システムルートから参照され、
.Xr chroot 8
されたディレクトリツリーのルートからの参照では
.Em ありません。
.El
.Pp
オプションの変数は次のとおりです。
.Bl -tag -width ".Va NO_PREFETCHDISTFILES"
.It Va CD_PACKAGE_TREE
1 枚目および 2 枚目の CD-ROM イメージに追加する素材を含んだディレクトリです。
1 枚目のディスクの追加ファイルは
.Pa ${CD_PACKAGE_TREE}/disc1
に、2 枚目のディスクの追加ファイルは
.Pa ${CD_PACKAGE_TREE}/disc2
に置きます。
典型的には、この変数には、事前に呼び出した
.Cm package-split
ターゲットの出力ディレクトリを設定します。
.It Va CVSARGS
.Xr cvs 1
への追加の引数で、
.Dq Li "-qR"
といったサブコマンドの前に置かれます。
.It Va CVSCMDARGS
.Xr cvs 1
のコマンド
.Ic checkout
と
.Ic update
への追加の引数です。
例えば、この変数を
.Dq Li "-D '01/01/2002 00:00:00 GMT'"
に設定して
.Dq Li "make release"
または
.Dq Li "make rerelease"
すると、
.Xr cvs 1
はそれぞれ
2002 年 1 月 1 日 00:00:00 GMT のソースを
チェックアウトまたはアップデートするよう
.Xr cvs 1
に指示します。
.It Va DOC_LANG
構築すべき SGML ベースドキュメンテーションの、言語とコード。
設定されないと、使用可能なすべての言語に対し、
ドキュメンテーションが構築されます。
.It Va DOCRELEASETAG
ドキュメンテーションツリーのチェックアウト時に使用する CVS タグ。
通常、デフォルトで、ドキュメンテーションツリーの先頭が使用されます。
.Va RELEASETAG
がリリースタグを指定する場合、
関連付けられたリリースバージョンがデフォルトの代りに使用されます。
.It Va EXTLOCALDIR
.Pa ${CHROOTDIR}/usr/local
にコピーされるディレクトリ。
.It Va EXTSRCDIR
この変数で指定されるディレクトリは、
CVS checkout によって置かれたディレクトリの代わりに、
.Pa ${CHROOTDIR}/usr/src
へとコピーされます。
.Dq Li "rerelease"
では、このディレクトリはコピーされません。
cvs update が代わりに使用されます。
.It Va KERNEL_FLAGS
リリース構築中のカーネル構築時に、この変数の内容が
.Xr make 1
に渡されます。
例えば、この変数を
.Dq Li "-j 4"
に設定すると、
.Xr make 1
に最大 4 プロセスまで同時に実行することを指示することになります。
.It Va KERNELS
コンパイルして
.Dq base
ディストリビューションにインストールする、
追加のカーネル設定のリストを指定します。
各カーネルは、
.Pa /boot/<config>
にインストールされ、ローダから
.Dq Li "boot <config>"
でブートできるようになります。
.It Va LOCAL_PATCHES
.Pa /usr/src
に対するパッチファイル。
このパッチは、リリース構築を開始する前に、
.Xr chroot 8
環境で適用されます。
.It Va PATCH_FLAGS
パッチファイル
.Va LOCAL_PATCHES
を適用する際に用いる
.Xr patch 1
コマンドに渡す引数。
.It Va LOCAL_SCRIPT
.Xr chroot 8
環境で、ローカルパッチ適用直後に実行されるスクリプト。
.It Va MAKE_ISOS
これを定義した場合、CD-ROM ステージのディレクトリの内容から、
ブータブル ISO CD-ROM イメージを生成します。
.It Va NOCDROM
定義した場合、CD-ROM ステージのディレクトリを生成しません。
.It Va NODOC
定義した場合、
.Fx
ドキュメンテーションプロジェクトの SGML ベースのドキュメントを生成しません。
しかしながら、
.Pa src/share/doc
にある最小のドキュメンテーションセットから
.Dq doc
ディストリビューションが依然として作成されます。
.It Va NO_FLOPPIES
定義した場合、boot と fixit フロッピディスクイメージファイルを生成しません
(これらをサポートするプラットフォーム用)。
.It Va NOPORTS
定義した場合、Ports Collection はリリースから省略されます。
.It Va PORTSRELEASETAG
ports ツリーのチェックアウト時に使用する CVS タグ。
通常、デフォルトで、ports ツリーの先頭が使用されます。
.Va RELEASETAG
がリリースタグを指定する場合、
関連付けられたリリースバージョンがデフォルトの代りに使用されます。
.It Va NO_PREFETCHDISTFILES
この変数が定義されている場合、
.Xr chroot 8
環境に入る前に、リリース構築に必要な distfile がダウンロードされません。
.Va NO_PREFETCHDISTFILES
が設定されていない場合、取得が行われるのは、
.Va RELEASEDISTFILES
から distfile を取得完了した後であることに注意してください。
.It Va RELEASEDISTFILES
ports 用として、リリース構築に必要となる
ディストリビューションファイルが存在するディレクトリです。
これにより、低速なリンク経由で
distfiles をダウンロードする際に費やされる莫大な時間を
節約することができます。
.It Va RELEASENOUPDATE
.Dq Li "make rerelease"
の際にこの変数の値を設定した場合、
.Dq Li "cvs update"
によるソースコード更新を行ないません。
.It Va RELEASETAG
構築するリリースに相当する CVS タグ。
未定義の場合、CVS ツリーの
.Dv HEAD
.Dq ( "-CURRENT スナップショット" )
から構築されます。
.It Va SEPARATE_LIVEFS
live ファイルシステムを、1 枚目のディスクではなく、
専用の CD-ROM 上に記録します。
.It Va TARGET_ARCH
ターゲットとなるマシンプロセッサアーキテクチャ。
この環境変数は
.Dq Nm uname Fl p
の出力と同じものです。
異なるアーキテクチャ用にクロスビルドするにはこの環境変数を設定してください
.It Va TARGET
ターゲットとなるハードウェアプラットフォーム。
この環境変数は
.Dq Nm uname Fl m
の出力と同じものです。
ターゲットアーキテクチャをクロスビルドするのに必要な変数です。
例えば、PC98 マシン用にクロスビルドを行うには
.Va TARGET_ARCH Ns = Ns Li i386
と
.Va TARGET Ns = Ns Li pc98
が必要です。
.It Va WORLDDIR
.Dq Li "make buildworld"
が実行されたディレクトリです。
デフォルトは
.Pa ${.CURDIR}/..
であり、通常は
.Pa /usr/src
を指します。
.It Va WORLD_FLAGS
リリース構築中の世界 (world) 構築時に、この変数の内容が
.Xr make 1
に渡されます。
例えば、この変数を
.Dq Li "-j 4"
に設定すると、
.Xr make 1
に最大 4 プロセスまで同時に実行することを指示することになります。
.El
.Sh 関連ファイル
.Bl -tag -compact
.It Pa /etc/make.conf
.It Pa /usr/doc/Makefile
.It Pa /usr/doc/share/mk/doc.project.mk
.It Pa /usr/ports/Mk/bsd.port.mk
.It Pa /usr/ports/Mk/bsd.sites.mk
.It Pa /usr/share/examples/etc/make.conf
.It Pa /usr/src/Makefile
.It Pa /usr/src/Makefile.inc1
.It Pa /usr/src/release/Makefile
.It Pa /usr/src/release/${arch}/boot_crunch.conf
.It Pa /usr/src/release/${arch}/fixit_crunch.conf
.El
.Sh 使用例
以下のコマンド列は
.Fx 4.9
release を構築する際に使用したものです。
.Bd -literal -offset indent
cd /usr
cvs co -rRELENG_4_9_0_RELEASE src
cd src
make buildworld
cd release
make release CHROOTDIR=/local3/release BUILDNAME=4.9-RELEASE \\
  CVSROOT=/host/cvs/usr/home/ncvs RELEASETAG=RELENG_4_9_0_RELEASE
.Ed
.Pp
これらのコマンドを実行すると、FTP ディストリビューション用と、
CD-ROM ディストリビューション用として使える完全なシステムが
ディレクトリ
.Pa /local3/release/R
にできます。
.Pp
次のコマンド列は、ローカルで修正したソースツリーの
.Dq "-CURRENT スナップショット"
を構築するために使用できます。
.Bd -literal -offset indent
cd /usr/src
cvs diff -u > /path/to/local.patch
make buildworld
cd release
make release CHROOTDIR=/local3/release BUILDNAME=6.0-CURRENT \\
  CVSROOT=/host/cvs/usr/home/ncvs LOCAL_PATCHES=/path/to/local.patch
.Ed
.Sh 関連項目
.Xr cc 1 ,
.Xr crunchgen 1 ,
.Xr cvs 1 ,
.Xr install 1 ,
.Xr make 1 ,
.Xr patch 1 ,
.Xr uname 1 ,
.Xr md 4 ,
.Xr make.conf 5 ,
.Xr build 7 ,
.Xr ports 7 ,
.Xr chroot 8 ,
.Xr mtree 8 ,
.Xr sysctl 8
.Rs
.%T "FreeBSD Release Engineering"
.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/
.Re
.Rs
.%T "FreeBSD Release Engineering of Third Party Packages"
.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/
.Re
.Rs
.%T "FreeBSD Developers' Handbook"
.%O http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
.Re
.Sh 歴史
.Fx
1.x
では、チェックリストを手でチェックしながら、
.An Rod Grimes
によりコンパイルされ、リリースが作成されました。
不完全さはさておくにしても、このチェックリストには、
ファイルシステムを使えるようにするためのこまごまとした要求が大量に
含まれており、その実行は拷問としかいいようがないものでした。
.Pp
.Fx 2.0
リリースエンジニアリングを続ける中で、
.Pa src/release/Makefile
を直して、隔離された無菌環境でリリースを構築する際の退屈な作業の
ほとんどを自動的に行なえるようにすることに、顕著な努力が払われました。
.Pp
複数のブランチにまたがる 1000 回近くの改版を経て、
.Pa src/release/Makefile
の
.Xr cvs 1
ログには、リリースエンジニアたちが経験した苦難のいくばくかを示す
生々しい歴史の記録が刻み込まれています。
.Sh 作者
.Pa src/release/Makefile
は、もともとは
.An -nosplit
.An Rod Grimes ,
.An Jordan Hubbard ,
.An Poul-Henning Kamp
によって書かれました。
このマニュアルページは、
.An Murray Stokely Aq murray@FreeBSD.org
によって書かれました。
.Sh バグ
.Fx
ドキュメンテーションに対するインフラストラクチャ変更は頻繁で、
これが原因でセキュリティブランチ上のリリース構築が失敗することがあります。
最後に完全にサポートされた
.Fx
リリースから
ドキュメンテーションをチェックアウトし、リリース構築することで、
この問題を回避できます。
例:
.Pp
.Dl "make release RELEASETAG=RELENG_4_9 DOCRELEASETAG=RELEASE_4_9_0 ..."