ja/Projects/wija

概要

wija およびそのプラグインは Java 言語 (J2SE; Java 2 Standard Edition) により記述されています*1。 J2SE による開発には JDK (J2SE Development Kit) が必要です (Mac OS X には付属しています)。 また、ビルドは ant ツールにより行われることを想定しています。

Media Art Online で開発・配布されるソフトウェアおよび web サイトは、 wija およびそのプラグインを含め、 Perforce ソフトウェアによってバージョン管理されています。 Perforce は商用ソフトウェアですが、Media Art Online では、現在、オープンソースの開発目的に限り、 40ユーザのライセンスを Perforce 社から無償で取得しています (将来的にはユーザ数を増やしてもらえる可能性もあります)。 また、Media Art Online での開発を行わず、参照・取得するだけの目的であれば、 どなたでも Perforce ソフトウェア (クライアントソフトウェアは無償) を用いて開発中の最新のソースコードを取得できます。

Perforce の 40ユーザのライセンスを活用するために、 また、開発上の様々な議論を行うために、wija-devel(-en) メーリングリストが用意されています (wija-devel-en では英語のみを用います)。 wija-devel(-en) のメンバには、 バージョン管理データベースへの書き込みが許可された Perforce ユーザアカウントが割り振られます。

wija-devel(-en) メーリングリストに参加されたい方は、下記までご連絡ください。

mailto.png

Nightly build (夜ごとのビルド)

wija-devel(-en) のメンバは、 Perforce によるレビューメッセージを受け取ることで、 更新があったときに最新のソフトウェアやドキュメンテーションを試用できます。

ソフトウェア開発の場合

しかし、Perforce で取得できるのはソースコードですので、実際に試用するためには、 開発ツールを用いてソフトウェアをビルドする必要があります。 その操作は、ソフトウェアの開発に携わっていない人にとっては煩雑だと考えられます。

そこで、開発ツールを用いない方でも、更新があったときにそれを試せるように、 内部リリースを行います。

この内部リリースは、更新があった翌日の、日本時間の朝 8:00 までに行われます。 以下の URL から内部リリースをダウンロードできます。

内部リリースは、対応する最新の Perforce change 番号を含んだ次のファイル名で、 圧縮アーカイブファイルとして提供されます。

wija-change番号.zip

ドキュメント開発の場合

同様に、ヘルプページも「オムニドキュメント」という形式で書かれたソースコードが バージョン管理の対象となりますので、ご自身のコンピュータ上で web ページとして閲覧するためには開発ツール (ヘルプページ作成ツール) によるビルドが必要です。 しかし、この場合、Media Art Online のスタッフも web サーバ上でビルドを行いますので (将来的には自動化したいですが)、しばらくすると、 次の URL から更新内容が反映されたページを閲覧できるようになります。

試用した結果、問題がなければ更新内容が http://www.media-art-online.org/wija/ に反映されます。

開発ツール

  • JDK (http://java.sun.com/ )
    • Java 2 Standard Edition 開発キット
    • Mac OS X には付属しています (最新版をソフトウェア・アップデートにより取得してください)
  • Perforce (http://www.perforce.com/ )
    • ソフトウェア構成管理ツール
    • このページでは p4 (コマンドライン版クライアントソフトウェア) を前提に解説します
    • 詳細については上記 URL から取得できるドキュメンテーションを参照してください
  • Ant (http://ant.apache.org/ )
    • ビルドツール
  • helpgen (Media Art Online で開発しており、Perforce で取得できます)
    • ヘルプページ作成ツール

Perforce の導入と設定

Perforce の概要

Perforce は、離れた場所にいて、別々のコンピュータを使っている人々が、 インターネットを用いてひとつのソフトウェアやドキュメンテーションを開発することを支援するソフトウェアです。 Perforce では、ソフトウェアやドキュメンテーションを構成するファイルのひとつひとつについて、 バージョンを管理できます。

depot (デポ)
Perforce では、サイト毎に用意される Perforce サーバ (Media Art Online では perforce.media-art-online.org) に depot と呼ばれるデータベースが置かれます。このデータベースに、そのサイトで開発されるすべてのソースコードが更新履歴とともに格納されます。depot では、みなさんのコンピュータと同様に、ファイルの情報が階層ディレクトリにより整理されています。
クライアント
Perforce を用いるユーザは、自分が関係する開発項目毎に、クライアントと呼ばれるマッピングを定義します。これは、depot 上のどの部分が、ユーザのコンピュータのローカルディスクのどのディレクトリにマップされるかを定義するものです。
ワークスペース
depot 上のある部分がマップされている、ローカルディスク上のディレクトリをワークスペースと呼びます。Perforce を用いるユーザは、depot からワークスペースに最新バージョンのファイルをダウンロードして、ファイルを追加したり、既存のファイルに変更を施して、それらを depot に提出します。
レビューメッセージ
Perforce ユーザは、自分が関係する開発項目に更新があった場合に、メールにて通知を受けるように設定できます。この通知をレビューメッセージと呼びます。

何故、Perforce なのか:

Perforce と同様にバージョン管理を行うソフトウェアには様々なものがあります。 特に、CVS (Concurrent Versions System) と呼ばれるソフトウェアは無償で利用でき、 フリーソフトウェアの開発に広く使われています。 Media Art Online で Perforce を用いている理由としては、それが高速であること、 また、デザインが整理されており、保護機構も強力で、緻密な設定が可能であることなどがあげられます。

ダウンロードとインストール

  • http://www.perforce.com/ のダウンロードページから、お使いのプラットフォームに対応する p4 ソフトウェアをダウンロードし、インストールしてください。
    • p4 はコマンドライン (コマンドプロンプト) で動作するプログラムです。GUI を持つプログラムもありますが、コマンドラインが結局一番便利に使えると思います。ここでは p4 ソフトウェアの説明を行います。

※ Perforce ソフトウェアの使用は必須ではありません。
 ご自分で開発をされない方は、nightly build を活用してください。

Perforce で用いる環境変数

お使いのプラットフォームでの方法に沿って、以下の環境変数を設定してください。

環境変数名意味設定する内容
P4CLIENTクライアント名ユーザが用いるワークスペースを識別するのに用いられます。
P4EDITORエディタユーザが普段用いているエディタプログラム
P4PASSWDパスワードお知らせしたパスワード
P4PORTサーバ名:ポートperforce.media-art-online.org:1666
P4USERユーザ名お知らせしたユーザ名

クライアント名の付け方は、次の形式を参考にしてください。

コンピュータ名_scm ←ソフトウェア開発用のクライアント名
コンピュータ名_wcm ←ドキュメント開発用のクライアント名

p4 ソフトウェアでは、-c オプションによりクライアント名を指定できるので、 複数のクライアントを切り替えて使う方は、環境変数 P4CLIENT を設定する必要はありません。

主な Perforce コマンド

p4 では、次の形式でコマンドを打ち込みます ($ はプロンプトを表しています)。

$ p4 コマンド [コマンドオプション...] [コマンド引数...]

グローバルオプション (-c 等) はコマンドよりも前に指定します。 例えば次のような形式になります。

$ p4 -c クライアント名 コマンド [コマンドオプション...] [コマンド引数...]

p4 での主なコマンドは以下の通りです。

コマンド名機能
p4 addファイルの追加
p4 clientクライアントの作成・編集・削除
p4 clientsクライアントの一覧表示
p4 deleteファイルの削除
p4 editファイルを編集のためにオープン
p4 resolve編集内容の衝突の解決
p4 revert提出前の変更の取り消し
p4 submit追加・編集・削除内容の depot への提出
p4 syncdepot からファイルを取得してワークスペースを更新
p4 userユーザの作成・編集・削除
p4 usersユーザの一覧表示

MAO WSCM Depot の構成

Media Art Online における Perforce 応用システムを MAO WSCM (Media Art Online Web/Software Configuration Management) と呼んでいます。 Media Art Online での depot の大まかな構成は以下の通りです。

パス意味
//depot/wcm/...Media Art Online Web サイト (wija ヘルプページを含む)
//depot/scm/...Media Art Online ソフトウェア (wija を含む)
//depot/docs/...Media Art Online パブリケーション (論文、発表資料等)

wija-devel(-en) メーリングリストのメンバは、//depot/wcm/... と //depot/scm/... に対するレビューメッセージを受け取るように設定されています (設定はご自分で変更可能です)。 wija-devel(-en) メーリングリストのメンバのうち、村井研究室のメンバは、 更に //depot/docs/... に対するレビューメッセージを受け取るように設定されています。

パブリケーションに p4 submit された内容は以下の URL から自動的にアクセス可能になります。

ソフトウェア開発のためのディレクトリ構成

wija に関係するディレクトリは、//depot/scm/main/ 以下、次のようになっています。

+-java----+ ↓java ディレクトリ以下は p4 sync で自動的に作成されます。
|         |
|         +-org-+
|               |
|               +-media-art-online-+
|                                  |
|                                  +-encoding (符号化ライブラリ)
|                                  |
|                                  +-ghc   (Overlay GHC プラグイン)
|                                  |
|                                  +-gnupg    (GnuPG ライブラリ)
|                                  |
|                                  +-helpgen  (ヘルプページ作成ツール)
|                                  |
|                                  +-iwat     (i-WAT プラグイン)
|                                  |
|                                  +-iwatsrv  (i-WAT ロボットプラグイン)
|                                  |
|                                  +-jabber   (Jabber/XMPP ライブラリ)
|                                  |                                    
|                                  +-omelets  (OMELETS (LETS) ライブラリ)
|                                  |
|                                  +-plugin   (プラグインライブラリ)
|                                  |
|                                  +-qtx      (Cutie X プラグイン)
|                                  |
|                                  +-spotlite (SpotLite プラグイン)
|                                  |
|                                  +-tunes    (Tunes プラグイン)
|                                  |
|                                  +-whp      (WIDE Hours プラグイン)
|                                  |
|                                  +-whpsrv   (WIDE Hours ロボットプラグイン)
|                                  |
|                                  +-wija     (wija ライブラリ)
|                                  |
|                                  +-wija_    (wija 主プログラム)
|                                  |
|                                  +-wijabot  (wija ロボット主プログラム)
|                                  |
|                                  +-xml      (XML ライブラリ)
|
|
+-javadoc (ドキュメントディレクトリ; ant doc で自動的に作成されます)
|
+-javaout (出力ディレクトリ; ビルドする前に作成しておく必要があります)

helpgen と omelets は wija の一部ではありません (helpgen はヘルプページ作成ツールで、ヘルプページを記述するためのオムニドキュメントのトランスレータが現状 omelets の中に含まれています)。

また、wijabot は自動化可能な wija であり、wija とは別々にビルドされます。

ドキュメント開発のためのディレクトリ構成

wija に関係するディレクトリは、//depot/wcm/main/ 以下、次のようになっています。

+-gnupg--+
|        |
|        +-help            (GnuPG ヘルプページ)
|
+-iwat---+                 (i-WAT 主ページ)
|        |
|        +-help            (i-WAT ヘルプページ)
|
+-java---+
|        |
|        +-help            (Java ヘルプページ)
|
+-png                      (画像ファイル)
|
+-png-en                   (画像ファイル - 英語版用)
|
+-wija---+                 (wija 主ページ)
         |
         +-help            (wija ヘルプページ)
         |
         +-download-+      (wija ダウンロードページ)
                    |
                    +-0.07 (version 0.07 リリースファイル)
                    |
                    :

上では、i-WAT はプラグインの代表として描かれています。 Media Art Online で開発されるその他のプラグインの web ページもこの構成に従います。

0.07 はリリースされているバージョンの代表として描かれています。

パブリケーションのためのディレクトリ構成

Media Art Online のメンバによるパブリケーションは //depot/docs/main/ 以下、次のように格納されています。

+-tex-+     (論文/発表資料の LaTeX2εソースファイル)
      |
      +-eps (論文/発表資料に挿入する図版)

Perforce チュートリアル

ユーザの設定

ユーザの設定は、p4 user コマンドにより行います。 以下のコマンドを打ち込むと、エディタが開き、ユーザの設定を変更することができます。

$ p4 user ユーザ名

Media Art Online から Perforce ユーザアカウントを取得した場合、 初期パスワードが設定されていますので、セキュリティ上、それを変更することが強く奨励されます。

Password:    ****** ←書き換えます

また、以下のようにレビューメッセージが設定されていますが、変更が可能です。

Reviews:
    //depot/wcm/... ←ドキュメントの更新のレビューメッセージを受け取ることを示します
    //depot/scm/... ←ソフトウェアの更新のレビューメッセージを受け取ることを示します

クライアントの作成

ユーザの設定が済んだら、クライアント (depot とワークスペースのマッピング) を作成します。 次のコマンドを打ち込むと、エディタが開きます。

$ p4 client クライアント名

クライアント名にはお使いのコンピュータ名 (種類ではなく、個体名) を含めるようにすると、 混乱を避けられます (例: iggy_wcm ← iggy というコンピュータでドキュメント開発を行う)。

depot とワークスペースのマッピングのためには、Root と View を設定します。

Root: 基点となるディレクトリ名 (例: /Users/alice/Programs)

Root で、ワークスペースの基点となるディレクトリ名を指定します。 ソフトウェア開発であれば、ご自分のホームディレクトリ下の Programs という名称を奨励します。 ドキュメント開発の場合は、 ご自分のコンピュータの web 共有のためのディレクトリを指定するとよいでしょう。

View:
    //depot/scm/main/java/org/... //クライアント名/java/org/...

View では、depot 内のパスとワークスペース内のパス (Root からの相対指定) のマッピングを定義します。 上は、ソフトウェア開発のために指定すべき内容を示しています。

View:
    //depot/wcm/main/gnupg/...          //クライアント名/gnupg/...
    //depot/wcm/main/iwat/...           //クライアント名/iwat/...
    //depot/wcm/main/java/...           //クライアント名/java/...
    //depot/wcm/main/png/...            //クライアント名/png/...
    //depot/wcm/main/png-en/...         //クライアント名/png-en/...
    //depot/wcm/main/wide_hour/help/... //クライアント名/wide_hour/help/...
    //depot/wcm/main/wija/...           //クライアント名/wija/...

上は、煩雑ですが、ドキュメント開発のために指定すべき内容です。 Media Art Online の web サイト (//depot/wcm/main/ 以下) には、 wija 関連のページ以外にも大量のコンテンツがあるため、 上のように書いた方がローカルディスク資源を節約できます。

ワークスペースの構築と更新

p4 sync コマンドにより、depot の内容をワークスペースに読み込みます。 下は、コマンドラインでクライアント名を指定する場合です。

$ p4 -c クライアント名 sync

ソフトウェアのビルド

ソフトウェアのビルドには ant ツールが必要です。

wija 本体をビルドする場合は次のようにします (ワークスペースの基点が ~/Programs であると前提)。

$ cd ~/Programs/java/org/media_art_online/wija_
$ ant package

ビルドが完了すると、~/Programs/javaout にソフトウェアが構築されています (予め ~/Programs/javaout を作成しておいてください)。

更にプラグインをビルドする場合は、例えば i-WAT であれば次のようにします。

$ cd ../iwat
$ ant package

ドキュメントのビルド

ドキュメントのビルドには、現状では Perl が必要です。 また、helpgen をビルドしておく必要があります。

以下は、ソフトウェア開発用ワークスペースの基点が ~/Programs であることを前提にしています。

$ cd ~/Programs/javaout
$ perl helpgen.pl ドキュメント開発用ワークスペースの基点

レビューメッセージを受け取ったら…

レビューメッセージを受け取ったら、Perforce を用いている場合は、以下のコマンドで再度、 depot からファイルをワークスペースにダウンロードしてください。

$ p4 -c クライアント名 sync

そしてビルドを行い、問題が生じていないか確かめてください。

Perforce を用いない場合は、nightly build を待って試用してください。

ファイルの追加

p4 add により、ワークスペースにファイルを追加できます。 ファイルを作成する前後 (後を推奨します) に、 以下のようなコマンドにより、depot に対して、追加しつつあるファイルの存在を知らせます (p4 submit するまで、実際には追加されません)。

$ p4 -c クライアント名 add -t ファイルタイプ ファイル名...

ファイルタイプは、ファイルの種類を指定します。

ファイルタイプ意味
text+kテキストファイル (キーワード変換あり)
binaryバイナリファイル

キーワード変換:

ソースコードに次のような文字列を注釈として埋め込んでおくことにより、 p4 submit 時にキーワードが変換され、更新日時などの情報をソースコード自体から読み取れるようになります。

キーワード意味
$Id$ファイルの ID (depot 上のパスとリビジョン)
$DateTime$ファイルの更新日時

p4 add による、ファイルの追加予約は、p4 revert によって取り消すことができます。

ファイルの編集

既存のファイルは、Perforce によってロックされています。 ロックを解除し、編集可能にするためには、p4 edit を用います。

$ p4 -c クライアント名 edit ファイル名...

p4 edit の後に行った編集内容は、p4 revert により取り消すことができます。

変更内容の depot への提出

p4 add によって予約したファイルの追加を実際に実施したり、 p4 edit の後に行われた編集内容を depot に反映させるためには、p4 submit を行います。

$ p4 -c クライアント名 submit

p4 submit を行うと、エディタが開きますので、 Description を記述します (なるべく英語を用いてください)。 保存して終了すると、更新内容が depot に通知されます。


*1 プラグインは一部、スクリプト言語で記述されることがあり得ます。その場合は、プラットフォーム標準の言語 (例: Mac OS X では AppleScript?) で書かれるか、プラグインの導入マニュアルで導入の仕方が解説される必要があります。また、ヘルプページ作成ツールである helpgen は現状では Perl により書かれたスクリプトを用います。

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2007-07-10 (火) 20:07:33 (3789d)