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:
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.
ant clean
in the
components
directory.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. 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.
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:
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. build.xml
script. 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
. 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:
README
file in each component must list the
leaf packages used by that component.package.html
file
(use the one in components/templates/package.html
as a
template) that describes the purpose of the package and the
component it lives in.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:
<echo
message="--component-name--" />
build.xml
in the test
subdirectory.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.
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.