diff --git a/htdocs/BuildSystems.html b/htdocs/BuildSystems.html index 5e7b34e..b5968a5 100644 --- a/htdocs/BuildSystems.html +++ b/htdocs/BuildSystems.html @@ -2,7 +2,7 @@ - + @@ -24,7 +24,9 @@ clear, repeatable procedures that software developers go by to compile, run, test, create documentation, and cut releases. Our build systems are fully automated, which provides a good basis for - collaborative development. + collaborative development. 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.

Table of Contents

@@ -144,61 +146,112 @@ 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. + a Java program. I compile, test, run, and build releases using + Ant, and really like it.

- Although Ant is for Java programs, it has enough features to make - it a viable choice of build system for non-Java stuff like our - Tibetan Machine Web fonts. + 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.

+

Installing Apache Ant

To install Apache's Jakarta Ant (or "Apache Ant" or simply "Ant"), - see the Apache Ant - website. 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->System->Advanced->Environment Variables) and the like. + you'll first need a JDK installed. I recommend getting Sun's latest + 1.4 JDK (yes, it's available for Linux too). Next, see the Apache Ant website. + 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->System->Advanced->Environment Variables) and the + like. One thing they don't tell you is that their binary + distribution ships with a ton of documentation in + $ANT_HOME/docs/ that can all safely be deleted if you + care about disk space.

- To test your installation, use cvs to checkout the - Fonts module. It has a simpler Ant build file + I recommend installing Ant yourself, and not using a package manager + such as apt-get or rpm. This is because the ordinary installation + has a well-known $ANT_HOME/lib directory in which we'll + wish to place a couple of JARs ( + junit.jar and Vamp), as described below. 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. +

+ +

+ To test your installation, use cvs to checkout either the + Fonts module or the Jskad module. The + Fonts module has a simpler Ant build file (Fonts/build.xml) than the Jskad module - has, so it's better for testing. Change directory to - Fonts and run the following command: + has, so perhaps it's better for testing. The Jskad + 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, + Jskad/build.xml, free of nonstandard constructs. + Change directory to whichever module you choose and run the + following command:

- ant clean dist + ant clean

- If you have any trouble, see Ant's FAQs and then e-mail David - Chandler. + The output shouldn't alarm you, and it should conclude with "BUILD + SUCCESSFUL". If you have any trouble, see Ant's FAQs and then + e-mail David Chandler.

- Now that you have a good installation of Ant itself, you may want - to install the Vamp Ant - task provided by the Venus - Application Publisher. You need this to cut Java Web - Start releases of Jskad, Savant, QuillDriver, and the - translation tool. You do not need it otherwise. + Now that you have a good installation of Ant itself, you probably + will want to install both JUnit and Vamp. These steps can wait + until later if you're not sure you'll be testing our software or + packaging our software for release. Here are the steps to install + them:

+ +

- Installing Vamp's Ant task is simple enough, and is in fact simpler - than Vamp's web pages of October 1, 2002 imply. That is, if you - have installed Ant 1.5.1 or later, then you can simply drop - vamp.jar into Ant's lib directory and - forget about changing your classpath. + Your build environment is good to go!

-

Setting things up to use CVS

@@ -301,14 +354,14 @@ name="buildingfonts">
  • - after being sure that your Fonts 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. To do - this, you can run 'cvs -f rtag tag-name - Fonts' or (and this is preferred) you can run 'cvs - -f tag -c tag-name'. Good tag names are like the - following: + after being sure that your Fonts 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. To do this, you can run 'cvs -f rtag + tag-name Fonts' or (and this is preferred) you can + run 'cvs -f tag -c tag-name'. Good tag + names are like the following: Note that tagging for a release of just the Tibetan Machine Web - fonts and not the Tibetan Machine fonts is no different + font and not the Tibetan Machine font is no different than tagging for a simulaneous release of both.
  • @@ -564,7 +617,7 @@ module

    You'll also need to checkout the Fonts module underneath the directory where you checked out the - Jskad directory. We put the TMW fonts into some JAR + Jskad directory. We put the TMW font into some JAR files, so the 'Jskad/Fonts/TibetanMachineWeb/' directory must exist.

    @@ -726,22 +779,67 @@ module
    Testing

    - We will soon use JUnit to provide - automated unit tests. Running them will be as simple as making Ant - aware of JUnit and then running 'ant check'. + Testing is an underappreciated part of software development. + 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. If you see the break immediately, it's no big deal. When you + have a solid test suite, you're much more likely to make changes + with confidence.

    - To make testing easy, you should use interfaces rather than + But testing isn't just for us, the developers. 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). 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. For other parts of the system, + where failure is obvious (like GUI interfaces), testing can slide + more easily. +

    + +

    + 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. If we don't do this, can you imagine someone entrusting + us to convert their Kangyur, in its Roman transliteration, into + Unicode? Don't imagine they will just glance at the first and last + page of the converted text and sign off on our fine tool. +

    + +

    + In short, the test suite determines whether our software is + well-receieved or merely well-intentioned. +

    + +

    + We use JUnit to provide automated + unit tests. Running them is as simple as making Ant aware of JUnit + (see below) and then running 'ant clean check'. If + there are any failures, you should examine the files + Jskad/TEST-* and track them down. +

    + +

    + To make Ant aware of JUnit, simply copy + Jskad/extensions/to-be-installed-with-ant/junit.jar to + the $ANT_HOME/lib/ directory (and, if you're on + UNIX/Linux, make the file world-readable). More details are provide + above. +

    + +

    + To make future testing easy, you should use interfaces rather than hard-wiring in calls to classes that are difficult to instantiate. 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. If you create an interface and use the database only through that interface, then creating a mock object that pretends to - be that database but returns canned answers is a simple matter. + href="http://mockobjects.com/"> mock object that pretends to be + that database but returns canned answers is a simple matter.

    @@ -821,7 +919,9 @@ module

    First, be sure you've installed Vamp's Ant task as described above. + href="#installant"> above. You can do many day-to-day + development activities without performing this step, so don't assume + that you must have already done it.

    @@ -850,8 +950,9 @@ module Jskad module)

  • - September_23_2002_release (referring to the - release of all programs in Fonts module made on September 23, 2002 + September_23_2002_release (referring to the release + of all programs in Fonts module made on September 23, + 2002
    • @@ -940,8 +1041,10 @@ module QuillDriver, like Jskad, requires all-permissions security. That means that xalan.jar, xercesImpl.jar, and xml-apis.jar need to be jar-signed by the same - certificate as Savant. We don't yet do this automatically , but here's how to do this manually: + certificate as QuillDriver. We do this automatically via 'ant + self-contained-dist' or 'ant + web-start-releases', but here's how to do this manually: