9.2 Setting Up a Development Environment for Generated Files

9.2.1 Problem

You want to set up your development environment to handle generated files.

9.2.2 Solution

Create two directories at the same level as your source and build tree. The first directory contains generated source code and may be called something like src-generated. The second directory contains compiled code for the generated source and may be called something like build-generated.

9.2.3 Discussion

The best location for generated source files is in a directory at the same level as your source tree and build tree. Equally important is separating the compiled code for generated source files from the compiled code of nongenerated source files. This provides a convenient, easy to manage directory structure, as shown in Figure 9-1.

Figure 9-1. Directory structure for generated files
figs/jexp_0901.gif Why not place generated files in the source directory?

Placing generated files in the src directory causes version control tools to assume new files should be added to the repository, which is simply not true. Generated files should never be versioned, but rather the templates and scripts that are used to generate the files should be versioned.

  • DO NOT check generated files into your version control tool.

  • DO check the templates and scripts used to generate the files. Why not place generated files in the build directory?

Placing generated files in the build directory has its own problems as well. For starters, the build directory, by convention, contains compiled code, not source code. Another important reason to maintain separate directory structures is to keep your Ant buildfile simple and easy to manage. When you want to force code to recompile, simply delete the build directories. If you placed generated source files in the build directory, the Ant buildfile would need to exclude those files from being deleted. Introducing a directory specifically for generated files allows the Ant buildfile to remain simple. Why not place the compiled generated code in the build directory?

The build directory may seem like a natural location for compiled generated code. This type of setup has its problems, though. Developers typically use an IDE for quick development. If a developer rebuilds the entire project through the IDE, then all of the compiled code may be deleted. The IDE has to rebuild all source code, including the generated code. This may not seem like a mammoth task until you are dealing with thousands of generated files. Keeping separate build directories ensures that your development environment remains stable and efficient.

9.2.4 See Also

The next recipe shows how to integrate XDoclet into your Ant buildfile, providing continuous integration.