en/Projects/wija

Overview

wija and its plug-ins are written in Java language (J2SE; Java 2 Standard Edition)*1. You will need to install JDK (J2SE Development Kit) to develop programs using J2SE (bundled with OS in case of Mac OS X). We assume that ant tool is used for builds.

The versions of all software (including wija and its plug-ins) and web sites developed and distributed by Media Art Online are managed using Perforce software. It is a commercial software, but Perforce has agreed to grant free licenses for 40 users in Media Art Online only in the case where those licenses are used for development in open source projects. Also, since the client software for Perforce is free, anyone can obtain the latest source code using the software even if they do not intend to participate in development at Media Art Online.

We have prepared the wija-devel-en mailing list (the English-only version of wija-devel) to share those licenses and to discuss issues in the development of wija and its related software. For each member of wija-devel-en list, a writing-enabled Perforce user account is allocated.

If you are interested in joining wija-devel-en, please let us know at the following

mailto.png

Nightly build

The members of wija-devel-en can try out the latest software or documentation by receiving a review message by Perforce right after a modification is made to the development items in which they are interested.

In case of software development

However, what you can obtain from Perforce is source code, so that you will need to build the softare using the development tools in order to actually try them out. It could be too complex for people who do not normally develop software.

Therefore, an internal release is made almost nightly, so that people who do not wish to use the development tools can still check changes when they are made.

This internal release is made by the early morning (8:00 JST) of the next day following a new modification. The following URL is reserved for the internal releases.

An internal release is provided in the form of a compressed archive file whose name contains the latest Perforce change number.

wija-change#.zip

In case of documentation development

Likewise, you will need to build help pages on your computer from their source code written in "OmniDocument?" format. To do so, you will need to use one of our development tools (help page generator).

However, Media Art Online staff (a software robot in future) will always build help pages on our second web server whenever a modification is made to the documentation. This will let you browse the updated pages on the following URL after sometime:

If no one sees a problem in the updated documentation, the modification will be propagated to the published site at http://www.media-art-online.org/wija/ .

Development tools

  • JDK (http://java.sun.com/ )
    • Java 2 Standard Edition Development Kit
    • Bundled with Mac OS X (please use Software Update)
  • Perforce (http://www.perforce.com/ )
    • A software configuration management tool
    • This page describes how to use Perforce, using p4 (the command line client software) as an example
    • Please refer to the Perforce documentation accessible from the above URL.
  • Ant (http://ant.apache.org/ )
    • A build tool
  • helpgen (developed at Media Art Online, included in our Perforce depot)
    • A help generator

Perforce installation and configuration

Perforce overview

Perforce is a software to help people physically distributed in many distant locations, using different computers, to develop the same software and/or documentation using the Internet. Perforce lets you manage versions of each file of which a software or a documentation consist.

Depot
Perforce places a depot, or the version management database, on the Perforce server prepared for a site. This database contains all source code and their revision histories of the software or documentations developed on the site. In the depot, information of files are organized in the form of layered directories just like they are in your computer.
Client
A Perforce user defines a client, or a mapping, for each development category with which they are concerned. The mapping defines which part of the depot corresponds to which directory in the local disk of the user's computer.
Workspace
The directory in the local disk onto which a part of the depot is mapped is called a workspace. A Perforce user downloads the latest versions of the files from the depot, adds files to the workspace, modifies existing files, and submits the changes to the depot.
Review message
A Perforce user can have the Perforce server send them e-mail messages to notify any changes to the development items with which they are concerned. This notification message is called a review message.

Why Perforce:

There are a lot of versioning software available in the market other than Perforce. CVS (Concurrent Versions System) is perhaps the most well-known example of such software, being free, and is used broadly for development of free software. The reasons why Media Art Online uses Perforce include 1) it is faster, 2) it is well-designed, 3) it provides more minute control over accessing the files.

Environment variables for Perforce

The following environment variables may have to be set. How to do so depends on the platform you are using.

NameMeaningSetting
P4CLIENTClient nameUsed for identifying the workspace the user uses
P4EDITOREditorThe editor software the user usually uses
P4PASSWDPasswordThe password notified to you
P4PORTServer name:portperforce.media-art-online.org:1666
P4USERUser nameThe user name notified to you

The following is a suggestion for naming the clients.

computerName_scm <- client name to identify a software development space
computerName_wcm <- client name to identify a document development space

(SCM stands for Software Configuration Management. WCM stands for Web Content Management.)

Because p4 software always lets you specify the client name by -c option, you do not need to set P4CLIENT, especially if you intend to use multiple clients all the time.

Popular Perforce commands

A p4 command takes the following form ($ is a prompt, which may be different in your environment).

$ p4 command [option...] [argument...]

Global options (such as -c) are specified before the command name.

$ p4 -c client command [option...] [argument...]

The following is the list of popular p4 commands.

CommandFunction
p4 addAdds files
p4 clientCreates/edits/deletes a client
p4 clientsLists existing clients
p4 deleteDeletes files
p4 editOpens files for editing
p4 resolveResolves conflicts of editions
p4 revertCancels modifications before submitting
p4 submitSubmits additions/editions/deletions to the depot
p4 syncUpdates the workspace by obtaining files from the depot
p4 userCreates/edits/deletes a user
p4 usersLists existing users

MAO WSCM Depot configuration

The Perforce application system in Media Art Online is called MAO WSCM (Media Art Online Web/Software Configuration Management). The following is an overview of the depot in MAO WSCM.

PathDescription
//depot/wcm/...Media Art Online Web site (including wija help pages)
//depot/scm/...Media Art Online software (including wija)
//depot/docs/...Media Art Online publications (papers and presentation materials)

wija-devel(-en) mailing list members are configured to review //depot/wcm/... and //depot/scm/... by default (meaning that they will receive review messages when changes are made; the configuration can be changed by the members themselves). Those wija-devel(-en) members who are also members of Murai Lab. are configured to review //depot/docs/... by default as well.

The publications p4 submitted will be automatically accessible from the following URL.

Directory structure for software development

The following is how directories related to wija are configured under //depot/scm/main/.

+-java----+ (directories under java are automatically created by a p4 sync)
|         |
|         +-org-+
|               |
|               +-media-art-online-+
|                                  |
|                                  +-encoding (encoding library)
|                                  |
|                                  +-ghc        (Overlay GHCplug-in)
|                                  |
|                                  +-gnupg    (GnuPG library)
|                                  |
|                                  +-helpgen  (help page generator)
|                                  |
|                                  +-iwat     (i-WAT plug-in)
|                                  |
|                                  +-iwatsrv  (i-WAT robot plug-in)
|                                  |
|                                  +-jabber   (Jabber/XMPP library)
|                                  |                                    
|                                  +-omelets  (OMELETS (LETS) library)
|                                  |
|                                  +-plugin   (plug-in library)
|                                  |
|                                  +-qtx      (Cutie X plug-in)
|                                  |
|                                  +-spotlite (SpotLite plug-in)
|                                  |
|                                  +-tunes    (Tunes plug-in)
|                                  |
|                                  +-whp      (WIDE Hours plug-in)
|                                  |
|                                  +-whpsrv   (WIDE Hours robot plug-in)
|                                  |
|                                  +-wija     (wija library)
|                                  |
|                                  +-wija_    (wija main program)
|                                  |
|                                  +-wijabot  (wija robot main program)
|                                  |
|                                  +-xml      (XML library)
|
|
+-javadoc (document directory; generated by ant doc)
|
+-javaout (output directory; needs to be created before building)

helpgen and omelets are not part of wija (helpgen is a help page generator. The OmniDocument? translator for help pages is currently included in omelets.)

wijabot is a automated version of wija, which is built separately from wija.

Directory structure for documentation development

The following is how directories related to wija are configured under //depot/wcm/main/.

+-gnupg--+
|        |
|        +-help            (GnuPG help page)
|
+-iwat---+                 (i-WAT home page)
|        |
|        +-help            (i-WAT help page)
|
+-java---+
|        |
|        +-help            (Java help page)
|
+-png                      (image files)
|
+-png-en                   (image files for the English version)
|
+-wija---+                 (wija home page)
         |
         +-help            (wija help page)
         |
         +-download-+      (wija download page)
                    |
                    +-0.07 (version 0.07 release files)
                    |
                    :

In the above, i-WAT is used as an example of a plug-in module. Web pages for other plug-in modules developed in Media Art Online follow the same structure.

0.07 is an example of a released version.

Directory structure for publications

The following is how the publications by the members of Media Art Online are configured under //depot/docs/main/.

+-tex-+     (LaTeX2e source files of papers and presentation materials)
      |
      +-eps (EPS figures for papers and presentation materials)

Perforce tutorial

Setting user profiles

To configure your user profile, use p4 user command. By typing the following, you can open an editor window to edit your user profile.

$ p4 user userName

If you have obtained a Perforce user account from Media Art Online, you are strongly encouraged to change the initial password for security reasons.

Password:    ****** <- rewrite

Also, the following initial settings for reviewing can be changed.

Reviews:
    //depot/wcm/... <- receive review messages for documentation.
    //depot/scm/... <- receive review messages for software.

Creating a client

After setting your user profile, create a client which is a mapping between the depot and your workspace. Open an editor window to edit a client by the following command line.

$ p4 client clientName

The client name should include your computer name (proper noun) so that it will be easy to distinguish (ex. iggy_wcm for documentation development on a computer named iggy).

Specify the Root and View for mapping a part of depot onto your workspace.

Root: baseDirectoryName (ex. /Users/alice/Programs)

Root specifies the base directory of your workspace. Suggested directory name for software development is "Programs" under your home directory. You would want to specify a Web-sharing directory on your computer for documentation development.

View:
    //depot/scm/main/java/org/... //clientName/java/org/...

View specifies the mapping between a path in the depot and a path in your workspace (relative from Root). The above view is for software development.

View:
    //depot/wcm/main/gnupg/...          //clientName/gnupg/...
    //depot/wcm/main/iwat/...           //clientName/iwat/...
    //depot/wcm/main/java/...           //clientName/java/...
    //depot/wcm/main/png/...            //clientName/png/...
    //depot/wcm/main/png-en/...         //clientName/png-en/...
    //depot/wcm/main/wide_hour/help/... //clientName/wide_hour/help/...
    //depot/wcm/main/wija/...           //clientName/wija/...

The above view, although lengthy, is for documentation development. This way, resources in your local disk can be saved, because Media Art Online web site (under //depot/wcm/main/) contains a lot other contents than wija-related pages.

Setting up/updating a workspace

By p4 sync command, you can download the contents of the depot into your workspace. The command line below specifies the client name by an option.

$ p4 -c clientName sync

Building software

ant tool is required for building software.

The command lines to build wija are like the below, assuming "~/Programs" is the base directory of your workspace.

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

The executable software will be under "~/Prograsm/javaout/" after the build is complete (create "~/Programs/javaout" prior to your first build).

If you would further like to build plug-in modules, type as follows (in case of i-WAT).

$ cd ../iwat
$ ant package

Building documentation

Currently, Perl is required for building documentation. You would also need to build helpgen prior to building documentation.

The following command lines assume that the base directory of your workspace for software development is "~/Programs".

$ cd ~/Programs/javaout
$ perl helpgen.pl theBaseDirectoryOfDocumentationDevelopment

Upon receiving a review message

Upon receiving a review message and if you use Perforce, update your workspace by the latest files in the depot.

$ p4 -c clientName sync

Then, build the software and see if the update caused any problems.

If you do not use Perforce, wait for the next nightly build to try out.

Adding files

You can add files to your workspace by p4 add. Before or after (after is suggested) creating the files, notify the depot of their existence by the following command line (the files will not be included in the depot until p4 submitted).

$ p4 -c clientName add -t fileType fileName...

A file type should be one of the following.

File typeMeaning
text+ktext file (with keyword translation)
binarybinary file

Keyword translation:

By embedding the following strings in the comments in your source code, those keywords will be translated upon p4 submit, and update time and other information will be obtainable from the source code themselves.

KeywordMeaning
$Id$file ID (the path and revision in the depot)
$DateTime$update date and time

The effects of p4 add can be cancelled by p4 revert if the files have not been p4 submitted.

Editing files

The existing files are locked by Perforce. Use p4 edit to unlock the files and getting them ready for editing.

$ p4 -c clientName edit fileName...

The effects of p4 edit and modification afterwards can be reverted by p4 revert if the files have not been p4 submitted.

Submitting files to depot

Use p4 submit to actually add files specified by p4 add or write the modification after p4 edit back to the depot.

$ p4 -c clientName submit

p4 submit opens an editor window in which the submission specification is described. Fill "Description" in, save and exit the editor. Then the depot will be updated.


*1 Some part of plug-in modules may be written in a script language. In which case, either it should be the platform's standard language (such as AppleScript? for Mac OS X) or users should be guided how to install the script language. Currently, helpgen, our help generator tool, uses a script written in Perl.

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