cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [DAISY] Created: Configuring Cocoon with
Date Fri, 10 Jun 2005 13:53:09 GMT
A new document has been created.

Document ID: 30
Branch: main
Language: default
Name: Configuring Cocoon with
Document Type: Simple Document
Created: 6/10/05 1:52:38 PM
Creator (owner): Mark Leicester
State: draft


Mime type: text/xml
Size: 10329 bytes
<html imagetoolbarenabled="true">

<h1>Build Property Precedence</h1>

<p>Ant looks for build properties defined in .properties files in the following
locations, in the following order:</p>

<li> in your user account's home directory.</li>
<li> in the Cocoon root directory.</li>
<li> in the Cocoon root directory.</li>

<p>For example, if your contains the line
"exclude.webapp.javadocs=true" then this will take precedence over any settings
to the contrary in later files (i.e. in or The first file to set a property "wins".</p>

<h1>Modifying build properties</h1>

<p>To override properties you will need to copy the existing
file from the Cocoon root directory to a new file called
also in your Cocoon root directory, or to in your user
account's home directory.</p>

<p>From (should be copied to</p>

<pre># ---- Webapp ------------------------------------------------------------------


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

<p><strong>documentation</strong> the cocoon docs as seen on the website.
link for the documention will also be excluded from the main welcome page.</p>
<p><strong>javadocs</strong> the javadocs of all cocoon core and blocks
The link for the javadocs will also be excluded from the main welcome page.</p>
<p><strong>idldocs</strong> some modeling documentation on the flow object
(FOM) described in idl. The link for the FOM docs will also be excluded from the
main welcome page.</p>
<p><strong>scratchpad</strong> new components or core functions under
experimental development. The components will not be configured in,
cocoon.xconf, etc.</p>
<p><strong>samples</strong> the functioning samples. This excludes core,
and scratchpad samples. (blocks and scratchpad may not have been included anyway
depending on your choices in other config options).</p>

<pre># ---- Build Exclusions --------------------------------------------------------


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

<p><strong>scratchpad</strong> scratchpad will not be compiled at all.</p>
<p><strong>deprecated</strong> classes moved to the deprecated source directory
will not be compiled at all.</p>
<p><strong>javadocs</strong> the javadocs will not be created at all</p>
<p><strong>idldocs</strong> the idl FOM docs will not be created at all</p>

<pre># ---- Configuration -----------------------------------------------------------

<p>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
<a href="">CustomConfigTarget</a>
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.

<p><strong>include.driver.*</strong> causes the driver name to be declared
the load-class param. They <strong>DO NOT</strong> cause the actual jar
containing the driver to be placed in WEB-INF/lib nor do they configure your
datasource in cocoon.xconf. They were added because declaring the class in
web.xml was a frequently forgotten task.</p>
<p><strong>allow-reloads</strong> enables a magic "cocoon-reload" request
parameter to cause the entire Cocoon controller object to be disposed and
recreated. This is convenient when declaring new components in cocoon.xconf
during development, but should be disabled for any live site. It is not needed
to allow subsitemaps or xsps to reload when their source is modified.</p>
<p><strong>enable-uploads</strong> causes file uploads received via multipart
html forms (with input type="file" elements) to be automatically parsed by
Cocoon and available as objects in the request. There are at least two samples
that will not work unless this property is set to true, but it is disabled by
default. There are also more settings related to this in web.xml, and you can
set <strong>any</strong> of these even after build time.</p>

<pre># ---- Validation --------------------------------------------------------------


<p>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.</p>

<pre># ---- Forrest -----------------------------------------------------------------


<p>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.</p>

<p>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
(<a href="">GeoffHoward</a>). I have
not traced this through the build targets though.</p>

<pre># ---- Build -------------------------------------------------------------------


<p>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

<pre># ------ Webapp Build Properties -----------------------------------------------


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

<p><strong>build.webapp</strong> could be changed to an external project
to "seed" a project based on Cocoon.</p>
<p><strong>build.webapp.loglevel</strong> specifies the default loglevel
for logging while Cocoon runs. Like the configuration settings, this can be
changed later, but it is convenient to do it here at build time.</p>

<pre># ------ Standalone-demo Build Properties --------------------------------------

<p>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

<p>NOTE: Could someone who knows more about the Standalone target fill in here
and check my facts?
(<a href="">GeoffHoward</a>).</p>

<pre># ---- Compilation -------------------------------------------------------------


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

<pre># ------ 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.

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


<p><strong>Q:</strong> 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.</p>

<p><strong>A:</strong> Yes you can, but for it to work you'll need to copy
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!</p>


The document belongs to the following collections: ciatutorial

View raw message