ソースコード・リテラシーのススメ

第3回ドキュメントをどう使うか?

前回までにmaninfoなど、伝統的なUNIX/Linuxのオンラインドキュメントシステムについて解説してきました。これらのドキュメントシステムは必要十分な機能を備えてはいますが、ターミナルソフトウェアからコマンドで起動しなければならなかったり、manとinfoで操作方法が異なったりと、不便な部分もあります。そのため、GNOMEKDEといった最近のデスクトップ環境では、より見栄えのいい、統合的なドキュメントシステムを提供しています。

新しいドキュメントシステム

伝統的なオンラインドキュメントはrofftexinfoといった特定のソフトウェアに依存する形式で記述されているのに対し、新しいドキュメントシステムは汎用的なXML形式で記述され、Webブラウザ等から柔軟に利用できるようになっています。たとえば、KDEでは「ヘルプセンター(khelpcenter)」を用いればWindowsと同様に「スタートメニュー」から「ヘルプ」を選んで登録されている各種ドキュメントを閲覧することが可能ですし、それぞれのアプリケーションの「ヘルプ」ボタンをクリックすることで、そのアプリケーションに関するドキュメントを直接読むこともできます。また、KDEのドキュメントのみならず、UNIXのmanページやinfoページも調べることができます。

図1 KDEヘルプセンター経由のmanページ
図1 KDEヘルプセンター経由のmanページ

KDEではKonquerorを用いてmanページやinfoページを表示することも可能になっており、Konquerorでmanページを表示する場合はURLとしてman:/を、infoページを表示する場合はinfo:/を指定すれば、インストールされているmanやinfoの一覧が表示され、読みたいファイルを選択すれば、その内容が適切に整形されて表示されます。たとえばinfo:/libtool/Creating object filesを指定して、libtoolのinfoページを見ると、図2のようになります。

図2 Konqueror経由のinfoページ
図2 Konqueror経由のinfoページ

たまたま手元でKDE環境のテストをしていたため、今回はKDE環境を元に紹介しましたが、同等の機能はGNOME環境でも提供されています。これら新しいデスクトップ環境では、manやinfoといったページ形式やコマンドの操作方法の違いを気にせず、Webブラウザ経由で各種オンラインドキュメントを参照できるため、初心者の方でも使いやすいことでしょう。

各種ドキュメントの使い方

昨年秋にPlamo-4.21をリリースして以来、Plamo Linux以外の仕事に忙殺されていてメンテナンスをサボっていましたが、最近になってようやくPlamoの作業に多少時間を使えるようになりました。現在は、近日中のメンテナンスリリースに向けて、滞っていた各種更新作業に追われています。そのような作業の現場で、今までに紹介してきたドキュメントをどのように活用しているかを紹介してみます。

コマンドのオプション確認

/etc/passwdファイルには、登録されているユーザのログイン名やホームディレクトリ、使用するシェルなどの情報が記録されています。インストール直後の初期状態で、どのようなシェルやホームディレクトリが登録されているかを調べたくなりました。

ご存知のように、/etc/passwdファイルは1行が1ユーザに対応し、各行は“:”(コロン)で区切られた7つの欄から構成されています。

/etc/passwdファイルの例
 root:x:0:0::/root:/bin/bash
 bin:x:1:1:bin:/bin:
 daemon:x:2:2:daemon:/sbin:
 ...

ホームディレクトリの情報は6つめの欄、シェルの位置は7つめの欄に記載されているので、まずこのファイルから7つめの欄を取り出す方法を考えます。

Perlならば各行をsplit(/:/)で分割、awkならばフィールドセパレータ FS=’:’の指定で何とかなりそうですが、スクリプトを書くのも面倒なので、より簡単なUNIXのcutコマンドを使おうと考えました。cutコマンドは各欄の区切りをオプションで指定できたはずなので、⁠欄区切りを指定するオプションは-sだったかな?」とcutコマンドを使ってみました。

 % cut -s':' -f7 /etc/passwd 
 cut: オプションが違います -- :
 詳しくは `cut --help' を実行して下さい.

おっと、⁠オプションが違う」と怒られてしまいました。では、指示されているように cut --help を実行してみます。

 % cut --help
 使用法: cut [オプション]... [ファイル]...
 ファイルの各行から選択した部分だけを切り出して, 標準出力に表示します.
 
 長いオプションに必須の引数は短いオプションにも必須です.
   -b, --bytes=LIST        LIST に指定したバイト位置の文字を出力
   -c, --characters=LIST   LIST に指定した文字位置だけを出力
   -d, --delimiter=DELIM   フィールドの区切り文字を TAB の代わりに DELIM に
   -f, --fields=LIST       LIST に指定したフィールドだけを出力; -s オプション
                           が指定されなければ, 区切り文字を含む行も表示
 ....

これを見ると各欄(フィールド)の区切り文字はデフォルトではTAB変更するためには-dオプションだということがわかります。そこで先のコマンドの-sを-dに代えて実行してみます。

 % cut -d':' -f7 /etc/passwd
 /bin/bash
 
 /bin/sync
 /sbin/shutdown
 /sbin/halt
 ....

今度はうまくいったようです。こうして取り出したログインシェルをsortで並べかえて、使われているコマンドの頻度を調べたり、パイプ経由で xargs ls -lに流しこんで、想定しているコマンドが存在するか、パーミッション等は大丈夫かといった点を確認しました。

新しいパッケージの作成

昨年の秋にPlamo-4.21を公開してから、あっと言う間に10ヵ月近くの月日が流れてしまいました。この間に収録しているソフトウェアの多くがバージョンアップされています。これらバージョンアップにあわせてパッケージを更新していくのがディストリビュータの主な仕事です。

たいていのソフトウェアでは2.10や0.8.6のようにピリオドやハイフンで区切られた2桁、あるいは3桁の数字(バージョン番号)でバージョンを管理しています。これらの数字は左から、メジャー番号、マイナー番号、リリース番号などと呼ばれ、以前のバージョンからの変更点の多寡によってどの数字を更新するかが判断されます。

どの程度の変更でバージョン番号のどの部分を更新するかは開発者に任されているため、バージョン番号の付け方はソフトウェアプロジェクトごとに異なっているのが現実ではありますが、大まかな合意としては以下のようなルールが存在するでしょう。

メジャー番号の更新
以前のバージョンと互換性が取れなくなるほどの大きな更新が加えられた場合
マイナー番号の更新
新しい機能等は追加されたものの、以前のバージョンとの互換性は保たれている場合
リリース番号の更新
機能的な追加や変更はほとんどなく、プログラムのバグ修正程度の場合

このようなルールを知っておけば、バージョン番号のどの部分が更新されたかによって、パッケージを更新する際の対応を変えることができます。たとえば、リリース番号の更新の場合はビルド用スクリプトのバージョン番号を変える程度で対応できるでしょうし、マイナー番号の更新の場合は今までになかった機能が追加されていないかを調べた方がいいでしょう。またメジャー番号が更新された場合は、0からビルドスクリプトを作り直すつもりで調べ直す必要があるでしょう。

ドキュメント参照の実例

以下に、マイナー番号が2つほど更新されたbashをパッケージ化する際に、どのようなドキュメントを参照したかの例を紹介します。

Plamo-4.21ではbash-3.0を使っていましたが、bashの最新版を調べると3.2というバージョンがリリースされていました。bash-3.2はメジャー番号は3で同じものの、マイナー番号が従来使っていたものから2つほど飛んでいるので、機能的な変更や修正が行なわれている可能性があります。そこでソースコードを展開した後、まずREADMEファイルを調べてみました。

  Introduction
 ============
 
 This is GNU Bash, version 3.2.  Bash is the GNU Project's Bourne
 Again SHell, a complete implementation of the POSIX.2 shell spec,
 but also with interactive command line editing, job control on
 ....
 (このソフトウェアはGNU Bashバージョン3.2です。BashはGNUプロジェクト製の
  Bourne Again Shellで、POSIX.2のシェルに必要な機能を完全に満した上、
  対話的な行編集やジョブ制御等の機能を持ち...)

このファイルをざっと見る限り、ソフトウェアの簡単な紹介しか記述されておらず、とくに注意すべき点についての記載はありませんでした。まず目を通すべきREADMEファイルに重要な注意事項等が記されていないということは、過去のバージョンとの重大な非互換性などは存在しないことを意味しているのでしょう。そこで多少は安心して、次にNewsファイルに目を通しました。

 This is a terse description of the new features added to bash-3.2 since
 the release of bash-3.1.  As always, the manual page (doc/bash.1) is
 the place to look for complete descriptions.

 (これはbash-3.1の公開以降に加わったbash-3.2の新機能の簡単な紹介です。
  従来通り、完全な説明についてはマニュアルページ(doc/bash.1)を参照すること)
 
 1.  New Features in Bash

 a.  Changed the parameter pattern replacement functions to not anchor the
     pattern at the beginning of the string if doing global replacement - that
     combination doesn't make any sense.
 
 b.  When running in `word expansion only' mode (--wordexp option), inhibit
     process substitution.
 ....
  (1. Bashの新機能
   a. 引数のパターン置換機能を変更し、グローバルな置換が行なわれる場合は文字列の先頭
      パターンのみに注目しないようにした。そのような組み合わせは意味を無さない。
   b. 「単語展開のみ」モード(--wordexpオプション)で起動した場合は、プロセス置換を行なわない
      ようにした ....)

このファイルにはbashの各バージョンに追加された新機能や変更点がリストアップされています。3.0に対し、3.1、3.2で新しく追加された機能はそれほど大きなものではないようなので、多少の修正は必要なものの、従来のビルドスクリプトを流用してコンパイルできそうです。

次にINSTALLファイルを見て、コンパイルやインストール時に注意すべき点があるかを調べました。

 Basic Installation
 ==================
 
 These are installation instructions for Bash.

 The simplest way to compile Bash is:
 ...

 (インストールの基本
  以下はBashのインストール方法の指示である。
  Bashをコンパイルするもっとも簡単な方法は:...)

このファイルの中にはconfigureスクリプトを動かす際のオプションの指定についての記載がありました。

 Optional Features
 =================
 
 The Bash `configure' has a number of `--enable-FEATURE' options, where
 FEATURE indicates an optional part of Bash.  There are also several
 `--with-PACKAGE' options, where PACKAGE is something like `bash-malloc'
 ...

 (オプション機能
  Bashに付属のconfigureスクリプトはさまざまな --enable-FEATURE オプショ
  ンを指定可能である。ここで指定するFEATUREはBashの機能のうち取捨選択可
  能な部分を意味する。また --with-PACKAGE オプションも指定可能で、
  PACKAGE の部分は bash-malloc 等の...)

configureスクリプトで指定できる機能はconfigureを--helpオプションを付けて起動して調べないといけない場合が多いのですが、bashの場合はドキュメントの中で指定可能な機能についての説明がなされていました。このファイルで説明されている指定可能な機能をざっと眺めてみると、Plamoのビルドスクリプトでは使っていない--enable-multibyteというオプションが目につきました。

 `--enable-multibyte'
      This enables support for multibyte characters if the operating
      system provides the necessary support.

 (OSが必要な機能を提供していれば、マルチバイトキャラクターに対応する)

今回のビルドにはこのオプションを指定しようと思いつつ、他にも指定しておけば便利な機能がないかと ./configure --help を実行して可能な設定を調べてビルド時のオプションを検討し、以前使っていたスクリプトを修正して、新しいバージョンのパッケージを作成しました。作成したパッケージは手元の環境でインストールテストし、再起動して各種スクリプト類の動作を確認した上でFTPサーバに登録し、新しいバージョンとして公開しました。

今回の例ではかなり詳しくドキュメントを調べているように見えるかも知れませんが、実際は各ドキュメントの先頭部分を少し読んでみて、残りは必要そうな部分を飛し読みしている程度なので、それぞれのファイルにかけた時間は数分程度でしょう。

開発者たちの努力のおかげで、最近の多くのソフトウェアは./configure &&make installだけでインストールできるようになっています。しかしながら、最初に少しだけ時間をかけてREADMEやINSTALLをなどを眺め、そこに上げられている注意点を把握しておくだけで、ビルド時のトラブルはずいぶん少なくなりますし、使用中に何かトラブルが発生した場合でもよりスムーズに対応できるようになるでしょう。

READMEに代表されるドキュメントファイルには開発者たちのぜひ伝えたいメッセージが簡潔に書かれています。新しいソフトウェアを使う前には多少面倒でもREADME程度には目を通すようにしましょう。その方が結局は時間のロスが少なくなるはずです。

おすすめ記事

記事・ニュース一覧