cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@cocoon.apache.org
Subject [Cocoon Wiki] New: CocoonBlockBuilder
Date Thu, 28 Oct 2004 11:33:56 GMT
   Date: 2004-10-28T04:33:56
   Editor: ReinhardPoetz <reinhard@apache.org>
   Wiki: Cocoon Wiki
   Page: CocoonBlockBuilder
   URL: http://wiki.apache.org/cocoon/CocoonBlockBuilder

   Proposal for CocoonBlockBuilder

New Page:

=== Goal ===
Cocoon is a large beast as it integrates so many technologies. We did the first step by moving
some parts of Cocoon into blocks. Still, it is not possible to develop a single block without
having to care of all the other blocks.

I have been working on a proposal (http://svn.apache.org/repos/asf/cocoon/whiteboard/block-builder)
that prototypes my ideas where we should move to with our build system.

My goals for the CocoonBlockBuilder are:

 * decouple core and block development
 * it should be possible to develop a single block
 * Have a small footprint in Eclipse (load only necessary libraries and sources)
 * drive the build from a block descriptor file
 * create Gump scripts based on block descriptor
 * gump makes sure that everything integrates well
 * Go towards ["Blocks"]
   * create a block descriptor that contains all necessary block infos (dependencies on other
blocks, libraries)
   * separate public and private classes
 * two modes of deployment (both modes take care of sitemap, cocoon.xconf, logkit.xconf and
roles update)
   * development deployment: web application uses compiled classes (via ParanoidCocoonServlet)
and examples (without copying them around) --> "live editing"
   * production deployment: create a "valid" web application without external links
 * Enable current behaviour of a 
   * global build
   * a single Eclipse project for all
   * a webapp with all blocks

Please consider this as a proposal. I don't know build tools like Maven in depth so that I
couldn't have prototyped my ideas like I've done it with Ant. For the first, let's talk about
functionality and then about tools.

=== How to use it? ===
Checkout http(s)://svn.apache.org/repos/asf/cocoon/whiteboard/block-builder. Make sure, that
block.build.properties and blockbuilder.properties are correct (which should work if you have
the complete Cocoon SVN tree). Call "ant compile" at /test/blocks/myblock/trunk.

=== Directory structure ===
In order to explain what I have done, let's take a look at the file system:


{{{
cocoon
 |
 +--blocks
 |    |
 |    +--authentication-fw
 |        |
 |        +--trunk
 |        |   +--descriptor.xml
 |        |   +--build.xml
 |        |   +--legal [DIR]
 |        |   +--src
 |        |   |   +--java
 |        |   |       +--public
 |        |   |       +--private
 |        |   +--samples
 |        |    
 |        +--branches
 |
 +--trunk
 |    +--build.xml
 |    +--src
 |    |   +--java
 |    |       +--core
 |    |       +--public
 |    |       +--private
 |    +--samples
 |    +--lib
 |        +--core
 |        +--endorsed
 |        +--blocks
 +--branches
 +--tags     
}}}   

 * Blocks should move into its own place in SVN - as long as possible we only maintain trunk,
if necessary (e.g. for XSP) branches too
 * each block has a descriptor (see below)
 * the java sources a separated into a public and a private section. We should move as much
as possible into private
 * if a block depends on another block it can only use public classes/interfaces
 * in /trunk/lib there is a repository of all available libraries, rule is that a block ""has
to"" use these libs (see block descriptor) if available, otherwise we end in jar versioning
hell
 
=== Projekt descriptor ===
{{{
<?xml version="1.0" encoding="UTF-8"?>
<block id="http://apache.org/cocoon/autentication-fw/1.0">
   
  <name>Autentication Framework</name>
  <author href="http://cocoon.apache.org">Cocoon Community</author>
  <license href="http://www.apache.org/LICENSE-2.0/">Apache Software License 2.0</license>
   
  <requirements>
    <requires
      block="http://apache.org/cocoon/session-fw/1.0"
      name="session"
      />
  </requirements>
  
  <libraries>
    <lib id="avalon-framework-api" location="core"/>
    <lib id="avalon-framework-impl" location="core"/>
    <lib id="excalibur-xmlutil" location="core"/>        
    <lib id="excalibur-pool" location="core"/>
    <lib id="excalibur-sourceresolve" location="core"/>
  </libraries>
  
 </block>
}}}

The project descriptor gives global information of the block (name, author, ...), the required
blocks and and required libraries. Note that libraries are only references via their names
and not their versions.

To make this useable, a small addition to our jars.xml is necessary:

{{{
<jars>
  <file id="util.concurrent">
    <title>Doug Lea's Concurrent Utilities</title>
    <description>
      The concurrency management primitives that will be the 
      foundation of JDK 1.5 concurrency management.
    </description>
    <used-by>Cocoon</used-by>
    <lib>core/util.concurrent-1.3.4.jar</lib>
    <homepage>http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html</homepage>
  </file>
  ...
</jars>
}}}
Note the id attribute in the file element.


=== Build system and Ant tasks ===
The build system is based on the descriptor. It uses its information to resolve  all dependencies.
Technically, the Ant script is generated via XSTL. This way, it can be reused in all blocks
via Ant import statements. If necessary, for a block a certain build target can be overriden
locally

{{{
<project default="compile" name="Build autentication-fw block">

    <property file="local.block.build.properties"/>
	<available file="${blockbuilder.root}" property="available.blockbuilder.root"/>
    <fail unless="available.blockbuilder.root" 
    	message="Property blockbuilder.root has to be set!"/>
	
	<xslt in="descriptor.xml" 
		  out="build/temp/build-by-xslt.xml"
	      style="${blockbuilder.root}/targets/block-descriptor2ant-script.xsl">
	</xslt>
	
	<import file="build/temp/build-by-xslt.xml"/>
	
</project>

}}}

To make it run, the property blockbuilder.root has to be set.

Each block has its block.build.properties (e.g. for the authentication-fw block):

{{{
# ---- Paths -------------------------------------------------------------------

src.public=src/public
lib.dir=../../../trunk/lib

# ---- References --------------------------------------------------------------
root.core=../../../trunk
root.block.session=../../session-fw/trunk

}}}

As you can see, the directories for the sources, the library repository, cocoon core and the
session block are specified. Using Ant mechanisms this properties can be overriden locally.

Currently following build targets for external use are available

==== compile ====
The block and all blocks it depends on and Cocoon core are compiled.

==== package ====
The block and all blocks it depends on and Cocoon core are packaged into single packages.

==== clean ====
The block and all blocks it depends on and Cocoon core build directories are deleted.

==== eclipse-project ====
An Eclipse project file is generated that only points to the necessary libraries. This target
is based on an custom Ant task that creates a .classpath file for Eclipse resolving path information
correctly (WARNING: currently only relative paths for core.root and block.xxx.root are working).


=== What's done so far? ===
 * compiling and packaging that resolves dependencies (snowball effect)
 * create the eclipse project for a single block that only loads the necessary libraries

=== Open issues ===
 * global tasks (compile, webapp, javadoc, ...)
 * create gump script
 * block deployment
 * What about referencing the classes directories instead of block libraries (ensures that
development is done using the latest classes) AFAIK this is difficult (or at least buggy in
Eclipse)
 * How much flexibility do we need? (strict directory structure, package names, ...)
 * user libraries repository
 * splitting Cocoon core and the block sources in private and public parts


Mime
View raw message