build system overview

 BUILD SYSTEM (C) 2005 by Oliver Seidel (licensed under the GPL)



 Usage instructions:

 This system manages COMPONENTS. Each component lives in its
 own directory below the root. A component can be of three types:
 LIBRARY, MODULE, or APPLICATION. LIBRARIES do not feature a main
 class and cannot stand by themselves. MODULES have a class "Server",
 which features a demonstration of the module's capabilities in its
 main class, or permits the instantiation as a thread. APPLICATIONS
 combine several MODULES into a common, usable system. The source
 code of each component is in a package "net.os10000.bldsys.PKG".
 The file "components.xml" must contain a target for Apache ANT that
 goes by the name "PGK_local_build". It is invoked after unpacking
 the subsidiary components into the local build directory and before
 the standard compiler is invoked on the src directory and a jar file
 is constructed. The build system also expects the following lines
 int the file "component.xml": "component-project:", "component-depends:"
 "component-libs:". The text following each of these categories should
 consist of digits,characters,underscores and commas (where lists are
 required). The "component-depends:" lines of all these files describe
 a global dependency tree, which is an acyclic and directed graph with
 roots in the APPLICATION components. The build system cannot find
 components outside this graph. A fine example of a complex component
 is "mod_jnfsd". Each component must have the file "licensing.txt" and
 an "src" directory.




 This build system exhibits the following characteristics:

 1) this "build.xml" file
 2) a flat, 2-level directory structure
 3) standardised package naming
 4) a "component.xml" file in each of the directories with some metadata, and
 5) also with specialised build instructions for that component




 It is designed for speed through

 1) global dependency checking
 2) dependency caching in a single file ("auto_build.xml")

 and it is designed for simplicity through

 3) localised component descriptions




 It operates as follows:

 The file "auto_build.xml" is a cache for all build instructions to build
 each of the components: every ant invocation checks the dependencies of
 that file (very few, namely only the "component.xml" files) and only
 refreshes it if necessary. It then hands off that particular invocation
 to the that file.

 The file "auto_build.xml" (no it's not "Auto BILD" ... laugh if you're german)
 is constructed in such a manner that compilations are handled in the same way
 as that file itself: dependencies are checked first, only if necessary is
 the target re-compiled.