$Author: bastafidli $
$Date: 2006/08/27 07:52:10 $
$Revision: 1.10 $
$RCSfile: buildprocess.html,v $
OpenSubsystems project is setup to allow convenient development cleanly separating all source files created as part of this project from those, which are part of external projects and those generated as part of the build processs or testing. All code for all subsystems is located in a single directory tree even though individual subsystems are separated by packages. This allows for easier and simpler development since developers can easily find code they can use and reuse as well as fix problems and add features in multiple subsystems as needed without worrying about switching from project to project.
While you are creating new code or modifying existing code within Eclipse development environment, Eclipse automatically compiles your files as they are modified. The Problems view shows you any syntactical or checkstyle errors, which were found during the build and you can conveniently fix them by double clicking the message for Eclipse to take you to the location of the error. Eclipse also provides Quick Assist to help you automatically fix the common problems.
The files compiled by Eclipse are placed into
Since Eclipse doesn't recognize individual components, classes directory contains compiled code for all subsystems. This speeds up development but it is not suitable for distribution, since when distributing OpenSubsystems, the desire is to build and package individual subsystems independently. That allows us to track dependencies between subsystems and it allows users to pick and choose, which subsystems they are going to use.
The build of individual subsystems is performed using Ant build scripts. All build scripts and build related files are located in
The main files contained in this directory are:
You can conveniently launch Ant from within Eclipse after you tell Eclipse, which subsystems you want to work with. Go to Window menu, select item Show view and select menu item Ant. New Ant View will appear in your Java perspective. Click the Add Buildfiles button on the toolbar to add Ant build files into this view. Browse to
directory and select build files for components you want to work with. For example you can select build-security.xml if you want to develop Open Security subsystems. Click OK to add the selected files. Once the files are in the Ant view, click the Hide Internal Target button on the toolbar to filter down the displayed Ant targets to show only the important ones.
Each subsystem has a single build script. You can add build scripts for multiple subsystems into the Ant view and work with them simultaneously. Each build script is in Ant view represented by a single item. The build script be expanded by clicking on the + icon next to the name of the subsystem it represents. Once the build script tree in Ant view is expanded it will reveal individual targets, the script provides.
Target represents a step in a build process, which can be executed. Build scripts for all subsystems have the same structure and offer the same targets. When you double click on the target, Eclipse will launch Ant to build specified target and all its dependencies. There are also dependencies setup between individual subsystems. If one subsystems requires for its correct functioning another subsystems, when the dependent subsystem is built, Ant will also build all the subsystems it depends on. These are the common targets provided by every subsystem:
The day to day development work consists of using the update target to quickly build only the modified files so you can launch the built subsystem. The build target is handy to rebuild the entire subsystem including JavaDoc documentation to discover any potential problems. If there is a problem, you can use clean or cleanall target to remove the generated files and then use build or all target to rebuild the subsystems and all its dependencies. Checkstyle and test targets are handy when you are building using automates script but for day to day developmen. The distribute target will build distribution packages once you are ready to distribute your subsystem. Eclipse provides better way to check you coding style and run jUnit tests.
Ant build script generates all files into
directory. For a given subsystem it creates a subdirectory with the same name as the name of the subsystem. For example for Open Security subsystem the directory is
The first step of the build process is to separate the source files applicable to this subsystems from all the other ones. The build script copies the source files into
directory. The rest of the build will then use only this subset of the files to build the subsystem. This step ensures that even though there is a single tree for all the subsystems, when the subsystem is built, it is absolutely clear, which source files are used to build it.
The second step of the build process is to collect all external libraries and files this subsystem requires. The build script copies the files into
directory. The rest of the build will then use only these libraries to build the subsystem. This step ensures that even though different subsystems use different external projects, when a specific subsystem is built, only its required projects are used to build it. It is also clear, which external projects are needed for this subsystem. During this step the build script also collects libraries from other subsystems this one depends on.
The third step of the build process is to build the subsystem. All the files collected in step 1 are compiled (using libraries collected in step 2), generated, precompiled and packated into
directory. JavaDoc documentation for the subsystem is at this time also generated into
The next step of the build process is to test that the built subsystem is valid. This is done by running automated JUnit test suite to verify functionality of the created subsystem. All files created by the test are placed into
directory. At the end an HTML summary report of executed tests is generated into
The last step of the process is to create distribution packages. All files created for distribution are placed into
During the package phase, the build process creates compressed archives for all executable code as well as the web application. Seven different files are created
The last and optional (therefore it needs to be executed explicitly) step of the build process is to create distribution packages. Three different packages are created
To rebuild subsystem from source just using the distribution packages and without getting the entire code from CVS you will need both src and bin packages. First you will unpack the src packages to directory named sources in your development directory. Next you will place the entire external directory from the bin package next to the sources directory in your development directory. Now you can just navigate into the build subdirectory of the directory sources and invoke build script build-[subsystem_name].xml.