Source Code Organization and Build System

Design > Source Code Organization and Build System

Release Information

Project:	PROJECT-NAME
Internal Release Number:	X.Y.Z
Related Documents:	Example build.xml for Tomcat Apache Ant manual LINKS-TO-RELEVANT-STANDARDS LINKS-TO-OTHER-DOCUMENTS

Overview

TODO: Answer the questions below to help you define your source code organization and build process. Consider how the sample text relates to your project. Add, edit, or delete text as needed. E.g., not all projects try to be platform independent.

What are the most important facts that a developer should know about this source code organization and build system?

It roughly follows the standard proposed in the Tomcat documentation and is very similar to the organization used in projects at the Apache Software Foundation.

It follows our corporate standard: STANDARD-NAME.

Any new developer should keep the following in mind:

DO NOT check in any configuration file with a valid password. Instead, use your ~/default.properties to configure database access and other passwords.
If you find that newly updated code does not work, try to update the lib/ directory and do a clean build before asking for help.
Don't add any new directories before discussing it with PERSON-NAME.

What are the ranked goals of this source code organization and build system?

Separation of files by type
Separation of version-controlled files from files generated by the build process
Compatibility with standard build processes
Platform independence

Key Directories and Files in Developer Working Copies

TODO: Describe the purpose of each directory that will appear in a developer's working copy, also include any files that are important to the build process or runtime file structure. Indicate which files will be under version control (VC).

Path	VC	Description
build.xml	Yes	Build file
build.properties	Yes	Build properties file
src/	Yes	Source code
src/java/	Yes	Java source code
src/java/[Nested packages]/	Yes	Java source code of classes in each package
src/java/[Nested packages]/test/	Yes	Java source code of unit tests for classes in each package
web/	Yes	HTML and JSP files
web/css/	Yes	CSS files, if any
web/images/	Yes	Image files, if any
web/WEB-INF/web.xml	Yes	Java web application configuration file
conf/	Yes	Configuration files, if any
data/	Yes	Initial data to load into database and/or file system, if any
lib/	Yes	Libraries reused by this project, if any
scripts/	Yes	Command-line utility scripts used by this project, if any
www/	Yes	Project documents (e.g., overview, plan, requirements, and design)
build/	No	Output of build process
build/WEB-INF/classes/	No	Compiled code output by build process
dist/docs/api/	No	API documentation output from build process
dist/PROJECT-NAME-VERSION.war	No	Deployable web archive of classes and configuration files generated by build process

Build Targets

TODO: Describe the build targets that developers will use in daily development. Adjust the reusable sample text below to fit your project.

Target	Description
compile = default	Compiles Java source code and creates .class files under the "build" directory.
dist	Packages the system for distribution/deployment to servers or end users. Specifically, it creates .war archive of compiled classes and configuration files.
install	Places executable code into a location where it will actually be executed. Specifically, it copies .war file into Tomcat's webapps directory for use. You must then restart Tomcat or use the "reload" link in the Tomcat Manager.
javadoc	Generates Java API documentation under "build/docs/api/".
clean	Deletes files generated by previous build commands. Files under version control are not touched.

Build Configuration Options

Property	Description
app.name	The name of this application. This should be one short word. Used in the name of resulting package files. Specifically, the .war file. And, it will be used to access the application via http://localhost:8080/APP.NAME/
app.version	Version number of this release. Used in the name of resulting package files. Specifically, the .war file.
webapps.path	Path to the Tomcat "webapps" directory. Defaults to `C:\Program Files\Apache Group\Tomcat 4.1\webapps\`

Note: These build system properties can be modified by editing the build.properties file.

Source Code Organization and Build System Checklist

Separation of files by type: Are files separated by type?: Yes. Except that application JSP and HTML files are in the same directory, which is convenient because sometimes we change an HTML file to be a JSP file.; Yes. Except under DIRECTORY, where we are keeping a legacy directory structure. We plan to revise this before MILESTONE.
Separation of version-controlled and non-version controlled files: To what extent has this been achieved?: It has been achieved. Everything is under version control except for the "build" and "dist" directories. No step in the build process should create or modify any file in any other directory.; It has mostly been achieved. Everything is under version control except for the "build" and "dist" directories. Some temporary files are created elsewhere, but we have configured the version control system to ignore them.
Compatibility with standard build processes: To what extent has this been achieved?: So far, so good. We can use build.xml files that are very close to the examples that come with Ant. One difference is that we keep our technical documentation under "www" rather than under "docs". Also, we have avoided the use of custom ant tasks.; We needed to add some things that are not usually done. Specifically, DETAILS.
Platform independence: To what extent has this been achieved?: We are using Ant, which is itself platform independent. The names of the files and directories should work across platforms because they do not rely on case-sensitive names. We assume that the utility scripts in the "scripts" directory support all needed platforms and we have not created directories for different versions of these files aimed at specific platforms.; We are using Ant, which is itself platform independent. The names of the files and directories should work across platforms because they do not rely on case-sensitive names. Our utility scripts are organized into directories for each supported platform.; We are focusing on a single platform for now. We will address multi-platform concerns before we complete MILESTONE.
Have these implementation decisions been communicated to the development team and other stakeholders?: Yes, everyone understands. Feedback is welcome.; No, this is a risk that is noted in the risk management worksheet.

TODO: Check for words of wisdom for additional advice on this template.

Company Proprietary