2011/12/21 - Jakarta has been retired.

For more information, please explore the Attic.



Having a common directory layout would allow for users familiar with one Jakarta project to immediately feel at home in another Jakarta project. The advantages are analogous to adopting a site-wide look-and-feel. Common Jakarta procedures strengthen the Jakarta brand.

The directory structure proposed here is based on best-practices as suggested by Jakarta committers. We recognize that the cost of changing an existing directory structure can be high. As such, this proposal is not binding.

Unless specified otherwise, the term project refers to a sub-project of the Jakarta project. The terms sub-project and project are used interchangeably and the intended meaning should be clear from the context.

This proposal is subject to approval.

Directory name Content Comment Under CVS Control?
LICENSE.txt A copy of the Apache License The LICENSE.txt should be placed at a prominent location. This file should have the suffix .txt so that it can be opened easily on platforms that use suffix mappings. YES
src/ Source code.

The code may be placed into separate source code directories by language, as in src/java/ and src/php/ for source code in the Java and PHP languages respectively. Other projects may separate the code according to function (src/share, src/testcases, src/compat). It is highly recomended that sub-directories be used under src/.

src/xdocs/ Documentation files in XML format. The Jakarta site uses Velocity/Anakia or Stylebook to transform dcumentation files in XML into HTML. The generated HTML files automatically inherit the Jakarta look-and-feel. Documentation is available. YES
docs/ Documentation files intended for the end user. The docs/ directory contain most of the documentation for the Jakarta sub-project. This includes Velocity/Anakia or Stylebook generated HTML files. This directory may also contain other documentation files. Generally, all documentation is stored in the src/xdocs/ directory and then "transformed" into this directory. It is then checked into CVS and checked out of CVS on the live website. This allows the user to browse the documentation on the local host without requiring network connectivity as well as on the live website. Alternatively some projects may place NO
docs/ or www/ Web site documentation. Some projects choose to check in documentation for their website to ease maintanence of site. This may be a superset of the documentation included in the documentation provided in distributions. If the project includes regular distributions then the website should be an image of documentation of last release. For projects that don't have regular releases and whos website does not have highly volatile information (news, bug reports etc.) then it is acceptable to use docs/ subdirectory otherwise the www/ directory is recomended. Once checked into the CVS it is expected that the documentation will also be checked out on live website. YES
www/index.html Starting point for browsing the documentation. Browsing the documentation locally should yield the same results as browsing the documentation on the sub-project home page on the Jakarta web site. YES
docs/api API documentation as generated by the Javadoc tool. Placing the API documenation under docs/api/ makes it slightly easier for other documentation files under docs/ to reference API documentation and vice versa. It is not recommended to check this into CVS. At some point, we will have the Alexandria project building the documentation for all of the Jakarta Projects and making the API documentation available that way. NO
tools/ or build/ Files required for building the sub-project. Building includes compiling source code, generating javadoc documentation, the creation of jar files and the distribution files in tar.gz or zip formats. YES
build.xml or build/build.xml The ANT build script. All Jakarta projects are required to use ANT as their build tool. Note, it is allowable to place this file at the top level directory structure. YES
build.sh build.bat Shell scripts for Unix and DOS environments to bootstrap the ANT build process. The existence of these files implies the existence of binary jar files, such as ant.jar and xerces.jar under CVS control Note, it is allowable to place the shell scripts in subdirectory build/. YES
tools/lib or build/lib/ Binary jar files required for building the sub-project. The jar files are added to the classpath by the bootstrapping shell scripts before invoking ANT. The jar files should consist of ant.jar as well as jar files needed for XML parsing.

The tools/lib/ or build/lib/ directory should contain jar files needed during build time and during build time only. If an XML parser is also required during the runtime of the project, then the jar files for the parser should be placed under dist/lib/.

dist/ This directory is an image of the distribution files. Hence why it is called "dist" (short for distribution). The contents of the dist/ directory should be enough to use the project. The particular format of distribution is project dependent. Some may generate a project.jar and a README while others may have dist the image of a .war file. It is commong to have dist/bin for scripts and dist/lib for jars related to runtime. NO
bin/ or build/ Intermediate files files generated while building the project.

It is to this directory that intermediate files are generated. Different types are generally generated to sub-directories (ie .class files stored in bin/classes, build/classes, .jar files in bin/lib or build/lib.

distributions/ This directory contains the project release distributions. These are often project.tar.gz, project.zip, project.rpm or project.war format.

There are generally two forms of releases. Binary releases and source releases. Binary releases consist of all the components end-users require to use the product. This may include jars and generated documentation.

A source release generally includes an image of CVS repository. Files excluded include any proposals/ or whiteboard/ code and the www/ directory. The source release will often include generated documentation.

This directory is meaningful only to release managers. End-user should be oblivious to it.

contribs/ Contributions not officially part of the sub-project. YES
whiteboard/ or proposals/ Revolutions and other untested code bases. It is here where developers will host revolutions, forks and other deviations of codebase. YES

It is recommended to include a .cvsignore file in top-level directory under CVS control in order to avoid the distracting "?" message output during CVS update.

If the source is in the Java language, then the package hierrarchy for a given project should start at org.apache.PROJECT. For example, for the Velocity project, the top-most package is org.apache.velocity.

When adding binary files to CVS, the -kb option is automatically used for common binary types. See the /home/cvs/CVSROOT/cvswrappers file for the exact types.

Should we also include directives for ANT build scripts, common target names, etc. in this document? [JSS] Yes.

About Jakarta

About Apache

Retired Subprojects