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

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

この記事を読むのに必要な時間:およそ 4 分

ドキュメント参照の実例

以下に,マイナー番号が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で新しく追加された機能はそれほど大きなものではないようなので,多少の修正は必要なものの,従来のビルドスクリプトを流用してコンパイルできそうです。

しばらく前の話になりますが,bash-2.05bからbash-3.0へ更新された際には,シェルスクリプトのテストコマンドの中で =~ という正規表現を利用可能な比較式が追加され,一部のディストリビューションではさっそくこの機能をサービスの初期化用スクリプトなどに使っていました。
bashのシェルスクリプト機能が強化されたことを知らずに,新しいサービス初期化用スクリプトのみを持ってくると,手元の環境ではエラーになり起動できません。⁠シェルスクリプトなのにヘンだなぁ...」と首をひねりつつ,エラーになる場所を絞り込んでいくと,シェルスクリプトでは見覚えのない =~ なんて比較式が目につきました。⁠こんな比較式,シェルスクリプトで使えたっけ?」とあれこれ調べていったら,bash-3.0のNEWSファイルにこの旨が記載されており,3.0以降の新機能だったことがわかった,という経験をしたことがあります。

次に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程度には目を通すようにしましょう。その方が結局は時間のロスが少なくなるはずです。

著者プロフィール

こじまみつひろ

Plamo Linuxとりまとめ役。もともとは人類学的にハッカー文化を研究しようとしていたのが,いつの間にかミイラ取りがミイラになってOSSを仕事にするようになってしまいました。最近はスペシャリスト養成を目的とした専門職大学院で教壇に立ったりもしています。

URLhttp://www.linet.gr.jp/~kojima/Plamo/index.html