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, ...).
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, or ../argouml/tools/apache-ant-X.X.X/bin/ant arg, depending on if you work from the argouml directory, the argouml/src/argouml-build directory, or a module in a subproject such as argouml-cpp 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: 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.
Compiling for Unix and Mac OS X
Here is what you need to do in order to compile and run your checked out copy of ArgoUML under Unix or Mac OS X. If building on Mac OS X make sure you have the current Developer Tools from Apple (see ADC/Mac for details) installed.
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.
Change the current directory to the directory you are building
cd /your/checked/out/copy/of/argouml/src
Start Ant with no parameters to get a list of build targets with descriptions
./build.sh
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.
Compiling for Windows
If you do this from Cygwin you work just like for Unix.
set JAVA_HOME=\where\you\have\installed\jdk
Change the current directory to the directory you are building
cd \your\checked\out\copy\of\argouml\src\argouml-build
Start Ant with "-p" parameter to get a list of build targets with descriptions
build -p
- Run ArgoUML using build run
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.
Building the core ArgoUML
If you work with ant you will want to check out and build the entire project. You do this with the install target.
Change the current directory to the directory you are building
cd /your/checked/out/copy/of/argouml/src
Start Ant with no parameters to get a list of build targets with descriptions
./build.sh install
This will build all of the core of ArgoUML and copy it to the build directory where sub-projects expect to find it.
Building one of the sub-projects
If you want to run ArgoUML with modules enabled the build.xmls are set up to do this in two ways:
- Test just one sub-project
- Build the core ArgoUML (See above)
- Run the module
This is done with run ant-target in the directory of the sub-project in question.
- Test several sub-projects together
- Build the core ArgoUML (See above)
- Compile and install the sub-projects
This is done with install ant-target in each of the sub-projects' directory. The install ant-target copies the jar or jars of the module to the argouml/build/ext directory.
- Start ArgoUML
This is done with run ant-target in the argouml directory. This will start ArgoUML with all the modules "installed".
Developing in a sub-project without compiling the ArgoUML core yourself
Download and unpack the latest release of ArgoUML and located it in the argouml\build directory.
C:\Work>mkdir argouml C:\Work>jar xf ArgoUML-0.34.zip C:\Work>move argouml-0.34 argouml\build
Check out your subproject.
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.
The sub-project's relation to ArgoUML
The purpose of a sub-project 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, 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.
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.
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 and generates a html report with the result. This probably requires the junit.jar tool from the argouml project.
- tests-xml (if tests exists) - This runs all the JUnit test cases available in the module.
Troubleshooting the development build
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 get it all again from the repository in a new copy.
Another reason might be that you have a 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!
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.