cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@cocoon.zones.apache.org
Subject [DAISY] Created: Configuring Cocoon with build.properties
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 build.properties
Document Type: Simple Document
Created: 6/10/05 1:52:38 PM
Creator (owner): Mark Leicester
State: draft

Parts
=====

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

<h1>Build Property Precedence</h1>

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

<ol>
<li>cocoon.build.properties in your user account's home directory.</li>
<li>local.build.properties in the Cocoon root directory.</li>
<li>build.properties in the Cocoon root directory.</li>
</ol>

<p>For example, if your cocoon.build.properties contains the line
"exclude.webapp.javadocs=true" then this will take precedence over any settings
to the contrary in later files (i.e. in local.build.properties or
build.properties). 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 build.properties
file from the Cocoon root directory to a new file called local.build.properties
also in your Cocoon root directory, or to cocoon.build.properties in your user
account's home directory.</p>

<p>From build.properties (should be copied to local.build.properties):</p>

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

#exclude.webapp.documentation=true
#exclude.webapp.javadocs=true
#exclude.webapp.idldocs=true
#exclude.webapp.scratchpad=true
#exclude.webapp.samples=true
</pre>

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

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

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

#exclude.scratchpad=true
#exclude.deprecated=true
#exclude.javadocs=true
#exclude.idldocs=true
</pre>

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

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

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

#include.driver.oracle=true
#include.driver.postgre=true
#include.driver.odbc=true
#config.allow-reloads=true
#config.enable-uploads=true
</pre>

<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="http://wiki.apache.org/cocoon/CustomConfigTarget">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>

<ul>
<li>
<p><strong>include.driver.*</strong> causes the driver name to be declared
in
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>
</li>
<li>
<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>
</li>
<li>
<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>
</li>
</ul>

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

validate.config=true
validate.xdocs=true
validate.jars=true
</pre>

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

forrest.home=../xml-forrest/build/dist/shbat/
</pre>

<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="http://wiki.apache.org/cocoon/GeoffHoward">GeoffHoward</a>). I have
not traced this through the build targets though.</p>

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

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

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

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

<ul>
<li>
<p><strong>build.webapp</strong> could be changed to an external project
folder
to "seed" a project based on Cocoon.</p>
</li>
<li>
<p><strong>build.webapp.loglevel</strong> specifies the default loglevel
used
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>
</li>
</ul>

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

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

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

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

compiler=modern
compiler.debug=on
compiler.optimize=on
compiler.deprecation=off
compiler.nowarn=on
</pre>

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

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

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

<h2>Q&amp;A</h2>

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

</body>
</html>

Collections
===========
The document belongs to the following collections: ciatutorial

Mime
View raw message