ftp/arch/dcpam/ ディレクトリのメンテナンス手引

この文書について

この文書は ftp/arch/dcpam/ ディレクトリのメンテナンスの手引である.

このディレクトリに置かれている主な資源

ftp/arch/dcpam/ には, 主に以下の情報が置かれている.

各ディレクトリの詳細については, SIGEN.htm を参照のこと.

HTML 文書の管理方法

  • 原則的に HTML ファイルは RD 形式のテキスト (以下 RD ファイルと呼ぶ) から自動生成するようにする. Makefile を RD ファイルと同じディレクトリに置くことで, 以下のコマンドで自動的に htm.ja, htm.en が生成される. RD の文法については, 地球流体電脳倶楽部 dcmodel プロジェクト: モデルプロジェクトのための最低限 rd -- rd ファイルの作成 を参照のこと. 

    $ make

    ただし, カレントディレクトリ などでは, Makefile から Rakefile が呼び出されるようになっているため, 以下のコマンドで HTML 文書が生成される.

    $ rake
  • 原則的に, 実際に英語の文章を作成していなくとも, htm.ja と htm.en の 両方を作成できるような構造にしておく. (もちろん, 中身がない結果 htm.en が 作成されなくてもかまわない).
  • 具体的には, 日本語の部分は =begin JA, =end JA で囲み, 共通部分は =begin と =end で, 英語の部分は =begin EN, =end EN で くくる.

dcpam ソースの展開とシンボリックリンクの方針

  • ソースの公開は, dcpam/ 直下に dcpam<バージョン番号> としたディレクトリ を作成する.
  • ソースは, Git リポジトリから git archive コマンドで展開したものを置く.
    • git archive するためには, 展開の前にはタグを付ける必要がある. タグの付け方については, Git タグの付け方 参照のこと. git archive したソースは, Git タグ名と同名のディレクトリに格納する.
    • 例: dcpam5/dcpam5-20090319
  • ドキュメントが RD や RDoc などにより生成されるようになっている場合には, 展開されたソース内部でドキュメントの生成を行っておく.
  • 展開されたディレクトリから, tar コマンドで tgz ファイルを作成しておく.
  • 最新版には <dcpamバージョン番号>_latest, および <dcpamバージョン番号>_latest.tgz というシンボリックリンクを張る.
  • トップのディレクトリからは, その最新版のシンボリックリンクを参照するようにする.
  • 過去版が入手できるように, 過去版の tgz の入手とソースツリーを閲覧するための ページを用意する. ページは, ソース展開トップディレクトリ以下の index.htm と index.htm.en とする.

dcpam のバージョンに関して

  • dcpam の構造に大幅な改変を加える場合, タグに含まれるバージョン番号を増やす. dcpam0 からスタートし, 順次 dcpam1, dcpam2, …と作っていく.

Git タグの付け方

ソースツリーのタグは, 日付を表すタグ (日付タグと呼ぶ) と, バージョン名を表すタグ (バージョン名タグと呼ぶ) の両方を付けることとする. バージョン名タグは必須ではない *1.

日付タグ            バージョン名タグ
----------------------------------------
dcpam0-20040125
dcpam1-20040320     dcpam1-0_1
dcpam1-20040429
dcpam1-20040630     dcpam1-1_0
dcpam2-20040901     dcpam2-1_0
dcpam2-20050901     dcpam2-2_0
dcpam2-20050901-1   dcpam2-2_1     # 一日に複数回, 日付タグを設定する
                                   # 場合には, 接尾詞として "-1", "-2"
                                   # といったものを付記すること.

タグの付ける際には, Git 作業コピーのトップディレクトリで,

$ git tag -a dcpam5-20030901 -m "Snapshot on 2003/09/01."
             ^^^^^^^^^^^^^^^ ← これがタグ名となる.

等とする.

ソース展開の手順

ソース展開の手順として, まず手動での展開の手順を示す. Makefile を用いて自動化された展開の手順は, その後の ソース展開の手順 (自動) で示す.

展開の準備

展開のため, グループユーザと umask を設定する.

$ sg dcpam
$ umask 002				! group writable にする

展開するタグを確認する. Git の作業コピー内で, 以下のように コマンドした際, 以下のように表示されるのがタグである.

$ git tag

  Initial
  dcpam2-20050530: 1.8
  dcpam2-20050207-1: 1.4
            :

ソース展開の手順

git archive コマンドにより, 展開を行う. まず Git リポジトリに移動する. 

$ cd /GFD_Dennou_Club/ftp/arch/dcpam/git_repos/dcpam.git

展開先のディレクトリを作成する.

$ mkdir /GFD_Dennou_Club/ftp/arch/dcpam/dcpam5/dcpam5-20090325

日付タグの場合には以下のように展開する. 

$ git archive --format=tar --output=/GFD_Dennou_Club/ftp/arch/dcpam/dcpam5/dcpam5-20090325/archive.tar dcpam5-20090325

上の例では, /GFD_Dennou_Club/ftp/arch/dcpam/dcpam5/dcpam5-20090325/archive.tar が作成され, archive.tar にフラットにディレクトリ, ファイルが含まれている. archive.tar を展開し, dcpam5-20090325.tgz としてアーカイブし直す. 

$ cd /GFD_Dennou_Club/ftp/arch/dcpam/dcpam5/dcpam5-20090325
$ tar xvf archive.tar
$ rm archive.tar

ドキュメント, 依存関係ファイル, emacs tags ファイルの生成

展開したソースツリー以下でドキュメント等の生成を行う. 一度 configure したのち (ソースコードをコンパイルするわけでは ないので, 指定するライブラリは存在さえしていれば良い), make でドキュメント等を生成し, 最後に distclean で configure のキャッシュファイルなどを削除する.

$ cd dcpam5-20090325
$ ./configure \
              --with-netcdf=/usr/lib/libnetcdf-ffc5.a \
              --with-gtool5=/usr/lib/gtool5-ffc5/lib/libgtool5.a \
              --with-ispack=/usr/lib/libisp-ffc5.a \
              --with-spml=/usr/lib/spml-ssl2-ffc5/lib/libspml-ssl2.a \
(あるいは, $ bash compile_with_pkgs.sh)
$ make doc
$ make depend
$ make tags
$ make distclean

tgz 作成の手順

tgz を作成する.

$ cd ..
$ tar cvzf dcpam5-20090325.tgz dcpam5-20090325

シンボリックリンクの貼り換え

古いシンボリックリンクを削除し, 新しいシンボリックリンクを作成. 

$ rm dcpam5_latest	     ! 古いリンクを一旦削除
$ rm dcpam5_latest.tgz
$ ln -s dcpam5-20090325 dcpam5_latest
$ ln -s dcpam5-20090325.tgz dcpam5_latest.tgz

過去版アーカイブリストの更新

$ vi index.htm

  (書き換え作業)

$ vi index.htm.en

  (書き換え作業)

dcpam トップページに記載される dcpam の最新バージョンの書き換え

$ cd ..
$ vi index.rd

  (書き換え作業)

$ make

以下は cvs 時代の文書

このディレクトリに置かれている主な資源

ftp/arch/dcpam/ には, 主に以下の情報が置かれている.

各ディレクトリの詳細については, SIGEN.htm を参照のこと.

HTML 文書の管理方法

  • 原則的に HTML ファイルは RD 形式のテキスト (以下 RD ファイルと呼ぶ) から自動生成するようにする. Makefile.rd2html を RD ファイルと同じディレクトリに置くことで, 以下のコマンドで自動的に htm, htm.en が生成される. RD の文法については, 地球流体電脳倶楽部 dcmodel プロジェクト: モデルプロジェクトのための最低限 rd -- rd ファイルの作成 を参照のこと. 

    $ make -f Makefile.rd2html

    ただし, カレントディレクトリ などでは, Makefile から Makefile.rd2html が呼び出されるようになっているため, 以下のコマンドで HTML 文書が生成される.

    $ make
  • 原則的に, 実際に英語の文章を作成していなくとも, htm と htm.en の 両方を作成できるような構造にしておく. (もちろん, 中身がない結果 htm.en が 作成されなくてもかまわない).
  • 具体的には, 日本語の部分は =begin JA, =end JA で囲み, 共通部分は =begin と =end で, 英語の部分は =begin EN, =end EN で くくる.

dcpam ソースの展開とシンボリックリンクの方針

  • ソースの公開は, dcpam/ 直下に CVS プロジェクト名と同名のディレクトリ を作成する.
  • ソースは, CVS リポジトリから cvs export コマンドで展開したものを置く.
    • cvs export するためには, 展開の前には CVS タグを付ける必要がある. タグの付け方については, CVS タグの付け方 参照のこと. cvs export したソースは, CVS タグ名と同名のディレクトリに格納する.
    • 例: dcpam5/dcpam5-20090319
  • ドキュメントが RD や RDoc などにより生成されるようになっている場合には, 展開されたソース内部でドキュメントの生成を行っておく.
  • 展開されたディレクトリから, tar コマンドで tgz ファイルを作成しておく.
  • 最新版には <CVSプロジェクト名>_current, および <CVSプロジェクト名>_current.tgz というシンボリックリンクを張る.
  • トップのディレクトリからは, その最新版のシンボリックリンクを参照するようにする.
  • 過去版が入手できるように, 過去版の tgz の入手とソースツリーを閲覧するための ページを用意する. ページは, ソース展開トップディレクトリ以下の index.htm と index.htm.en とする.

dcpam のバージョンに関して

  • dcpam の構造に大幅な改変を加える場合, 新規 CVS プロジェクトを開始する. dcpam0 からスタートし, 順次 dcpam1, dcpam2, …と作っていく.

CVS タグの付け方

ソースツリーのタグは, 日付を表すタグ (日付タグと呼ぶ) と, バージョン名を表すタグ (バージョン名タグと呼ぶ) の両方を付けることとする. バージョン名タグは必須ではない *2.

日付タグ            バージョン名タグ
----------------------------------------
dcpam0-20040125   
dcpam1-20040320     dcpam1-0_1
dcpam1-20040429   
dcpam1-20040630     dcpam1-1_0
dcpam2-20040901     dcpam2-1_0
dcpam2-20050901     dcpam2-2_0
dcpam2-20050901-1   dcpam2-2_1     # 一日に複数回, 日付タグを設定する
                                   # 場合には, 接尾詞として "-1", "-2"
                                   # といったものを付記すること.

タグの付ける際には, CVS 作業コピーのトップディレクトリで,

$ cvs tag dcpam5-20030901
          ^^^^^^^^^^^^^^^ ← これがタグ名となる.

等とする.

ソース展開の手順 (手動)

ソース展開の手順として, まず手動での展開の手順を示す. Makefile を用いて自動化された展開の手順は, その後の ソース展開の手順 (自動) で示す.

展開の準備

展開のため, グループユーザと umask を設定する.

$ sg dcpam
$ umask 002				! group writable にする

展開するタグを確認する. cvs の作業コピー内で, 以下のように コマンドした際, 以下のように表示されるのがタグである.

$ cvs log ファイル

  symbolic names:
         dcpam2-20050530: 1.8
         dcpam2-20050207-1: 1.4
                      :

ソース展開の手順

cvs export コマンドにより, 展開を行う. まず CVS リポジトリと同名のディレクトリに移動する. 

$ cd /GFD_Dennou_Club/ftp/arch/dcpam/dcpam5

日付タグの場合には以下のように展開する. 

$ cvs -d /GFD_Dennou_Club/ftp/arch/dcpam/cvsroot export -r "dcpam5-20090325" dcpam5

バージョン名タグの場合は以下のようになる.

$ cvs -d /GFD_Dennou_Club/ftp/arch/dcpam/cvsroot export -r "dcpam5-1_1" dcpam5

ソースは, 今回の例であれば dcpam5 ディレクトリ以下に展開される. その後, ディレクトリ名をタグ名 (dcpam5-20090325 等) に変更し, SIGEN ファイルを作成する.

ドキュメント, 依存関係ファイル, emacs tags ファイルの生成

展開したソースツリー以下でドキュメント等の生成を行う. 一度 configure したのち (ソースコードをコンパイルするわけでは ないので, 指定するライブラリは存在さえしていれば良い), make でドキュメント等を生成し, 最後に distclean で configure のキャッシュファイルなどを削除する.

$ cd dcpam5-20090325
$ ./configure \
              --with-netcdf=/usr/lib/libnetcdf-ffc5.a \
              --with-gtool5=/usr/lib/gtool5-ffc5/lib/libgtool5.a \
              --with-ispack=/usr/lib/libisp-ffc5.a \
              --with-spml=/usr/lib/spml-ssl2-ffc5/lib/libspml-ssl2.a \
$ make doc
$ make depend
$ make tags
$ make distclean

tgz 作成の手順

tgz を作成する.

$ cd ..
$ tar cvzf dcpam5-20090325.tgz dcpam5-20090325

シンボリックリンクの貼り換え

古いシンボリックリンクを削除し, 新しいシンボリックリンクを作成. 

$ rm dcpam5_current	     ! 古いリンクを一旦削除
$ rm dcpam5_current.tgz
$ ln -s dcpam5-20090325 dcpam5_current
$ ln -s dcpam5-20090325.tgz dcpam5_current.tgz

過去版アーカイブリストの更新

$ vi index.htm

  (書き換え作業)

$ vi index.htm.en

  (書き換え作業)

dcpam トップページに記載される dcpam の最新バージョンの書き換え

$ cd ..
$ vi index.rd

  (書き換え作業)

$ make

ソース展開の手順 (自動)

Makefile を用いて, 上記作業の一部を自動化した際の方法を以下に示す.

※ 現在はこの自動化をオフにしてあります, 使用する場合には /ftp/arch/dcpam/dcpam5/Makefile を編集してください.

展開の準備

展開のため, グループユーザと umask を設定する.

$ sg dcpam
$ umask 002		! group writable にする

展開するタグを確認する. cvs の作業コピー内で, 以下のように コマンドした際, 以下のように表示されるのがタグである.

$ cvs log ファイル

  symbolic names:
         dcpam2-20050530: 1.8
         dcpam2-20050207-1: 1.4
                  :

Current_CVS_Tag.mk の編集

<URL:Current_CVS_Tag.mk> の DCPAM5TAG を展開する版のタグに変更する. 

$ vi Current_CVS_Tag.mk

DCPAM5PROJ  = dcpam5
DCPAM5TAG   = $(DCPAM5PROJ)-20090325

make の実行

CVS プロジェクト名ディレクトリ (例: dcpam5/ ) に移動し, 以下のようにコマンドする.

$ make export

ソースコードの展開, およびソースコード内部でのドキュメント等の生成, tgz パッケージの作成とシンボリックリンクの張替え, SIGEN ファイルの作成, トップページのバージョン情報の置きかえが行われる.

これは上記手動での更新における ソース展開の手順, ドキュメント, 依存関係ファイル, emacs tags ファイルの生成, tgz 作成の手順, シンボリックリンクの貼り換え, 過去版アーカイブリストの更新, dcpam トップページに記載される dcpam の最新バージョンの書き換え の作業に相当する.

確認

CVS プロジェクト名ディレクトリ (例: dcpam5/ ) 以下に, CVS タグ名 のディレクトリと <CVSタグ名>.tgz の TGZ パッケージが作成され, そのディレクトリに <CVSプロジェクト名>_current, その TGZ パッケージに <CVSプロジェクト名>_current.tgz というシンボリックリンクが貼られていることを確認する.

また CVS プロジェクト名ディレクトリ (例: dcpam5/ ) 中の index.htm, index.htm.en のアーカイブリストが更新されている ことを確認する.

最後に dcpam トップページ の以下の "******" の部分が Current_CVS_Tag.mk の編集 で 変更した値になっていることを確認する.

(Version: *****)

Footnotes

*1 (2005/04/05 石渡) バージョン名タグとして "dcpam2-1.0" と付けようと思ったら cvs [tag aborted]: tag `dcpam2-1.0' must not contain the characters `$,.:;@' と言われたよ! どうやら "$", ",", ".", ":", ";", "@" といった文字は含めてはいけないらしい!
*2 (2005/04/05 石渡) バージョン名タグとして "dcpam2-1.0" と付けようと思ったら cvs [tag aborted]: tag `dcpam2-1.0' must not contain the characters `$,.:;@' と言われたよ! どうやら "$", ",", ".", ":", ";", "@" といった文字は含めてはいけないらしい!