thdltools/www
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
www/htdocs/BuildSystems.html
eg3p ee840fe816 I have embedded the SourceForge documentation into 
THDL's web design and menu system. At the design
protocols for the THDL web site are a bit messy, but
they are being cleaned up and hopefully will eventually
emerge in a way that makes them easier for non-THDL
staff like David C. to make sense of.
2003-05-14 20:52:13 +00:00

1310 lines
46 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<!-- @author David Chandler -->
<!-- @date-created October 20, 2002 -->
<!-- @editor Emacs, baby! -->
<!--
==============
INSERT KEYWORDS AND DESCRIPTION HERE
==============
-->
<meta name="keywords" content="tibetan fonts, tibetan software, digital ethnography">
<meta name="description" content="This presents intellectual and electronic tools for using Tibetan language in a digital medium and for viewing the THDL site.">
<!--
==============
INSERT PAGE TITLE HERE
==============
In order to facilitate the use of the unicode character set the charset declaration will be set equal to utf-8
Always incorporate Tibetan and Himalayan
-->
<title>THDL Tools Build Systems</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-utf-8">
<!--
==============
THIS IS THE STYLE FOR THE BODY; IT'S WHAT CALLS ON THE BANNER AS A BACKGROUND IMAGE AND SETS UP THE BACKGROUND COLOR. MAKE SURE TO LINK TO THE BANNER HERE.
==============
-->
<style type="text/css">
<!--
body {background-attachment: scroll; background-image: url(http://iris.lib.virginia.edu/tibet/images/bannerTools.gif); background-repeat: no-repeat; background-position: left top; backgroud-color: white}
-->
</style>
<!--
==============
THE STYLE FOR THE TEXT, ETC. IT GOES TO THE TOP-LEVEL STYLE PAGE. IS THERE A NEED FOR EACH COLLECTION TO HAVE INDIVIDUAL STYLE PAGES?
==============
-->
<link rel="stylesheet" href="http://iris.lib.virginia.edu/tibet/style/tools.css">
<!--
==============
MAKES NETSCAPE RELOAD IF THE WINDOW IS RESIZED
==============
-->
<script language="JavaScript">
<!--
function MM_reloadPage(init) { //reloads the window if Nav4 resized
if (init==true) with (navigator) {if ((appName=="Netscape")&&(parseInt(appVersion)==4)) {
document.MM_pgW=innerWidth; document.MM_pgH=innerHeight; onresize=MM_reloadPage; }}
else if (innerWidth!=document.MM_pgW || innerHeight!=document.MM_pgH) location.reload();
}
MM_reloadPage(true);
// -->
</script>
</head>
<!--
==============
SETS THE PAGE MARGINS TO "0" SO THE MENU DOESN'T GET SCREWED UP
==============
-->
<body topmargin="0" leftmargin="0" marginwidth="0" marginheight="0">
<!--
==============
THE JAVASCRIPT MENUS
==============
-->
<script type='text/javascript'>
//HV Menu v5- by Ger Versluis (http://www.burmees.nl/)
//Submitted to Dynamic Drive (http://www.dynamicdrive.com)
//Visit http://www.dynamicdrive.com for this script and more
function Go(){return}
//==============
// --CALL UP THE MENU. THE 1ST OF THE CHOICES HAS THE VARIABLES
// AND NEEDS TO BE UPDATED FOR EACH SECTION.
// MENU_LOADER.JS WILL ALWAYS BE THE SAME.
//==============
</script>
<script type='text/javascript' src='http://iris.lib.virginia.edu/tibet/scripts/menu_tools.js'></script>
<script type='text/javascript' src='http://iris.lib.virginia.edu//tibet/scripts/menu_loader.js'></script>
<script type="text/javascript" src="http://iris.lib.virginia.edu//tibet/scripts/thdl_scripts.js"></script>
<noscript> Your browser does not support Javascript menus. Please utilize the
Site Map for navigation.</noscript>
<div align="left" style="position:absolute; left:0px; top:0px; width:100px; height:50px; z-index:7">
<a href="http://iris.lib.virginia.edu/tibet/index.html">
<img src="http://iris.lib.virginia.edu/tibet/images/spacer.gif" style="border-width:0" width="100" height="50">
</a>
</div>
<div id="Layer1" style="position:absolute; left:100px; top:28px; width:708px; height:20px; z-index:1">
<!--
==============
INSERT THE BREADCRUMBS
==============
A HREF tags should not be applied to current page, e.g. THDL and Collections get link, Literature and Home do not. If you were on a subpage of Literature, then Literature would link to the Literature home page.
-->
<div align="right"><font color="#000000"><A HREF="http://iris.lib.virginia.edu/tibet/index.html">THDL</A> : <A HREF="http://iris.lib.virginia.edu/tibet/tools/index.html">Tools</A> : <a href="http://iris.lib.virginia.edu/tibet/tools/software.html">Software</a> : Build Systems</a></font>
</div>
</div>
<!--
==============
INSERT THE MENU
==============
-->
<div id='MenuPos' style="text-size:9px; layer-background-color:#CCCCCC; background-color: #CCCCCC; position:absolute; left:0px; top:50px; width:808px"><table width="808" cellpadding="0" cellspacing="0" height="19"><tr><td><p style="font-size:9px">Menu loading...</p></td></tr></table></div>
<!--
==============
MAKE THE LAYER THAT WILL HOLD THE CONTENT OF THE PAGE - THE TEXT, IMAGES, WHATEVER. THIS LAYER WILL BE CLOSED AT THE END OF THIS HTML DOCUMENT
==============
Maximum table width not to exceed 750
All images must have borders of 1 pixel
No image will exceed 325 X 325 height and width measurements
Position attribute on layer3 may need to be changed to absolute to accomodate Netscape
-->
<div id="Layer3" style="position:relative; left:7px; top:80px; width:801px; height:396px; z-index:1; overflow: visible; background-color: #FFFFFF; layer-background-color: #FFFFFF; border: 1px none #000000" >
<table width="750" border="0" cellspacing="0" cellpadding="10">
<tr>
<td valign="top" align="left">
<!--
=============
FOR EVERY "ADMINISTRATIVELY DISTINCT" PROJECT, THERE SHOULD BE A CREDIT FOR THE PROVIDER OF THE INFO
=============
-->
<script langauge="JavaScript">
function openWin(url, name) { popupWin = window.open(url, name,"resizable=1,scrollbars=1,toolbar=0,width=400 ,height=450")
}
</script>
<!--
============
THIS LINK WILL OPEN A SEPARATE WINDOW THAT WILL PROVIDE INFORMATION REGARDING THE ADVISORY BOARD MEMBERS. ALSO PROVIDED IN THE PAGE WILL BE PARTICIPATION AND DONATION INFORMATION.
============
-->
<!--
==============
SETS THE BODY TEXT TO JUSTIFIED
==============
-->
<div align=justify>
<!--
=============
INSERT LINK TO GUIDED TOUR HERE -uncomment when ready.
=============
-->
<!--
==============
INSERT BODY TEXT HERE
The first section of text is the short "introduction" about the Theme and the various discplines that have a vested interest in them.
Design principle: Bold the first few words of this text section.
==============
-->
<h2>THDL Tools Build Systems</h2>
<p>
David Chandler has put together a build system for Jskad, the
translation tool, Tibbibl, and for the fonts.&nbsp; In the CVS
repository, you'll find that the build system once worked for Savant
and QuillDriver as well.&nbsp; This document describes them, and
should be updated if we put together build systems for the two
diacritics packages and for Wylie Word (but see e-mail to
thdl-devel@lists.sourceforge.net that tells why we probably will
continue to require Wylie Word developers to edit from within MS
Word on account of the difficulty of using CVS with VBA).
</p>
<p>
What is a <i>build system</i>, you ask?&nbsp; A build system is a
set of clear, repeatable procedures that software developers go by
to compile, run, test, create documentation, and cut releases.&nbsp;
Our build systems are fully automated, which provides a good basis
for collaborative development.&nbsp; Even for individual
development, a good build system gives you the confidence to make
big organizational changes and saves you time in the long run.
</p>
<h3>Table of Contents</h3>
<ul>
<li>
<a href="#glossary">Glossary</a>
</li>
<li>
<a href="#whyant">Why we chose Apache Ant</a>
</li>
<li>
<a href="#installant">Installing Apache Ant</a>
</li>
<li>
<a href="#cvs">Setting things up to use CVS</a>
</li>
<li>
<a href="#buildingfonts">Building the <code>Fonts</code>
module</a>
</li>
<li>
<a href="#wwwmodule">Building the <code>www</code>
module</a> -- how to publish on this very web site, that is
</li>
<li>
<a href="#diacriticsmodule">Building the <code>Diacritics</code>
module</a>
</li>
<li>
<a href="#wyliewordmodule">Building the <code>WylieWord</code>
module</a>
</li>
<li>
<a href="#jskadmodule">Building the <code>Jskad</code>
module</a>
<ul>
<li>
<a href="#jskadsetup">Setting things up for your first build
of the <code>Jskad</code> module</a>
</li>
<li>
<a href="#daytoday">Day-to-day development activities
with the <code>Jskad</code> module</a>
<ul>
<li>
<a href="#testingjskad">Testing</a>
</li>
</ul>
</li>
<li>
<a href="#webstart">Why we chose Java Web Start and how it
works</a>
</li>
<li>
<a href="#relwebstart">Cutting a Java Web Start release</a>
</li>
</ul>
</li>
</ul>
<h3>Glossary<a name="glossary"></a></h3>
<p>
This document uses the following terms:
</p>
<ul>
<li>
CVS -- "concurrent versions system", a piece of software used by
SourceForge and many others for source code revision control.
</li>
<li>
WinCVS -- a front end for use on Windows that you can use rather
than the command-line cvs tools.
</li>
<li>
<a name="sandbox">sandbox</a> -- a directory on your local machine
that mirrors one in our project's CVS repository.&nbsp; You get
one by using the command <code>'cvs checkout'</code>.&nbsp; It's
called a sandbox because you can safely play in it; your work will
not affect others until you commit your changes to the
repository.&nbsp; (Though if you really wanted to, you could
create a CVS branch and then even your commits (to that branch)
wouldn't affect the work of others on the trunk, or main branch.)
</li>
<li>
ssh, scp, sftp -- the software that SourceForge uses to allow you
to log in to their server without worrying about the security of
your password of the subsequent communications.&nbsp; ssh logs you
in, scp and sftp allow you to copy files to and from
<code>thdltools.sourceforge.net</code>.&nbsp; Windows users should
either get these tools with Cygwin or should install PuTTY; the
latter is probably easier.
</li>
<li>
Ant -- a.k.a. Apache Ant.&nbsp; Software we use to compile and
package Java programs for distrution.
</li>
</ul>
<h3>Why we chose Apache Ant<a name="whyant"></a></h3>
<p>
Ant is built from the ground up as a full-featured, extensible
build system for Java programs.&nbsp; If you use Ant, your
classpath-related headaches disappear (after clearing initial
hurdles), and you can be sure that the build will work the same on
Linux and the Mac as it does on Windows XP, because Ant itself is
a Java program.&nbsp; I compile, test, run, and build releases
using Ant, and really like it.
</p>
<p>
Although Ant is mainly intended for building Java programs, it has
enough features to make it a viable choice of build system for
things non-Java, things like the Tibetan Machine Web font.
</p>
<h3>Installing Apache Ant<a name="installant"></a></h3>
<p>
To install Apache's Jakarta Ant (or "Apache Ant" or simply "Ant"),
you'll first need a JDK installed.&nbsp; I recommend getting Sun's
latest 1.4 JDK (yes, it's available for Linux too).&nbsp; Next, see
the <a href="http://jakarta.apache.org/ant/"> Apache Ant</a>
website.&nbsp; Their instructions for installation are pretty good,
but you may have trouble if you're on Windows and you don't know how
to set environment variables (try Control
Panel-&gt;System-&gt;Advanced-&gt;Environment Variables) and the
like.&nbsp; One thing they don't tell you is that their binary
distribution ships with a ton of documentation in
<code>$ANT_HOME/docs/</code> that can all safely be deleted if you
care about disk space.
</p>
<p>
I recommend installing Ant yourself, and not using a package manager
such as apt-get or rpm.&nbsp; This is because the ordinary
installation has a well-known <code>$ANT_HOME/lib</code> directory
in which we'll wish to place a couple of JARs (<a
href="#testingjskad"> <code>junit.jar</code></a> and Vamp), as
described below.&nbsp; I've had personal experience with an RPM that
made it impossible for me to make Ant aware of extra JARs, so stay
away from RPMs and other packages.
</p>
<p>
To test your installation, use cvs to checkout either the
<code>Fonts</code> module or the <code>Jskad</code> module.&nbsp;
The <code>Fonts</code> module has a simpler Ant build file
(<code>Fonts/build.xml</code>) than the <code>Jskad</code> module
has, so perhaps it's better for testing.&nbsp; The
<code>Jskad</code> module should be good to go as well, though,
because we have a multi-buildfile system that delegates less common
build activities (ones that require tweaking of your Ant
installation) to supporting buildfiles and keeps the main buildfile,
<code>Jskad/build.xml</code>, free of nonstandard constructs.&nbsp;
Change directory to whichever module you choose and run the
following command:
</p>
<blockquote>
<code>ant clean</code>
</blockquote>
<p>
The output shouldn't alarm you, and it should conclude with "BUILD
SUCCESSFUL".&nbsp; If you have any trouble, see Ant's FAQs and then
e-mail David Chandler.
</p>
<p>
Now that you have a good installation of Ant itself, you probably
will want to install both JUnit and Vamp.&nbsp; These steps can wait
until later if you're not sure you'll be testing our software or
packaging our software for release.&nbsp; Here are the steps to
install them:
</p>
<ul>
<li>
To install JUnit, first do a cvs checkout of the
<code>Jskad</code> module (see <a href="#cvs"> below</a> for info
on how to use CVS).&nbsp; Now, to make Ant aware of JUnit, simply
copy <code>Jskad/extensions/to-be-installed-with-ant/junit.jar</code>
to the <code>$ANT_HOME/lib/</code> directory (and, if you're on
UNIX/Linux, make the file world-readable).
</li>
<li>
It isn't much trouble to install the <a
href="http://www.vamphq.com/ant.html"> Vamp Ant task</a> provided
by the <a href="http://www.vamphq.com/"> Venus Application
Publisher</a>.&nbsp; You need this to cut <a
href="http://java.sun.com/products/javawebstart/"> Java Web
Start</a> releases of Jskad, [Tibbibl if I ever get my act
together], and the translation tool.&nbsp; You <b>do not</b> need
it otherwise.
<p>
Installing Vamp's Ant task is simple enough, and is in fact
simpler than Vamp's web pages of October 1, 2002 imply.&nbsp;
That is, if you have installed Ant 1.5.1 or later, then you can
simply drop <code>vamp.jar</code> into Ant's <code>lib</code>
directory (i.e., <code>$ANT_HOME/lib/</code>) and forget about
changing your classpath (but do be sure, Linux/UNIX users, that
the file is world-readable).
</p>
</li>
</ul>
<p>
Your build environment is good to go!
</p>
<h3>Setting things up to use CVS <a
name="cvs"></a></h3>
<p>
If you're working on Windows, it's probably easiest to follow <a
href="http://sourceforge.net/docman/display_doc.php?docid=766&amp;group_id=1">
SourceForge's instructions</a> on using WinCVS and PuTTY.&nbsp; The
instructions there aren't up to date for the latest version of
WinCVS (1.3b8 as of this writing).&nbsp; Instead of telling WinCVS
about <code>plink.exe</code> in the non-existent <code>Ports</code>
tab of the <code>Admin-&gt;Preferences</code> menu, you must click
the Settings button next to the server type (<code>"ssh"</code>) and
click the <code>'If ssh is not in the path'</code> checkbox, and
enter <code>plink.exe</code>'s full path there.
</p>
<p>
Also note that <a href="http://www.computas.com/pub/wincvs-howto/">
this page</a> is very helpful; it's about how to run WinCVS.
</p>
<p>
If you're using WinCVS 1.3b8, note that it has a bug -- it truncates
the output of <code>'cvs diff'</code> (as explained in <a
href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=622680&amp;group_id=10072&amp;atid=110072">
this bug report</a>).&nbsp; For that reason, you may wish to use
what WinCVS calls an "external diff" program, which is easy to
install and configure.&nbsp; Try using <a
href="http://www.prestosoft.com/examdiff/examdiff.htm">
ExamDiff</a>.
</p>
<p>
If you're on Linux or Unix, SF.net's site docs are excellent.&nbsp;
If you're on a Mac, and SF.net's docs don't do the trick, you're in
trouble.
</p>
<h3>Building the <code>Fonts</code> module<a
name="buildingfonts"></a></h3>
<p>
The <code>Fonts</code> CVS module comes with an Apache Ant build
system.&nbsp; We made this choice because the <code>Jskad</code> CVS
module already has an Apache Ant build system, and because Ant is
more than powerful enough for our needs.&nbsp; For this module, our
only task is to cut releases.&nbsp; There is nothing to compile
here; the only task that a developer will face is updating the
associated documentation and then cutting a new release, ready to go
up on SourceForge's File Release System (FRS).
</p>
<p>
To cut releases for one or both of the Tibetan Machine Web and
Tibetan Machine, do the following:
</p>
<ol>
<li>
use cvs to checkout the <code>Fonts</code> module.&nbsp; If you
have already checked it out, run <code>'cvs -f update -d'</code>
(in WinCVS, hold down the shift key while selecting "Update" and
then be sure the "Create missing directories that exist in the
repository" box is checked).
</li>
<li>
make whatever changes you need to
</li>
<li>
be certain the the release notes (a text or html file, I
believe) are under CVS control.&nbsp; Perhaps you'll reuse an
existing document, or perhaps you'll have to add a file to the
repository.&nbsp; Go to <a
href="http://sourceforge.net/project/showfiles.php?group_id=61934">
our project's download page</a> and see how we've done release
notes in the past.
</li>
<li>
commit those changes to the repository
</li>
<li>
<a href="#installant">install Apache Ant</a>
</li>
<li>
change directory to <code>Fonts</code> and run the following
command:
<blockquote>
<code>ant</code>
</blockquote>
If you have any problems, be sure you're using the correct
version of Ant and then read Ant's FAQs and documentation.&nbsp;
Or you can e-mail David Chandler.&nbsp; If it turns out that the
problem is in the Ant build file <code>Fonts/build.xml</code>,
make the required changes and be sure to commit them to the
repository.&nbsp; Now run the following command to rebuild the
releases:
<blockquote>
<code>ant clean dist</code>
</blockquote>
</li>
<li>
after being sure that your <code>Fonts</code> directory is a
mirror of the one in the repository, use cvs to tag this
revision that you wish to release with a name that another
developer, years down the road, will recognize as referring to
this release.&nbsp; To do this, you can run <code>'cvs -f rtag
<i>tag-name</i> Fonts'</code> or (and this is preferred) you can
run <code>'cvs -f tag -c <i>tag-name</i>'</code>.&nbsp; Good tag
names are like the following:
<ul>
<li>
<code>Fonts_1_0</code> (referring to the 1.0 release of the
Fonts module)
</li>
<li>
<code>September_23_2002_release</code> (referring to the
release of the Fonts module made on September 23, 2002
</li>
</ul>
Note that tagging for a release of just the Tibetan Machine Web
font and not the Tibetan Machine font is <i>no different</i>
than tagging for a simulaneous release of both.
</li>
<li>
Now that you've tagged this release, it will be possible for any
other developer to recreate the same release.&nbsp; This is the
heart of a good build system -- clear, repeatable procedures
that aren't painful to follow.
</li>
</ol>
<h3>Building the <code>www</code> module<a name="wwwmodule"></a></h3>
<p>
<a href="http://thdltools.sourceforge.net/"> Our SourceForge.net
website</a> is entirely under CVS control.&nbsp; This means that we
can freely make changes, knowing that they are never lost.&nbsp; It
also means that downloading our <a
href="http://cvs.sourceforge.net/cvstarballs/thdltools-cvsroot.tar.gz">
nightly CVS repository tarball</a> is all that is necessary to save
a backup copy of our SF.net web site.
</p>
<p>
To change an existing web page or to add a new one, you must do the
following:
</p>
<ul>
<li>
First use cvs to checkout the <code>www</code> module.&nbsp; If
you've already done that, then please use cvs to update (using
<code>'cvs update -d'</code> if you want to create missing
directories that exist in the repository) now.
</li>
<li>
To add a file or directory, use <code>'cvs add'</code>.&nbsp;
Change any files you wish.&nbsp; Now validate your HTML using
W3C's <a href="http://validator.w3.org/"> validator</a>.&nbsp;
Once it passes with no errors, commit your changes.
</li>
<li>
Now you must update the CVS <a href="#sandbox"> sandbox</a> at
<code>thdltools.sourceforge.net:/home/groups/t/th/thdltools/htdocs</code>.&nbsp;
To do so, use PuTTY or another <code>ssh</code> to log in to
<code>thdltools.sourceforge.net</code>.&nbsp; Now change directory
(<code>cd</code>) to
<code>/home/groups/t/th/thdltools/htdocs</code> and run <code>'cvs
-f update -d -P'</code>.&nbsp; You'll see your changes being made
to the "real" website.&nbsp; Surf to <a
href="http://thdltools.sourceforge.net/"> the website</a> and see
for yourself.
</li>
</ul>
<h4>Updating the parts of the website not in the <code>www</code>
module<a name="updateapidocs"></a></h4>
<p>
Not all of the material up at our SF.net <a
href="http://thdltools.sourceforge.net/"> website</a> is in the
<code>www</code> CVS module, but most of it is.&nbsp; Currently, the
only exception is the Javadoc API documentation for Jskad, Tibbibl,
and the translation tool.
</p>
<p>
Here is how to update these API docs:
</p>
<ul>
<li>
The Javadocs that THDLTools_Developers.html links to,
e.g. <code>http://thdltools.sourceforge.net/pubapi</code>, live
at <code>/home/groups/t/th/thdltools/htdocs/</code>.&nbsp; To
update them, first commit any changes you've made to the
repository.&nbsp; (This, combined with the date stamp that Ant
puts into our Javadoc docs, will give other developers enough
information to recover the revision of the source files that you
used.&nbsp; But feel free to <code>'cvs tag'</code> the revision
explicitly if you think it's important.&nbsp; I tagged one
revision <code>javadocs_october_27_2002</code>, for example.)
</li>
<li>
Now simply run <code>'ant private-javadocs-dist
public-javadocs-dist'</code> from the <code>Jskad</code>
directory, which creates
<code>Jskad/dist/docs/private-javadocs-DSTAMP.zip</code> and
<code>Jskad/dist/docs/public-javadocs-DSTAMP.zip</code>.&nbsp;
Examine the output for warnings; resolve them if
necessary.&nbsp; Note that the public-javadocs-dist causes
warnings about links not found that should be ignored; they
aren't found because the things linked to are private or package
private.
</li>
<li>
Now <code>scp</code> those two filse over with the command
<blockquote>
<code>scp dist/docs/private-javadocs-WHATEVER.zip
dist/docs/public-javadocs-WHATEVER.zip
yourUserId@thdltools.sourceforge.net/home/groups/t/th/thdltools/htdocs/</code>
</blockquote>
or use PuTTY's <code>scp</code> to do something equivalent.
</li>
<li>
Now, shell in to <code>thdltools.sourceforge.net</code> with
<code>'ssh -l yourUserId thdltools.sourceforge.net'</code> or
with PuTTY.
</li>
<li>
Change directory (<code>cd</code>) to
<code>/home/groups/t/th/thdltools/htdocs/</code>.
</li>
<li>
While you're here, do a <code>'cvs -f update -d -P'</code> --
just in case some developer made changes to the web pages but
forgot to update (don't worry about setting the CVSROOT--cvs is
smart enough to determine everything (but your password)
automatically).
</li>
<li>
Anyway, now run <code>'rm -fr pubapi privateapi public-javadocs*
private-javadocs*'</code> (from the <code>htdocs/</code>
directory).
</li>
<li>
Now run <code>'mkdir pubapi privateapi'</code>.
</li>
<li>
Now run <code>'cd privateapi'</code>.
</li>
<li>
Now run <code>'unzip
../private-javadocs-WHATEVER.zip'</code>.
</li>
<li>
Run <code>'cd ../pubapi'</code>.
</li>
<li>
Run <code>'unzip
../public-javadocs-WHATEVER.zip'</code>.
</li>
<li>
Update the symbolic links by executing, from the htdocs/
directory, <code>'rm -f public-javadocs.zip
private-javadocs.zip; ln -s public-javadocs-WHATEVER.zip
public-javadocs.zip; ln -s private-javadocs-WHATEVER.zip
private-javadocs.zip'</code>.
</li>
<li>
See if <code>http://thdltools.sourceforge.net/api/</code> looks
up to date (see the date at the very bottom of the page, for
starters).&nbsp; Also, verify that links to J2SE Javadoc
documentation are functioning -- click on a link to
<code>java.lang.Object</code> and be sure that it works.&nbsp;
If everything is fine, delete
<code>../../private-javadocs-WHATEVER.zip</code> and log out.
</li>
<li>
Visit <a href="THDLTools_Developers.html">the developers'
site</a> and ensure that the four links are all functional.
</li>
<li>
<b>UPDATE THESE INSTRUCTIONS</b> if something above is wrong or
unclear.
</li>
</ul>
<p>
That's all!
</p>
<h3>Building the <code>Diacritics</code> module<a
name="diacriticsmodule"></a></h3>
<p>
We don't yet have source code in this module.&nbsp; Check back here
once we do.
</p>
<h3>Building the <code>WylieWord</code> module<a
name="wyliewordmodule"></a></h3>
<p>
You'll have to use MS Word to get at the Visual Basic source code in
the .dot file.&nbsp; Edit it there, and then commit the revised .dot
file.&nbsp; 'cvs diff' won't work, but that's life.
</p>
<h3>Building the <code>Jskad</code> module<a name="jskadmodule"></a></h3>
<p>
The following sections describe how to use the Ant build system we
have for the <code>Jskad</code> module.
</p>
<p>
The first thing to note is that the <code>Jskad</code> module is
misnamed.&nbsp; We have all our Java code inside this module,
including Jskad, Tibbibl, and the translation tool.
</p>
<h4>Setting things up for your first build of the <code>Jskad</code>
module<a name="jskadsetup"></a></h4>
<p>
You'll have to first get your computer set up to use CVS.&nbsp; See
<a href="#cvs">above</a>.
</p>
<p>
The next thing you'll need to do is get a CVS <a
href="#sandbox">sandbox</a> -- a <code>Jskad</code> directory on
your local computer.&nbsp; Use <code>'cvs checkout Jskad'</code> or
WinCVS's "Checkout module" command to do so.
</p>
<p>
You'll also need to checkout the <code>Fonts</code> module
underneath the directory where you checked out the
<code>Jskad</code> directory.&nbsp; We put the TMW font into some
JAR files, so the <code>'Jskad/Fonts/TibetanMachineWeb/'</code>
directory must exist.
</p>
<p>
Now go get the JARs you need.&nbsp; Be sure to note which versions
you get, because you'll need to mention that in the release notes of
any releases you cut.&nbsp; The following are needed:
</p>
<ul>
<li>
We use <a href="http://xml.apache.org/xalan-j/"> Xalan</a> for
XSLT, and its binary distribution contains JARs for Xalan
<i>and</i> <a href="http://xml.apache.org/xerces2-j/index.html">
Xerces</a> -- handy.&nbsp; You only need to download Xerces' JARs
separately if you need a bug fix from a later release than that
included in Xalan's.&nbsp; After downloading, move
<code>xalan.jar</code>, <code>xercesImpl.jar</code>, and
<code>xml-apis.jar</code> to <code>$ANT_HOME/lib</code>.&nbsp;
They need to be there to avoid loader errors when running the
<code>check-report</code> target, which is a part of the nightly
builds that also requires XSLT (i.e., the presence of those JARs,
but in a place that Ant recognizes).&nbsp; A consequence of using
this location is that you'll probably find using targets like
<code>jskad-run</code> much easier than specifying your own
CLASSPATH.
</li>
<li>
We also use <code>jdom.jar</code> from <a href="http://jdom.org/">
JDOM.org</a>.
</li>
<li>
We also use (conditional on the <code>thdl.media.player</code>
option) the <a
href="http://java.sun.com/products/java-media/jmf/"> Java(TM)
Media Framework</a>.&nbsp; After it is installed, either change
your CLASSPATH to include its <code>jmf.jar</code>, or avoid the
classpath hassle by copying <code>jmf.jar</code> to
<code>Jskad/extensions/drop-ins</code>.
</li>
<li>
We also use (conditional on the <code>thdl.media.player</code>
option) <a href="http://www.apple.com/quicktime/"> QuickTime for
Java</a>.&nbsp; Installing it requires installing QuickTime,
selecting a "Custom" install, and checking the box for QuickTime
for Java.&nbsp; After it is installed, either change your
CLASSPATH to include its <code>QTJava.zip</code>, or avoid the
classpath hassle by copying <code>QTJava.zip</code> to
<code>Jskad/extensions/drop-ins</code>.
</li>
</ul>
<p>
If you need to add something else to the classpath, be it a .jar
file, a .zip file, or a directory, you have several options.&nbsp;
You can set your CLASSPATH environment variable, or you can call Ant
using <code>'ant -Dadditional.class.path=c:\my.jar'</code>, or you
can drop JAR or ZIP files into
<code>Jskad/extensions/drop-ins</code>.
</p>
<p>
While you're hacking, use our <a href="api/"> API docs on the
web</a>, or <a href="#makeapidocs"> build your own</a>.
</p>
<h4>Day-to-day development activities with the <code>Jskad</code>
module<a name="daytoday"></a></h4>
<p>
This section describes how our build system interacts with your
daily work hacking on Jskad, Tibbibl, and the
translation tool.
</p>
<h5>Compiling</h5>
<p>
Compiling any of the tools is a simple matter.&nbsp; First, ensure
that you are in the <code>Jskad/</code> directory of your <a
href="#sandbox">sandbox</a>.
</p>
<p>
Now run <code>'ant <i>program</i>-compile'</code> to create a
directory tree <code>Jskad/bin/<i>program</i>/</code> that contains
all the .class files and needed resources (.ini files, .xsl files,
et cetera).
</p>
<p>
Or you may run <code>'ant <i>program</i>-dist'</code> to create a
JAR file <code>Jskad/dist/lib/<i>program</i>-vanilla.jar</code> that
contains all the .class files and needed resources, but does not
contain any third-party JARs.
</p>
<p>
You may also run <code>'ant <i>program</i>-jws'</code> to create a
Java Web Start release.&nbsp; See <a href="#relwebstart">below</a>
to learn more about this.
</p>
<p>
<b>Gotcha:</b> We currently have the build system set up so that it
builds a program, say Jskad, given merely the name of the main
class, say <code>org.thdl.tib.input.Jskad</code>.&nbsp; This means
that our releases include only classes that we're actually
using.&nbsp; But it also means that your changes to any but the main
class will not cause recompilation.&nbsp; You must use <code>'ant
clean'</code> before recompiling.&nbsp; In addition, you should
clean after any cvs update.
</p>
<p>
The alternative to specifying just the main class is specifying
every needed class.&nbsp; If you do this, Ant often rebuilds the
correct classes.&nbsp; But you may have to modify
<code>build.xml</code> when you add a new file, and your releases
may include vestigial classes.
</p>
<h5>Running</h5>
<p>
Running the tools is easy for a developer.&nbsp; Just run <code>'ant
<i>program</i>-run'</code>, where <i>program</i> is one of
<code>jskad</code>, <code>tt</code>, or <code>tibbibl</code>.&nbsp;
This deals with classpaths and all of that, and it compiles
beforehand if needed.&nbsp; Note the gotcha above if you're
rerunning after changing the source code -- you'll have to use
<code>'ant clean <i>program</i>-run'</code>.&nbsp; If you modify a
resource, such as <code>Jskad/source/options.txt</code>, there are
no gotchas -- Ant is smart enough to handle this.
</p>
<h5>Generating API Documentation<a name="makeapidocs"></a></h5>
<p>
While you're hacking, use our <a href="api/"> API docs on the
web</a>, or build your own Javadoc API docs using <code>'ant
public-javadocs'</code> (to see only protected and public members)
or <code>'ant private-javadocs'</code> (to see all members).&nbsp;
They'll be waiting for you in
<code>Jskad/docs/{public,private}-javadocs/</code>.&nbsp; If you
want to update the API docs on our website, follow <a
href="#updateapidocs">these instructions</a>.
</p>
<h5>Integration with IDEs such as Eclipse</h5>
<p>
Nowadays, any good Java IDE is aware of Ant and will let you use Ant
for the things it is good at while using the IDE for the things it
is good at.&nbsp; Ask David Chandler how he got Eclipse up and
running; he did it without too much trouble.
</p>
<h5>Testing<a name="testingjskad"></a></h5>
<p>
Testing is an underappreciated part of software development.&nbsp;
Software without a good test suite costs more money and time to
maintain, and it can eventually become downright demoralizing when
you can't seem to make a simple change without breaking part of the
code.&nbsp; If you see the break immediately, it's no big
deal.&nbsp; When you have a solid test suite, you're much more
likely to make changes with confidence.
</p>
<p>
But testing isn't just for us, the developers.&nbsp; It's mainly to
give the user confidence (though hearing from us about our
extensive, automated test suite is the direct method whereby the
user gains this confidence).&nbsp; For key parts of our system,
parts that we hope others will trust with their most precious data,
we need excellent testing, design, and documentation.&nbsp; For
other parts of the system, where failure is obvious (like GUI
interfaces), testing can slide more easily.
</p>
<p>
The core modules dealing with Tibetan text are thus going to be
heavily tested, mainly by unit tests and end-to-end regression tests
that ensure that the software still does what we verified by hand it
should do.&nbsp; If we don't do this, can you imagine someone
entrusting us to convert their Kangyur, in its Roman
transliteration, into Unicode?&nbsp; Don't imagine they will just
glance at the first and last page of the converted text and sign off
on our fine tool.
</p>
<p>
In short, the test suite determines whether our software is
well-receieved or merely well-intentioned.
</p>
<p>
We use <a href="http://junit.org/"> JUnit</a> to provide automated
unit tests.&nbsp; Running them is as simple as making Ant aware of
JUnit (see below) and then running <code>'ant clean
check'</code>.&nbsp; If there are any failures, you should examine
the files <code>Jskad/TEST-*</code> and track them down.
</p>
<p>
To make Ant aware of JUnit, simply copy
<code>Jskad/extensions/to-be-installed-with-ant/junit.jar</code> to
the <code>$ANT_HOME/lib/</code> directory (and, if you're on
UNIX/Linux, make the file world-readable).&nbsp; More details are
provide <a href="#installant"> above</a>.
</p>
<p>
To make future testing easy, you should use interfaces rather than
hard-wiring in calls to classes that are difficult to
instantiate.&nbsp; For example, if we were to make use of a database
class in our DuffPane class, doing so directly would mean that the
database software would have to be properly installed and up and
running in order to test DuffPane individually.&nbsp; If you create
an interface and use the database only through that interface, then
creating a <a href="http://mockobjects.com/"> mock object</a> that
pretends to be that database but returns canned answers is a simple
matter.
</p>
<h5>Modifying <code>Jskad/build.xml</code></h5>
<p>
Should you need to modify the Ant build file
<code>Jskad/build.xml</code>, feel free to ask David Chandler to do
it for you.&nbsp; Or just look at the contents of that file and find
something similar to what you're doing.&nbsp; There are a few
comments in the file, and all commonly used functionality is
factored out into targets that are then summoned via
<code>antcall</code> tasks.
</p>
<h4>Why we chose Java Web Start and how it works<a name="webstart"></a></h4>
<p>
<a href="http://java.sun.com/products/javawebstart/"> Java Web
Start</a> makes it possible (in theory, anyway) to install a complex
application like Jskad with one mouse click of a link in your
favorite web browser and one more click of a "Yes, install Jskad"
button in a dialog box (necessary because our applications require
security privileges to read and write from disk etc.).&nbsp; Upon
the second run of the program, Java Web Start asks the user if they
want to create shortcuts on their computer.&nbsp; Also, any time the
program is invoked (from a shortcut or a web link) and a network
connection is found, new versions of the software will be downloaded
automatically, keeping the user up to date.
</p>
<p>
In addition, the <a href="http://www.vamphq.com/"> Venus Application
Publisher</a> provides a mechanism for creating CD-ROM-based
installers that load our Java Web Start code into the user's Web
Start cache directory.&nbsp; Then running the software will check
for updates as described above.&nbsp; (I don't know if we'll ever
use this, and it's kind of ugly, but it's here.)
</p>
<p>
For the above scenario to play out, the user must have installed a
recent (1.2 or later) Java runtime environment.&nbsp; That's it from
the user's point of view.
</p>
<a name="webstartserver"></a>
<p>
The web server that delivers the content must associate the MIME
type application/x-java-jnlp-file with the "jnlp" extension and must
associate the MIME type application/x-java-archive-diff with the
"jardiff" extension.&nbsp; In addition, if you want to be able to
serve up a new release with the least difficulty (simply dropping a
.war file (a Java Web ARchive) into the appropriate directory on the
server), the server must run a J2EE application server such as
Apache's Tomcat.
</p>
<h4>Cutting a Java Web Start release<a name="relwebstart"></a></h4>
<p>
For the reasons stated above, Java Web Start (JWS) is our
distribution mechanism of choice.&nbsp; But cutting a Java Web Start
release is not the easiest thing you've ever done.&nbsp; For one
thing, because our applications require access to the local disk,
they must ask for security privileges.&nbsp; JWS warns users not to
grant such privileges unless they know the software provider is
trustworthy.&nbsp; Trust depends in turn on identity, and identity
is proven by public key cryptography.&nbsp; So to cut a JWS release,
you have to sign your JARs and rejar and sign any third-party
JARs.&nbsp; (If signing JARs is new to you, the J2SE documentation
on the subject is okay, but hopefully reading below will tell you
all you need to know.)
</p>
<p>
First, be sure you've installed Vamp's Ant task as described <a
href="#installant"> above</a>.&nbsp; You can do many day-to-day
development activities without performing this step, so don't assume
that you must have already done it.
</p>
<p>
Second, create the release notes and the changelog.&nbsp; These
should be two different text files.&nbsp; Somewhere in one or both,
you should mention the versions of the third-party JARs and APIs
that we have packaged with our release.&nbsp; <b>Most importantly,
put in a link to the web server on which you're going to put the web
start release!</b>&nbsp; Commit these text files to the repository
(adding them first if necessary).
</p>
<p>
Third, commit any changes you've made to the repository.&nbsp; After
being sure that your <code>Jskad</code> directory is a mirror of the
one in the repository, use cvs to tag this revision that you wish to
release with a name that another developer, years down the road,
will recognize as referring to this release.&nbsp; To do this, you
can run <code>'cvs -f rtag <i>tag-name</i> Jskad'</code> or (and
this is preferred) you can run <code>'cvs -f tag -c
<i>tag-name</i>'</code>.&nbsp; Good tag names are like the
following:
</p>
<ul>
<li>
<code>thdl_tools_1_0</code> (referring to the 1.0 release of the
Jskad module)
</li>
<li>
<code>September_23_2002_release</code> (referring to the release
of all programs in <code>Fonts</code> module made on September 23,
2002
</li>
</ul>
<p>
As you may have inferred, we release all four programs when we
release any one of them.&nbsp; This is only a half-truth, though--we
release the unified source distribution any time we release a binary
distribution, but we don't necessarily put out all four binary
distributions in unison.
</p>
<p>
Now run
</p>
<blockquote><code>ant -Dkeystore="file:///c:/thdl/sandboxes/Jskad/your.keystore"<br>
&nbsp;&nbsp;&nbsp;&nbsp;-Dkeystore.password=baz<br>
&nbsp;&nbsp;&nbsp;&nbsp;-Ddgkey.password=foo<br>
&nbsp;&nbsp;&nbsp;&nbsp;-Dkey.alias="Johnny Developer"<br>
&nbsp;&nbsp;&nbsp;&nbsp;-Djnlp.codebase="http://your.web.server/THDL_STUFF"<br>
&nbsp;&nbsp;&nbsp;&nbsp;<i>program</i>-jws'</code>
</blockquote>
<p>
where <i>program</i> is one of <code>jskad</code> or
<code>tt</code>.&nbsp; This cleans first, so your changes will be
respected.&nbsp; This then creates a WAR file
<code>Jskad/dist/java-web-start/<i>program</i>-JWS.war</code>.&nbsp;
This also extracts the signed JAR from inside that WAR, which is
handy if you're deploying to a web server that isn't running a J2EE
application server.&nbsp; More on that below.
</p>
<p>
The argument to <code>-Dkeystore</code> is a URL like
<code>file:///c:/foo/keystore</code>.&nbsp; This should be a
keystore that you've created with keytool.&nbsp; We haven't yet paid
the money to get a real X.509 key, so create your own.&nbsp; Users
will see a nasty warning saying that we may not be who we say we
are, but so be it.&nbsp; Each key in your key store has an
associated alias, such as your name.&nbsp; Specify it as the
argument to <code>-Dkey.alias</code>.&nbsp; The other two arguments
are the password for the keystore as a whole
(<code>-Dkeystore.password</code>) and the password for the specific
key whose alias you're giving.
</p>
<p>
Inspect the output for warnings.&nbsp; Ignore the warning about
<code>"[vampwar]
org.apache.velocity.runtime.exception.ReferenceException: reference
: template = html/test.html [line 37,column 14] : $jnlp-url is not a
valid reference."</code> but fix any others.
</p>
<p>
If you wish to deploy to a J2EE application server, such as Apache's
Tomcat, now copy the <code>.war</code> file to the server.&nbsp;
You're done with the binary part of the release.
</p>
<p>
If you're deploying to a plain-vanilla web server, first ensure that
its MIME type associations are correct (see <a
href="#webstartserver">above</a>).&nbsp; Now ignore the
<code>.war</code> file and copy the appropriate <code>.jnlp</code>
file(s) and the appropriate JAR(s) from
<code>Jskad/dist/java-web-start/</code> to the webserver.&nbsp;
Those two files are all you need, and you don't need to edit the
<code>.jnlp</code> file because you specified the
<code>jnlp.codebase</code> property.
</p>
<p>
Now put up a source release on SourceForge's File Release System
(FRS).&nbsp; After ensuring that you've made NOT EVEN ONE CHANGE to
your sandbox, and after updating it, and after verifying that this
revision is cvs-tagged appropriately, use <code>'ant
src-dist'</code> to create
<code>Jskad/source/THDL-Tools-src-<i>todays-date</i>.zip</code>.&nbsp;
Now put this zip file up on the FRS with the appropriate release
notes and changelog (which should have been committed and tagged in
the repository).
</p>
<p>
You're done!&nbsp; <b>Except, of course, for the gotcha:</b> At
present, only the translation tool and Jskad have working Java Web
Start releases; Tibbibl's is on the way.&nbsp; Tibbibl, like Jskad,
requires all-permissions security.&nbsp; That means that
<code>xalan.jar</code>, <code>xercesImpl.jar</code>, and
<code>xml-apis.jar</code> [or whichever subset is used...] need to
be jar-signed by the same certificate as Tibbibl.&nbsp; We do this
automatically via <code>'ant self-contained-dist'</code> or
<code>'ant web-start-releases'</code>, but here's how to do this
manually:<!-- DLC FIXME: automate this further. -->
</p>
<ol>
<li>unjar these jars.</li>
<li>delete their META-INF directory, which i think contains signature info.</li>
<li>rejar, then sign with appropriate certificate.</li>
</ol>
<p>
Now send an e-mail to <a
href="mailto:thdltools-announce@lists.sourceforge.net">
thdltools-announce@lists.sourceforge.net</a> telling users where the
JWS binary release is, where the source code distribution is, and
why they should upgrade or try it out.
</p>
<p>
Please
<a href="mailto:thdltools-devel@lists.sourceforge.net">
e-mail us</a>
your comments about this page.
</p>
<p>
The
<a target="_blank" href="http://www.sourceforge.net/projects/thdltools">
THDL Tools</a>
project is generously hosted by:
<!--
DO NOT DELETE THE SF.NET LOGO.
We have a choice of colors and sizes for this logo (see
"https://sourceforge.net/docman/display_doc.php?docid=790&group_id=1"),
but we do not have the option of removing it. SourceForge requests
that we put it on each web page for our project, and to give us
incentive to do so, they will not track the number of hits for our
project web pages unless we put this link in. To track hits, see
"http://sourceforge.net/project/stats/index.php?report=months&group_id=61934".
-->
<a target="_blank" href="http://sourceforge.net/">
<img src="http://sourceforge.net/sflogo.php?group_id=61934&amp;type=1"
width="88" height="31" border="0" alt="SourceForge Logo">
</a>
<!-- AGAIN, DO NOT DELETE THE SF.NET LOGO. -->
</p>
</div>
</td>
</tr>
</table>
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink