cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@cocoon.apache.org
Subject [Cocoon Wiki] Updated: CocoonBlockBuilder
Date Sun, 21 Nov 2004 12:45:19 GMT
   Date: 2004-11-21T04:45:18
   Editor: ReinhardPoetz <reinhard@apache.org>
   Wiki: Cocoon Wiki
   Page: CocoonBlockBuilder
   URL: http://wiki.apache.org/cocoon/CocoonBlockBuilder

   no comment

Change Log:

------------------------------------------------------------------------------
@@ -1,208 +1 @@
-
-
-WARNING: This document is currently out of date, please see BlockManagement for now. I (RP)
will update this page ASAP.
-
-
-=== 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
when you call the ant script, the property and blockbuilder.root is available. The easiest
way is adding a file with the name "local.block.build.properties" to the root directory of
the block.
-
-The content of local.block.build.properties could look like this:
-
-{{{
-# ---- BlockBuilder -------------------------------------------------------------
-
-blockbuilder.root=../../../../dev
-
-}}}
-
-Then you can call one of the Ant tasks and compile the project (e.g. ant compile).
-
-=== 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
- * eclipse task not tested on non-win32 environments
-
+WARNING: This document is currently out of date, please see BlockManagement.

Mime
View raw message