This file provides an overview of the QCI Java Utilities package from the point of view of someone contributing code, maintaining the the package or otherwise building and changing the package. README.html provides a general overview of the project, its purpose, and contents.
We are a primarily UNIX/GNU/Linux based company. In documentation like this, we consistently use the UNIX (you may prefer to think of them as 'URL-style') conventions for talking about paths and locations. Feel free to automatically make the mental substitutions- we won't know.
Our use of this convention does not imply that the Java code or build process does not run on Windows. It does.
This project is hosted on SourceForge. SourceForge provides facilities for bug and task tracking, discussions, managing file releases and so forth. SourceForge also hosts the project web site, which contains an overview of the project and various subprojects plus links to the documentation.
This package and each subproject contains source code annotations which are used to produce HTML formatted JavaDoc. In addition to the JavaDoc comments in the Java code, JavaDoc also provides hooks for attaching package summary information, overview documents and examples. We try to take advantage of this ability to provide auxilliary information for understanding that package as a whole.
Each subproject also provides a README file to act as a quick overview and index as well as a Maintainer's README (this file) to give a more in-depth description of how the package is put together and maintained.
SourceForge provides a 'Documentation Manager', available from a tab on the SourceForge summary page for the project. We find that this facility is not useful for maintaining large, interlinked document trees, so we do not use it much. It is mainly used to store draft documents, technical memoranda and odd notes.
Following are the external packages and system settings required to build this package. The process by which our Ant scripts locate the required files and how they may be overridden is described below.
By default, required libraries are looked for in /netpkg-noarch/javalib/. This is controlled by setting the JAVALIB environment variable or by setting java.lib.dir in config/local/local.properties. The locations of libraries can also be specified individually two different ways. First, individual properties (e.g. junit.jar) may be specified to tell the build scripts that a particular library is not in the standard library directory. Second, individual libraries may be copied to lib/ext or lib/jdbc. The build scripts will automatically copy the required libraries from their central location into these directories in the local project. This allows you to insulate your local project from library upgrades in the central directory. If there is already a jar file in lib/ext/, it will not be overwritten.
The build process uses Ant from the Apache project. Ant provides a Java driven cross-platform build system which is enormously flexible. The build process is controlled from the build.xml file. This is an XML input file which defines tasks for Ant to perform. Running:
ant -projecthelp
Will list the available targets. 'testrun' is the most frequently used, followed by 'clean'. 'testrun' will build everything and run the unit tests. 'clean' will get rid of everything that was just built. 'javadoc' will build the API documentation (in docs/api/). You will want to examine the help for anything more specific and visit the Ant site to get an idea of how it works.
When you first check out the project from CVS or unpack the source distribution, most of the working directories are missing. The only directories that are included are those which contain source files. The remaining transient directories are created automatically by Ant when it is run. Specifically, the 'prepare' target does this, but 'prepare' is automatically invoked from every other target. 'distclean' will return the project to the check-out state, deleting the transient directories. 'squeakyclean' will perform a 'distclean' plus a 'sweep', which removes backup and temporary files left behind by editors.
The Java source is all under src/. src/app/ contains the source for the project classes, while src/test/ contains the source for the unit tests. application-html/ contains any html used in running the project or application. This comes from a generic project template and is not used here.
config/ contains various configuration files needed by the project, divided into subdirectories such as config/buildfiles/ (used by Ant), config/packagefiles (JAR manifests and so forth), config/test (functional test configuration, if present), and config/local/ (local settings which override the defaults in config/buildfiles/).
doc/ contains project documentation, including the javadoc (if built) under doc/api.
Java code is complied to classes which are stored in class/, mirroring the src/ structure. dist/ is a directory which may be used temporarily while constructing a distribution Jar or Zip (the actual archive ends up under lib/). lib/ contains copies of required external and locally built packages under lib/ext and lib/built, respectively. lib/jdbc is not used in this project. temp/ is a directory used as a scratch space for the build system.
reports/ contains files output from testing and running the package. reports/unit/ contains output from the tests.
As mentioned above, 'ant testrun' runs the test suite (building the package as necessary). The test suite uses the JUnit framework. The test suite class whcih is run by default is located in src/test/ProjectSuite.java. A message will be printed indicating the number of test run and success or failure. A summary/report is saved in reports/unit/summary/. Log information from testcases which extend com.qlue.util.logging.LoggerTestCase is saved in reports/unit/log/, one file per test method. Since this project provides the logging system, there are necessarily few tests which take advantage of this feature.
Although the test code and source code are in separate directory trees, they are organized into the same Java package. This means that test code does not need to import the code it is testing and may access package private data.
Version Info: $Id: README-Maintainer.html,v 1.5 2002/04/04 20:53:28 evought Exp $