MAGNET project workspace structure

Last update: $Date: 2001/12/13 03:17:49 $

The basic philosophy behind the MAGNET workspace structure is to support component-based development, and to recognize the fact that we need to build different sets of components into systems for different purposes. In addition, there are top-level tools, documentation, and third-party libraries that cut across components and systems. Here's how your workspace is set up:

Overall Structure

doc
Top-level documentation, such as the project home page, high-level Use Cases and design notes, meeting minutes, etc. The master copy is the project developers website, so you can browse it either at http://www.cs.umn.edu/magnet or on your local system. Note that anything you check into this hierarchy will show up on the project website within half an hour.

The composite javadoc directory is in the api subdirectory. Please don't check anything into this hierarchy, since it will be discarded when javadoc is regenerated. If you want to use images in your documentation, put them in doc/images. The javadoc on the project website gets regenerated once a day.

bin
Executables and shell/batch scripts that are either from third-parties (like lp_solve) or are not associated with any particular component or system. There will probably not be much stuff here - the existing PSE-Pro executables will be removed soon, and anything put here needs to exist in both Windows and Linux form (lp_solve is here in source form, and someone who has the necessary tools to build a Windows executable is welcome to do that). If you need to write unix shell scripts that cannot be easily converted to .bat files, then Windows users will have to have the cygwin package to use them. Most do.
lib
Third-party jar and zip files. Current contents include junit, log4j, ant, jboss/ejb, apache-xml, jgl, and PSE-Pro. The jgl and PSE-pro stuff will go away soon and should not be used for new development.
dist
Destination for component jar files built by individual component build scripts. This directory is initially empty in a new workspace or after running ant clean in the components directory.
components
This is where you will find all the project code. At the top level is the master build.xml file. Each subdirectory will contain code, test cases, design documentation, and build scripts for an individual component. A component is a coarse-grained piece of functionality that has reasonably high cohesion and low coupling to other components (the util component fails the cohesion test). It is in these subdirectories that you would create project files for JDE, JBuilder, Together/J, etc. See below for details on the structure of a component.
systems
Subdirectories contain build scripts, configuration data, and documentation for systems (and some subsystems) built from the components. This is where we would create a directory for an experiment set such as the ones we did for aa01 and ijcai01.

Every top-level directory, and every component and system directory, will contain a file called "README" that provides a brief summary of the contents of the directory, along with appropriate instructions for building and/or using the contents.

Structure of a Component

A typical component directory contains a build.xml file for building the component, a README file, and project files for IDE's and other tools. Subdirectory structure looks like this:

src
Component sources. Because all our Java packages are prefixed with edu.umn.magnet, all the actual content will be down in src/edu/umn/magnet/.... Names of packages should be short and all lower-case in accordance with Java conventions. Names of components and systems should be mixedCase with initial lowercase. The Windows folks say that this works fine as long as nobody tries to create directories in the archive from a Win 98 machine.
classes
Target directory for the local build.xml file. You don't need to create this directory, and you should never add it to the archive. It gets created by the build.xml script.
test
JUnit test cases for the component, along with a build.xml script for running them. Unit testing requires a class called AllTests in test/src, and a set of individual test case classes, usually one per class to be tested, that live in the packages of their respective to-be-tested classes. Test-case classes live under the test/src hierarchy. Use components/templates/TestTemplate.java as a template for these test-case classes, and name them after their to-be-tested classes. For example, if you want to write test cases for a class edu.umn.magnet.Foo, you would write a test class edu.umn.magnet.FooTest, and you would add the name of this class to the list of test cases in AllTests.
design
Target directory for diagrams produced from Together, and any other design documentation and graphics that is specific to the component.

There are example templates of most of the types of files you will need to create in components/templates.

No two components may define code in the same leaf package. Within a component, typically the test case code lives in the same package as the code it's testing, although it's in a separate hierarchy under test as mentioned above. Component-package mappings are accessible in two ways:

Circular dependencies among components are forbidden! Do an ant clean at the components level periodically to make sure you have created "hidden" dependencies (hidden from you, that is). The nightly build/test process will find it if you don't, and it doesn't like to find problems of this sort.

The build.xml file for each component must have the following targets:

prepare
Any required set-up, such as building required components to satisfy dependencies. The first action under this target must be
   <echo message="--component-name--" />
to make it easier to keep track of what's happening when you build the system at the top level.
compile
Compile sources into the local classes directory. If you are using resource files, make sure they get copied over to the classes directory during this step. See the util component for an example.
dist
Generate the component jar file into the top-level dist directory. The name of a component jar file will be component.jar, where component is the name of the directory the component lives in.
test
Run the unit tests for this component by invoking ant on the build.xml in the test subdirectory.
clean
Clean up. Remove all artifacts that can be produced by the build process, and run the clean target in the test subdirectory. Don't remove jar files of other components.

The build.xml file for the test subdirectory within a component has a test target that builds and runs all tests, along with prepare, compile, and clean targets.

Systems

Subdirectories under systems are intended to represent running systems of various sorts. Examples are search-experiment setups, GUI demos, server setups, etc. The primary components of a system are a run script (both a unix shell script called run and a Windows DOS run.bat should be provided), log configuration files, and any other properties or other configuration files necessary to run the system. These environments may also contain data-analysis code for reduction of experimental data. There may be a build.xml file here if necessary; it isn't necessary if simply running components/build.xml does everything you need. Instructions for setting up and running the particular system should be provided in a README file.