Diva source architecture

Contents

• Overview
• Packages
• Documentation directory

See also:

Overview

Diva is structured as a set of packages. Generally, each top-level package has a primary architect (sometimes two), who is responsible for architecting, documenting, and releasing that package. Each package is a Java package, so the directory name has to match the package name.

The top-level directory is named diva and has this structure:

    diva/
        README.txt
        makefile
        bin/
	doc/
        mk/
        package-1/
	package-2/
	...

• README.txt contains a brief description of Diva.
• makefile is the top-level makefile
• bin contains configuration management scripts
• doc is the documentation tree.
• mk contains shared makefiles

Packages

Top-level packages have the following structure. The configuration scripts tend to assume this structure.

    package/
        package.html               Description for javadoc
        demo/                      Demo files (Java)
        test/                      Test files (Java)
        makefile                   Recompile sources
        *.java                     Java source
        *.class                    Compiler output
        subpackage-1/       Subpackages
        subpackage-2/
        ...

Some notes:

• package.html contains a brief description of this package. It is read by javadoc and included in the generated API documentation.

• The demo directory contains a single demo application that show features of this package. It is invoked by the "run" rul of the makefile. Any demos that have a useful purpose get their own sub-package -- they don't go into demo.

• The test directory includes tests for the top-level package at its top-level. Tests for sub-packages are subdirectories within this directory.

• Two other directories that may appear are treated specially by the configuration scripts. scratch contains classes that compile, but are not released, and junk contains classes that may not even compile, and obviously don't get released.

The structure of sub-packages is minimal:

    subpackage/
        makefile                   Recompile sources
        *.java                     Java source
        *.class                    Compiler output

Note that test classes for the subpackage go in the test/ directory of the top-level package. Demo go in the demo directory of the toplevel package.

Documentation directory

The documentation tree in Diva is contained in the top-level doc directory. Documentation is not scattered throughout the source tree.

The documentation directory has this structure:

diva/
    doc/
        index.html            Index
	*.html                HTML files
        about                 General information about Diva
        admin                 Restricted administrative documentation
        api                   javadoc-generated documentation
        demo                  Static and on-line demos
        download              The Diva distribution
        images                Images used through-out the Web pages
        packages              Static and on-line demos
            package-1/     Package docs, one per top-level package
	    package-2/
	    ...
        templates             Files used to build the Web pages

The structure of the documentation for each package is flexible, but the following is typical:

     index.html          Overview page
     *.html              Introductory pages
     design/             The design document
     guide/              Programmer's guide
     reviews/            Minutes of all design and code review