Login | Register
My pages Projects Community openCollabNet
This page describes how the generation is working and in some cases should work.

How to set up and run

First time (to test if it works and to start up on a new machine):

  1. Check that you have a machine with Subversion and Java installed. (Currently it must be a Unix machine because the scripts are developed for Unix. See also issue 5).
  2. Check out this project
    cd /where/you/check/out
    svn co http://argouml-gen.tigris.org/svn/argouml-gen/trunk argouml-gen
    cd argouml-gen
    
  3. Download the source.
    ./update.sh
    

    Investigation is in progress to see if this could be replaced by a command like:

    svn update http://argouml-gen.tigris.org/svn/argouml-gen/builds builds
    
    to allow building for several branches. The builds directory would then contain directories with externals pointing to the correct combination of directories checking out as builds/<directory>/argouml/src_new...

  4. Generate the reports you have had your eye on. In this example we use jdepend.
    export JAVA_HOME=/where/you/have/java/installed
    ./build.sh report:jdepend
    
  5. Examine that the result is what you expected. You can find the result in tmp/RESULT/reports/jdepend
  6. Discuss on the dev@argouml-gen.tigris.org mailing list how your resources will be best put to use in the project. This will result in a Content Developer role in the argouml-stats project so you can do commits.
  7. Check out the entire argouml-stats project (1GB on December 2006, 700 Meg on June 2006)
    svn co http://argouml-stats.tigris.org/svn/argouml-stats/trunk argouml-stats
    
  8. Test the committing
    ./copy-add.sh reports-myreports reports/jdepend
    ( cd argouml-stats/www/reports-myreports && svn commit -m'Testing a report.' )
    
  9. Set up cron to build and run regularly. Create a specific script for your host, put it in the perhost directory, and create a crontab file entry like:
    0 0 * * * cd /where/you/check/out/argouml-gen && perhost/yourhost.sh
    
  10. Monitor the commits on the commits@argouml-stats.tigris.org mailing list to see that it works.

How it is working

Here are what the different files do in the order they are invoked.

build.sh
sets up the classpath with all tools and starts ant.
build.xml
contains a list of all shores to perform. The report:*-targets are delegated to build-reports.xml or directly to the build file in the development project. If any of these targets fails, something is seriously wrong in the set-up.
reporting.properties
contains the list of tools used.
build-reports.xml
is all the details on how to build the reports for the argouml project. It is copied to tmp/argouml/src_new and started there. It is used as an extension to the tmp/argouml/src_new/build.xml from the ArgoUML project. There is one report:*-target for each different report. The other targets are just for supporting the reports.
copy-add.sh
copies from tmp/RESULT.
create-index.sh
generates the contents of the index.html file with an updated list of all existing reports.
update.sh
updates the checked out copy of the source
tools
contains all tools that are used to generate the reports.
perhost/closettop.sh
contains the setup for the host name closettop (Linus' host).

Design of the report scripts

The reports (or the part of the reports) that are maintained in the development project are self-contained. They have the tools within the development project. The result end up somewhere in the project/build directory. They can be run by any developer at any time.

The reports that are maintained within the argouml-gen project require both the argouml-gen and the appropriate development projects (according to update.sh) to run. The have (additional) tools within the argouml-gen project. The result end up somewhere in tmp/RESULT. These reports are started from build.xml using build.sh.

Reports that are maintained in the development projects are also started from build.xml using build.sh but then build.xml (and build-reports.xml) are just starting the report and copying the result to somewhere in tmp/RESULT.

build.sh, build.xml (and build-reports.xml), and the development project tools don't control the Java version (nor the OS version). The Java and OS version are controlled on a per host basis by the host-specific scripts.

The host-specific scripts also control what directory the result is copied into possibly depending on the Java and OS version. To do this the copy-add.sh script is used.

How to add a new tool

To add a new tool, you will do approximately the following.

  1. Decide on the name for the report. You probably have thought of some tool that generates it so you can reuse that tool's name.
  2. Add a report:name-target in build.xml.
  3. Assuming that the report is generated based on the argouml source, the report:name-target is a delegation to build-reports.xml.
  4. Add the needed tool to the tools directory.
  5. Add a property in reporting.properties pointing to the tool.
  6. Add a report:name-target in build-reports.xml that does all the work using the property to point at the tool. The result of this should arrive in tmp/RESULT/reports/name with the html file tmp/RESULT/reports/name/index.html as its starting point.
  7. Test it.
  8. Commit it.

Last updated $Date: 2007-06-29 11:28:02 -0700 (Fri, 29 Jun 2007) $.