Note: the content of this page is moved to 30.html. Updates to the content will be done there. This page will no longer be reviewed for updates and will be removed in due time.


This page is not yet a full explanation obviously. Please chip in.

Remember, with ant properties a property is not changed once it is set. The build first loads properties from cocoon.build.properties in the user's home directory, then from local.build.properties in the main project directory, then the original build.properties. If you set a value before Cocoon's default does, your value "wins".

From build.properties (should be copied to local.build.properties):

# ---- Webapp ------------------------------------------------------------------

#exclude.webapp.documentation=true
#exclude.webapp.javadocs=true
#exclude.webapp.idldocs=true
#exclude.webapp.scratchpad=true
#exclude.webapp.samples=true

The above properties affect what is included in the webapp (or war if you build that too).

# ---- Build Exclusions --------------------------------------------------------

#exclude.scratchpad=true
#exclude.deprecated=true
#exclude.javadocs=true
#exclude.idldocs=true

The above control what is actually assembled, whether they are included in the webapp or not.

# ---- Configuration -----------------------------------------------------------

#include.driver.oracle=true
#include.driver.postgre=true
#include.driver.odbc=true
#config.allow-reloads=true
#config.enable-uploads=true

The above are convenience settings to control some init-params in web.xml. All of these can be done or undone manually at any time. These build properties only exist for convenience. An easy way to see what they are doing is to look in the src/confpatch directory and look at the various .xweb files. These are used by the CustomConfigTarget target which you can also use for your own configuration changes either as a part of the Cocoon build, or by defining the xpatch task in your own build file.

# ---- Validation --------------------------------------------------------------

validate.config=true
validate.xdocs=true
validate.jars=true

The validation targets ensure that various config files, documentation xml sources and the core, optional, and endorsed jars are in an expected state. There's really no reason to mess with these. The first two are fairly self-explanatory xml validiations, but the last bears a quick comment. Every jar used in the build is recorded with at least some explanation of its purpose in jars.xml. Only the lib/local directory is excluded from this requirement. The validate.jars target enforces this requirement.

# ---- Forrest -----------------------------------------------------------------

forrest.home=../xml-forrest/build/dist/shbat/

If present, Cocoon uses Forrest (an Apache project based on Cocoon focused on building documentation) to build its own documentation. Forrest does not ship with Cocoon because of the circular dependency it would create. If not present, Cocoon still builds its own documentation.

NOTE: I am surmising this to be the case because I don't have Forrest present on my machine and the docs still build with the old look (GeoffHoward). I have not traced this through the build targets though.

# ---- Build -------------------------------------------------------------------

build.root=build
build=${build.root}/${name}-${version}
build.dest=${build}/classes
build.mocks=${build}/mocks
build.test=${build}/test
build.docs=${build}/docs
build.docs.printer=${build}/printer-docs
build.site=${build}/site
build.xdocs=${build}/xdocs
build.idldocs=${build}/idldocs
build.javadocs=${build}/javadocs
build.context=${build}/documentation
build.context.printer=${build}/printer-documentation
build.blocks=${build}/blocks
build.deprecated=${build}/deprecated
build.scratchpad=${build}/scratchpad
build.scratchpad.src=${build.scratchpad}/src
build.scratchpad.dest=${build.scratchpad}/dest
build.samples=${build}/samples
build.temp=${build}/temp

build.docs.loglevel=ERROR
build.docs.printer.loglevel=ERROR

These define directories used in the build and should not normally need to be changed by an end user. The two loglevel values define the logging verbosity during the building of the regular docs and the printer friendly docs (if included).

# ------ Webapp Build Properties -----------------------------------------------

build.webapp=${build.root}/webapp
build.webapp.webinf=${build.webapp}/WEB-INF
build.webapp.classes=${build.webapp.webinf}/classes
build.webapp.lib=${build.webapp.webinf}/lib
build.webapp.samples=${build.webapp}/samples
build.webapp.docs=${build.webapp}/docs
build.webapp.javadocs=${build.webapp}/api/java
build.webapp.idldocs=${build.webapp}/api/fom
build.webapp.loglevel=INFO
build.war=${build}/${name}.war

Like the section above, these define directories used during the build. There are two which may be useful for end users:

# ------ Standalone-demo Build Properties --------------------------------------
build.standalone.demo=${build.root}/standalone-demo

The standalone demo target creates a directory with all the pieces (including the light version of Jetty) needed to zip up as a demo of Cocoon outside the normal directory. This could also be a starting point for a project based on Cocoon.

NOTE: Could someone who knows more about the Standalone target fill in here and check my facts? (GeoffHoward).

# ---- Compilation -------------------------------------------------------------

compiler=modern
compiler.debug=on
compiler.optimize=on
compiler.deprecation=off
compiler.nowarn=on

The above are compiler settings that would not normally need to be touched.

# ------ System Properties -----------------------------------------------------

# WARNING: you shouldn't need to modify anything below here since there is a
# very high change of breaking the build system. Do it only if you know what
# you're doing.

The properties following this warning have been ommited. If you have to ask, you shouldn't be messing with them!

Q&A

Q: Can I add an #include.driver.mysql=true to the Configuration section; if so, perhaps this should be a commented line already included in the shipped version, as I would guesstimate that this database has widespread use.

A: Yes you can, but for it to work you'll need to copy one of the existing .xweb driver patch files and modify it with the correct driver, the correct unless/if properties. I have meant to do this, but a patch from you will get the job done a lot faster!


CategoryInDaisy

BuildProperties (last edited 2009-09-20 23:42:26 by localhost)