Login | Register
My pages Projects Community openCollabNet

2020-03-13: This site is going to be decommissioned and shut down very soon. Please copy and archive any data you wish to keep ASAP

2.6. Build Process

[Note]Note

This needs to be updated with the Eclipse-orientation.

When building from the command line, the build process is driven by Apache Ant using the ant distribution provided in the tools directory.

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, and there is one in each mini-project directory: (argouml/src/argouml-app, argouml/src/argouml-core-infra, argouml/src/argouml-core-model, argouml/src/argouml-core-model-euml, argouml/src/argouml-core-model-mdr, and argouml/documentation).

2.6.1. How Ant is run from the ArgoUML development environment

For your convenience the ant tool is present in the source repository of ArgoUML in the file argouml/tools/apache-ant-X.X.X directory.

It is possible to start ant with the command tools/apache-ant-X.X.X/bin/ant arg, ../../tools/apache-ant-X.X.X/bin/ant arg, ../argouml/tools/apache-ant-X.X.X/bin/ant arg, or ../tools/apache-ant-X.X.X/bin/ant arg, depending on if you work from the argouml directory, the argouml/src/argouml-build directory, a module in the argouml-cpp directory, or the argouml/documenation directory respectively.

On windows the script to run is the 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.

[Note]Note

Some of the build.<sh|bat> files have been removed in the repository restructuring, (issue #4625).

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

To use another version of Ant than the one provided in the repository you must execute /where/ever/you/placed/your/new/ant target rather than build target.

2.6.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

  3. Start Ant with no parameters to get a list of build targets with descriptions

    ./build.sh

  4. Run ArgoUML using ./build.sh run

If you change something, running the run target again will build and run.

In certain cases when something is changed in the argouml project you need to use the "clean" target to re-compile everything, since we have not set up dependencies correctly.

2.6.1.2. Compiling for Windows

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

  1. set 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\argouml-build

  3. Start Ant with "-p" parameter to get a list of build targets with descriptions

    build -p

  4. Run ArgoUML using build run

2.6.1.3. Customizing and configuring your build

If you want to customize your build, change the appropriate build.xml or default.properties file.

Don't commit these changes unless you are working with updating the development environment itself.

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 just as you would do before other commits.

2.6.1.4. Building Javadoc

By running Ant again using build prepare-docs the Javadoc documentation is generated and put into trunk/src/build/javadocs.

2.6.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 the core ArgoUML

      This is done with install ant-target in the argouml directory.

    2. Run the module

      This is done with run ant-target in the argouml-whatever directory.

  2. Test several modules together

    1. Build the core ArgoUML

      This is done with install ant-target in the argouml directory.

    2. Compile and install the modules

      This is done with install ant-target in each of the argouml-whatever directories.

      The install ant-target copies the jar or jars of the module to the argouml/build/ext directory.

    3. Start ArgoUML

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

    This will start ArgoUML with all the modules "installed".

2.6.2. Developing in a subproject

This describes how to do development in one of the ArgoUML sub-projects.

If you are in a hurry:

C:\Work>mkdir argouml
C:\Work>mkdir argouml\build

Download and unpack the latest release of ArgoUML into this directory.

C:\Work>svn checkout http://argouml-XX.tigris.org/svn/argouml-XX/trunk argouml-XX
C:\Work>set JAVA_HOME=C:\Programs\jdkwhatever
C:\Work>cd argouml-XX
C:\Work\argouml-XX>ant run

An ArgoUML starts with the module from the subproject argouml-XX enabled.

That was the short version provided that, you are using Windows + JDK, you have ant installed, and the subproject in question does not require any of the ArgoUML tools to build.

If you don't understand this or it doesn't work, read the rest of the chapter that describes why and how in more detail.

2.6.2.1. The sub-project's relation to ArgoUML

The purpose of a subproject to ArgoUML is to develop things that are run within ArgoUML. In ArgoUML we call them modules, in other tools they are called add-ins or plug-ins.

If you want to start working with a module of your own you could do it by letting the ArgoUML project leader set up a subproject to ArgoUML for you. The benefits are:

  • You will inherit all the infrastructure from the ArgoUML project.

    This includes a site for your Subversion repository, mailing lists, web server..., a common way to set up the project, releases, bug fixes, static checks, and coding guidelines and license.

  • You get a community of ArgoUML developers that might monitor your work and fix problems, especially problems caused by changes that the developer makes to the ArgoUML API.

The draw-backs are:

  • You are forced to use the ArgoUML infrastructure

    Subversion, BSD license, coding guidelines.

  • You are forced to make your module Open Source.

    This is actually a Tigris policy.

If you decide not to make your module a argouml subproject, you can still benefit from using a similar set up as described here but since you have your module repository elsewhere, some adaptations are necessary.

The sub-projects are developed close to the ArgoUML project and reside in a similarly-looking subversion repository. We try to provide a working set of tools and instructions to fit the whole set of projects. These tools are sometimes located in the argouml project and sometimes in the subproject. Also, to compile the module, you need the argouml interfaces, and to run it you need argouml in place. In most cases the argouml interfaces is argouml itself so this distinction is mostly formal.

There are two ways to get the argouml in place w.r.t. your module. The ArgoUML source way and the quicker ArgoUML distribution way.

Using the ArgoUML source way you check out the argouml project alongside the subproject you are going to work with and build it. If you are doing development in the argouml project too, if the subproject in question requires a tool from the argouml project, or if your modules is on the bleeding edge of argouml development and you can't wait for distributions, this is the preferred way. You will need to update and rebuild the argouml project regularly.

Using the ArgoUML distribution way, you check out only your module and then download the ArgoUML distribution and work against that. This is the approach described in the beginning of this section. You will need to download and replace the ArgoUML distribution whenever you need a newer version to work against. You could also, at any point, upgrade to the ArgoUML source way to get to the bleeding edge.

The build.xml ant configuration file in the subproject and the argouml main project are set up to allow for both of these ways.

2.6.2.2. Working in a subproject

Each subproject has its own web site with documentation and plans of the subproject.

The subproject has its own commits mailing list that you need to join to monitor the commits. It also has its own dev mailing list where the people working within that subproject discusses the subproject. Join both of these mailing list to see what is going on in the subproject!

The sub-projects could use their own Issuezilla database but should preferably instead have issues registered in the ArgoUML Issuezilla. Every developer of a subproject needs to acquire an Observer role in the argouml project.

2.6.2.3. Targets in build.xml in a subproject

The following targets have the same documented meaning in all sub-projects:

  • clean - optional

    Removes files that are generated by running any of the other targets.

  • compile - optional

    Compiles the code. The result is in build/classes.

  • generate - optional

    This is a step that, if it exists, can be run before compile. The result of this is some files that are prerequisites for compile so the compile target runs this automatically.

  • install

    This builds the whole module and copies it into the ext directory in the argouml installation.

    The purpose of the ext directory is so that argouml can be started with several different modules started at once.

  • jar - optional

    This builds the whole module and puts the resulting jar file(s) in build.

  • run

    This starts argouml with this module active.

    This is the way to start this module with the newly compiled source.

  • tests - optional

    This runs all the JUnit test cases available in the module. This probably requires the junit.jar tool from the argouml project.

2.6.3. Troubleshooting the development build

2.6.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 svn update before trying to build again. If that doesn't work remove your checked out copy completely and get it all again.

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.6.3.2. Can't commit my changes?

You need to have a developer role in the ArgoUML project or in the subproject you are working with. If you don't, then you cannot do commits yourself. Discuss what you have done and how best to test it on the ArgoUML project developers mailing list or the developers' mailing list for your subproject. Get in contact with the active developers and urge them to 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 you may have problems. It is unknown if this is a problem in Subversion. Let the editor know if you find out.