2.3. Build Process

The ArgoUML build process is driven by ANT, and it is highly recommend that you stick to that. There are people known to build from JBuilder or Netbeans, but always make sure that your work compile with the plain vanilla build process.

Ant is a tool written in Java developed for Apache that reads an XML-file with rules telling what to compile to what result and what files to include in what jar-file.

The rule file is named build.xml. There is one of those in every separate build directory (src_new, documentation, and modules/whatever).

2.3.1. How ANT is run from the ArgoUML development environment

For your convenience the ant tool of the correct version is present in the CVS repository of ArgoUML in the file argouml/tools/ant-1.4.1/lib/ant.jar.

Normally ant is started with the command ../tools/ant-1.4.1/bin/ant arg and in the modules ../../tools/ant-1.4.1/bin/ant arg . On windows the command ..\tools\ant-1.4.1\bin\ant arg runs the program ant.bat.

To keep you from having to write this and keeping track if you are working with a module or not there are two scripts (one for Unix and one for Windows) that are called build.sh and build.bat respectively present in most of the directories that contain a build.xml file. These two scripts run the equivalence of the above paths.

By setting JAVA_HOME to different values you can at different times build with different versions of JDK and java.

To use different versions of ANT, you are responsible for installing your own version. Also, you must execute /where/ever/you/placed/your/new/ant target rather than build target.

2.3.1.1. Compiling for Unix

Here is what you need to do in order to compile and run your checked out copy of ArgoUML under Unix.

  1. JAVA_HOME=/where/you/have/installed/jdk

    export JAVA_HOME

    This is for sh-style shells like sh, ksh, zsh and bash. If you use csh-style shells like csh and tcsh you will instead have to write setenv JAVA_HOME /where/you/have/installed/jdk.

  2. Change the current directory to the directory you are building

    cd /your/checked/out/copy/of/argouml/src_new

  3. Start ant using ./build.sh

    This gives you a list of targets with descriptions

  4. Compile and run ArgoUML using ./build.sh run

    You can do this over and over again when you have modified something or want to compile and run again.

2.3.1.2. Compiling for Windows

  1. set JAVA_HOME=\where\you\have\installed\jdk

  2. Change the current directory to the directory you are building

    chdir \your\checked\out\copy\of\argouml\src_new

  3. Start ant using build

    This gives you a list of targets with descriptions

  4. Compile and run ArgoUML using build run

    You can do this over and over again when you have modified something or want to compile and run again.

If you do this from Cygwin you work just like for Unix.

2.3.1.3. Customizing and configuring your build

It is possible to customize your compilation of ArgoUML.

If you issue the command build list-property-files you can see what files are searched for properties.

Don't change the argouml/src_new/default.properties file (unless you are working with updating the development environment itself). Instead create one of the other files locally on you machine. The properties in these files have precedence over the properties in argouml/src_new/default.properties.

Remember that if you do this, you have modified your development environment. To be sure that you will not break anything for anyone else when checking in things developed using this modified environment, remove these files temporarily for the compiling and testing you do just before you commit.

2.3.1.4. Building javadoc

By running ANT again using build prepare-docs the javadoc documentation is generated and put into argouml/build/javadocs.

2.3.1.5. Building one of the modules

If you want to run ArgoUML with modules enabled the build.xmls are set up to do this in two ways:

  1. Test just one module

    1. Build ArgoUML, the package

      This is done with ant package in the argouml/src_new-directory.

    2. Run the module

      This is done with ant run-command in the argouml/modules/whatever -directory.

  2. Test several modules together

    1. Build ArgoUML, the package

      This is done with ant package in the argouml/src_new-directory.

    2. Compile and install the modules

      This is done with ant install-command in each of the argouml/modules/whatever -directories.

    3. Start ArgoUML

      This is done with ant run in the argouml/src_new-directory.

    This will start ArgoUML with all modules available.

2.3.2. Generating documentation

This describes how the documentation is generated i.e. both what to do and how the setup works.

If you are in a hurry:

C:\Work>set CVSROOT=:pserver:guest@cvs.tigris.org:/cvs
C:\Work>cvs login   (use guest as password)
C:\Work>cvs checkout argouml/documentation argouml/tools argouml/lib
C:\Work>set JAVA_HOME=C:\Programs\jdkwhatever
C:\Work>cd argouml\documentation
C:\Work\argouml\documentation>build defaulthtml

The html version of the Cookbook, Quick-Guide, and User Manual are built and the result end up in. C:\Work\argouml\build\documentation\defaulthtml\cookbook, C:\Work\argouml\build\documentation\defaulthtml\quick-guide, and C:\Work\argouml\build\documentation\defaulthtml\manual respectively.

[Note]Note

From here on it is the old text that is more or less "Publishing ArgoUML" to be reworked.

2.3.2.1. How the ArgoUML web site works

Tigris provides the ArgoUML site to be edited through CVS. Everything that is checked in under argouml/www becomes immediately available at the URL http://argouml.tigris.org/ with some added decorations.

Example: The file argouml/www/project.html is available at http://argouml.tigris.org/project.html.

This is the way the site is maintained and updated.

2.3.2.2. The ArgoUML documentation

For the ArgoUML project the same documentation shall be available in both HTML, PDF and javahelp. To this end the documentation is written in docbook XML and generated into two versions of HTML (one page per chapter and one page for the whole book), PDF and javahelp.

We have tools that does the conversion from docbook XML to HTML and PDF. The conversion is done whenever you need to look at the result or when you want to present the final result on the web site.

There are currently three different books generated in this way, each into its own directory. They are cookbook (this document), manual and quick-guide. They are all generated and stored in the exact same way except for the name of the directory that is one of cookbook, manual or quick-guide. Below I will reference these directories using book.

When a new version of the documentation is to be made available on the web site the responsible document release person does the following:

  1. He checks out everything needed and a copy of the argouml/www.

    If wanted, the CVS repository could be tagged and then the tag can be checked out. This makes it possible to know exactly how a certain version of the documentation was generated.

  2. The documentation is generated using build docs.

    This generates all three books and the result appears in argouml/build/documentation/defaulthtml/book, argouml/build/documentation/printablehtml/book, and argouml/build/documentation/pdf/book.

    This has been done several times before while preparing the release so no problems are expected. If there are problems then the preparations were not good enough and the process is best stopped right here.

  3. All the old files are removed from the checked out copy of argouml/www/documentation/defaulthtml/book, argouml/www/documentation/printablehtml/book.

  4. New files are copied into the checked out copy of www on top of the previous files there replacing them.

    All the files are copied from argouml/build/documentation/defaulthtml/book to argouml/www/documentation/defaulthtml/book. The same for printablehtml and pdf.

  5. No longer used files in argouml/www/documentation are removed from CVS and new files are added.

    cvs -n update

    Watch for "Missing" and "Unknown" files.

    The missing files are scheduled to be removed by: cvs remove each of the missing files

    The "Unknown" files are scheduled to be added by: cvs add each of the added files

    This removing of missing files and adding of unknown files may seem backward but it is from the perspective of CVS. The missing files are the ones that were present in the previous version of the documentation and do not have a replacement, either because that chapter does not exist anymore or that the tool generates filenames differently. The Unknown files are files with filenames that for the same reason appear from one version of the documentation to the next.

  6. Commit the changes thus publishing it on the web site.

    cvs commit -m'New version of the documentation published'

  7. The PDF book is uploaded to the download page.

2.3.2.3. How we work with documentation

The developers or authors that work with the documentation or with the tools to generate the documentation (or anyone else interested in how it works) can generate the documentation like described above and examine the result in argouml/build. It is only the last part about checking in and uploading the result under argouml/www/documentation that requires write access in the CVS and some configuration management since it more or less is releasing the manual.

In order to do this you need to check out the whole of the argouml/documentation directory. You also need the directory argouml/lib and argouml/tools that contain the tools used: ANT, Fop, saxon, ...

The subdirectories of argouml/documentation, cookbook, manual, and quick-guide each contain one of the three books. The subdirectory docbook-setup contains two things. It contains the configuration files that control how the generation is done. It contains the XSL rules for all the generation. The subdirectory images contains all the required pictures for all the books.

When, in the documentation you run ./build.sh defaulthtml or one of the other targets that builds the documentation, all books are built. What happens is (the target internal-dispatcher):

  • The manual/argomanual.xml is copied by ant to manual/argomanual-generated.xml while doing substitution of tokens: (@VERSION@ to become the version as specified in default.properties)

  • The file manual/argomanual-generated.xml is processed by the special docbook-setup/create-imglist.xsl xsl script that generates a list of included images.

  • All included images are copied.

    The purpose of this is to only get the images actually used copied with the document that uses them and not all images.

  • The html is generated by processing the file manual/argomanual-generated.xml.

The file manual/argomanual-generated.xml is a temporary file that only exists while processing the xml. If editing the xml with a docbook editors you open the file manual/argomanual.xml and edit the unsubstituted file. The differences between the unsubstituted file and the substituted file are so small that it shouldn't make any difference.

2.3.3. Troubleshooting the development build

2.3.3.1. Compiling failed. Any suggestions?

It might be that some other developer has made a mistake in checking in things that contain errors, or forgotten to check in some files in a change. Look at the last couple of hours on the developers mailing list! It is probably on fire.

Another reason for problems is an unclean local source tree. This means that if you have updated different parts of your source tree at different times it might contain inconsistencies. If you suspect this, first try to fix it by doing build clean and cvs update -d before trying to build again. If that doesn't work remove your checked out copy completely and get it all again through CVS.

Another reason might be that you have an build.properties or argouml.build.properties file that you have been working with earlier and that is doing something. If in doubt, remove those files.

If nothing helps, ask the developers mailing list!

2.3.3.2. Can't commit my changes?

You need to have a developer role in the ArgoUML project. If you don't then you cannot do commit yourself. Discuss what you have done and how best to test it on the developers mailing list! Eventually someone will commit it for you.

Furthermore the checkout of your copy needs to be done with your Tigris id that has the Developer role. If you for some reason have earlier checked out a copy as guest and then made modifications, changed the CVSROOT variable you still cannot commit changes done in the repository since the checked out copy contains information on who checked out. For this reason, it is best to apply for an Observer role in the project if you are going to work with the source at all. The Observer role is probably granted within a couple of days (we welcome everybody!) and then you can check out with your Tigris id. This means that when you eventually are granted a Developer role you can continue working with the same checked out copy.