Linux開発環境構築: `what`コマンドによるスクリプト管理と文書化
はじめに
この記事では、agla shell utilsに含まれるwhatコマンドを使って、スクリプトを管理する方法を紹介します。
whatコマンドは、whatdocコメントを解釈し、各シェルスクリプトの説明を提供し、スクリプトの理解を容易にします。
この記事では、whatの使い方を紹介するとともに、whatコマンド用コメントwhatdocの書き方を解説します。
各種スクリプトや設定ファイルにwhatdocコメントを追加して、これらのファイルの理解を容易にしましょう。
キーワード
以下で、使用する重要なキーワードを説明します。
-
whatコマンド:
スクリプト内のwhatdocコメントを解析して情報を表示するツール。スクリプトの目的や使用方法を簡単に把握できる -
whatdocコメント:
特定のフォーマットで書かれたコメント、スクリプトの説明やバージョン情報などを含み、スクリプトの理解を容易にする -
SCCS(Source Code Control System):
UNIX系OS で使われていたバージョン管理システム。whatコマンドの由来となっている
1. whatコマンド の基本機能
whatコマンドは、指定したシェルスクリプトに関する情報を出力します。
このセクションでは、whatコマンドの使用方法を説明します。
1.1 whatコマンドの基本
what コマンドは、agla shell utilsに含まれるシェルスクリプト管理用のユーティリティです。
このコマンドは、シェルスクリプトや設定ファイル中のwhatdocコメントを解釈し、ファイルの情報を提供します。
次のようにwhatdocコメントを追加したスクリプトをwhatコマンドで解析することで、スクリプトの概要を簡単に表示できます。
#!/usr/bin/env bash
#
# @(#) : Sample script to demonstrate whatdoc
# 注意: このスクリプトは`whatdoc`のデモンストレーションです
このスクリプトに対して、whatコマンドを実行すると次のようになります:
$ what sample.sh
sample.sh: (v 1.0.0) : Sample script to demonstrate whatdoc
このように、シェルスクリプトに関する情報を簡単に得ることができます。
1.2 whatコマンドの基本操作
what コマンドの使い方は簡単です。
what <ファイル名>
で、指定したファイルのバージョンと簡単な説明を出力します。
whatコマンドの場合は:
$ what what
what ( v0.0.5 ) : display shell script usage
となります。
1.3 whatコマンドの応用操作
'-d'オプションで、スクリプトの詳細な説明を表示します。
これにより、より深い理解が可能になります。
このときのコマンドは:
what -d <ファイル名>
となります。
what コマンドの場合は:
$ what -d what
what <file>
print shell script usage
-d print usage created by header
-v print version
-h -? print this usage
THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND.
THE ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER.
となります。
2. whatコマンドのインストール方法
2.1. whatコマンドのインストール手順
what コマンドは、次の手順でインストールします:
-
what コマンドのダウンロード
下記のコマンドを実行して、what コマンドをダウンロードする。wget https://raw.githubusercontent.com/atsushifx/agla-shell-utils/main/agla/what -
what コマンドのインストール
ダウンロードしたwhatコマンドをpathのとおったディレクトリにコピーする。cp what ~/bin -
実行権限の追加:
コピーしたwhatコマンドに実行権限を追加する。chmod +x ~/bin/what
以上で、whatコマンドが使えるようになります。
3. whatdocコメントの基本
whatコマンドでコマンドの説明を出力するには、ファイル内に適切なwhatdocコメントを追加する必要があります。
whatdocコメントを適切に使用することで、スクリプトの目的、使用方法などが簡単に把握できます。
これにより、スクリプトのメンテナンスが格段に容易になります。
3.1 whatdocコメントの基本フォーマット
whatdoc コメントは、以下のようなフォーマットで記述します:
#!/usr/bin/env bash
#
# @(#) : display shell script usage
#
# @version 1.0.0
# @author Furukawa, Atsushi <atsushifx@aglabo.com>
# @date 2023-12-27
# @license MIT
#
# @desc
#
# what <file>
# print shell script usage
#
# -d print usage created by header
# -v print version
# -h -? print this usage
#
#
###
#
# THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND.
# THE ENTIRE RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE USER.
#
#
注意事情:
whatdoc コメントはヘッダー部に記述します。shebangのあとに#コメントを続ける必要があります。
whatdoc コメントは、@(#)からはじまります。
@(#)は、SCCSという UNIX系OS で使われてたバージョン管理システム用のヘッダーです。
ここから、ヘッダーコメントの最終行までが whatdoc コメントになります。
2.2 whatdocコメントのヘッダー (short desc)
@(#)ではじまるコメントは、コマンドの簡単な説明となります。
what <ファイル名>で出力される説明は、ここのコメントとなります。
2.3 コメントタグの一覧
whatdoc コメントでは、@から始まるキーワードをコメントタグとして認識します。
現在、what コマンドでは@versionしか使っていません。
シェルスクリプトの管理のためには、@authorなどのほかのタグも書いておくといいでしょう。
コメントタグの一覧を下記に載せておきます:
| コメントタグ | 記法 | 説明 | 備考 |
|---|---|---|---|
| @(#) | @(#) : <短い説明> | シェルスクリプトの簡単な説明 |
whatコマンドで、スクリプトの簡単な説明として利用される |
| @version | @version <バージョン番号> | バージョン番号をセマンティックバージョニングで記述する | what の short descにバージョン番号を出力 |
| @author | @author <氏名> | スクリプトの作成者を記述 | |
| @date | @date <日時> | スクリプトの作成日時を記述 | |
| @license | @license <ライセンス> | 主にOSSのライセンスを略号で記述 |
ライセンス情報を提供する |
| @desc | @desc ... | スクリプトの長い説明を複数行のコメントで記述 | 詳細は、後述 |
2.4 @descタグ (long descの使用 )
@descタグは特殊で、複数行に渡ってコメントを記述します。
@descタグ以降の、行頭に#をつけたコメントをヒアドキュメントとして認識し、残りのヘッダコメント
が@descタグによるドキュメントとなります。
# @author Furukawa, Atsushi <atsushifx@aglabo.com>
# @date 2023-12-27
# @license MIT
#
# @desc
+-#
| # what <file>
| # print shell script usage
| #
+-##
.
.
<以下、shellscript本文>
上記の、+ ... +の行が、long descです。
注意:
@descタグは、whatdoc コメントの最後につける必要があります。
おわりに
この記事では、whatコマンドの使い方と、コマンドを使うためのコメントの書き方を紹介しました。
各種スクリプトや、bashrcなどの設定ファイルに whatdoc コメントを記述することで、スクリプトや設定ファイルの理解が容易になります。
whatコマンドを活用すれば、Linux 環境の生産性を向上できます。
それでは、Happy Hacking!
Discussion