forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <>
Subject Re: [wip] refactoring the build.
Date Wed, 21 Aug 2002 13:34:11 GMT
Great :) I'm 100% with you on how you propose to separate things.

A little update on the Maven plugin: I have a basic version working, that just
delegates to acorn.xml. Maven plugins are really easy.  They're basically a
Jelly script, plugin.jelly, which gets automatically 'sourced', and gets a
pointer to ${plugin.dir} where one can store static resources (dtds, xsls, jars
etc). So my plugin.jelly just delegates to Ant:

<project xmlns:j="jelly:core" xmlns:define="jelly:define">
  <goal name="forrest:transform">
    <property name="forrest.home" location="${plugin.dir}/xml-forrest"/>
    <ant antfile="${plugin.dir}/acorn.xml">
      <property name="forrest.home" value="${forrest.home}"/>

That pattern, of delegating to an Ant script, is what I'd like to preserve,
because then we can reuse the Ant script across Centipede, Maven, command-line
and from user's Ant scripts. All the Maven plugin does is map from Maven's
directory layout (${maven.*} properties) to Forrest's dir layout.

In summary; that's what I'm looking for in a refactored build system; an Ant
script(s) which I can create a *minimal* wrapper for, to create a Forrest or
Centipede plugin.

On Wed, Aug 21, 2002 at 01:42:28PM +0200, Marc Portier wrote:
> Hi all,
> I've started on the topic Jeff put on the agenda: separating the
> concerns in our build system.
> I understand touching the build system is of the rather
> disturbing kind.
> On the other hand, the relative silence on the list could be a
> sign that this is good timing?
> This is how I see things end up separated
> 1. work towards a new build.xml for forrest that actually makes
> forrest-distributions
>   - remove all forrest-site producing targets
>   - insert actual forrest-distributions
>     - the one I like to build now is some kind of shell/bat
> version of forrest. (see below)

(cool, but as you say, shell/bat scripts belong in section 2)

>     - what I am dreaming (no clue how to do it) of is other
> targets to build (1) cent / (2) jar (standalone and with ant task
> included) / (3) maven-plugin /...? (I hope maveners and
> centipeders will step in further down the line)

So here, a 'distribution' is comprised of:
 1) a directory containing a subset of all Forrest's available static files.
 2) the 'runtime' scripts (shell, bat, ant), that you describe below.

The script that generates a distribution (build.xml I suggest) will be pretty
simple; just compile the jars and do lots of copying.

> 2. work towards a separate that handles the
> run-time part of what forrest can do for any project
>   - place here the forrest-site producing things in such a way it
> can work on other projects
>     so we go here for bot-like tasks that use
> parameters (also the webapp target makes sense)

(and that I can call from a jelly script)

>   - part of acorn should go in here as well: the targets to build
> your fresh-project-template
>     (I like the way it builds file from inside the ant file,
> although I think to some copying a set of premade-termplate files
> would make it easier to manage the template content? e.g. also
> for when users would like to customise this template?)

If you look in acorn.xml, you'll see there's two sections, divided by:

<!-- .............. -->
<!-- .............. -->
<!-- .............. -->
<!-- .............. -->

The first section is what you want here; targets for rendering existing docs in
arbitrary directories. I took these directly from Forrest's build.xml, with
minimal modification.  It's ugly and needs rewriting. This is what I'd be
working on next, and (it sounds like) what you're working on now? Can I help,
or would you like me to do it?

>   - the bot-working targets should slide in here as well (anyone
> having feelings about yet another one?)

I'd vote for the bot stuff to be put in a separate forrestbot.xml script. It's
still runtime, but it's asynchronous runtime (eg cron-driven site updates) that
won't involve most users. 

> (I'ld like these targets to work eventually on the siteplan
> idea?)
> (down the line this will call for redoing the bot as well)
> 3. work towards a separate that captures the
> acorn-dropping idea
>   - look at forrest.home to install or update the thing there.
>   - get it from cvs and build it again to overwrite the other
> version
> This last one is handy, but less of a priority maybe? Cent users
> would get this kind of feature from the cent behaviour, don't
> know about maven on this.

This is the second section of acorn.xml. I vote for turfing out the first
section, define acorn.xml as "the script for seeding a new Forrest project",
and let a separate script to the actual Forrest running.

> As for the (only) distribution I think on building now:
> That would very much behave like ant.bat:  So people using
> forrest for their project should install this distribution in
> some directory, put its path in env: FORREST_HOME, add the bin
> section of it to their path and call the there residing
> forrest.bat or
> Pretty much like they use ant to build their classes, they should
> use forrest to build their site then.
> People that like to hook up this work in their chain of ant
> dependencies can just call the shell by means of <exec>
> This distribution will itself call upon ant to do the actual
> building: the 2nd one of the build files should be in here!
> Given this fact, it would probably be a lot cleaner for people
> that want to use forrest from their ant script to use <ant
> antfile=${ENV.FORREST_HOME}/ ...> in stead.
> (Still, making it possible for them to just type
> ($FORREST_HOME/bin/) on the command-line kinda sounds
> nice.  It would let them - produce the fresh project template
> (like acorn) - produce the docs and the webapp - to run as a
> bot... furthermore: site-building based on forrest should be open
> to non-programming-projects (no build.xml) as well, no?)

Let me backtrack and try to summarise what we have so far:

1) A 'distribution', containing all the static files and compiled jars. This
   should be generated by the build.xml Ant script.
2) Runtime parts of Forrest. Something that, given a pointer to 1) and a bunch
   of xdocs, generates a website. The runtime part should IMHO be an Ant
   script, say, called 'forrest.xml'.
3) Acorn stuff for 'seeding' new projects.

So build.xml, when building a distribution, should include forrest.xml and
acorn.xml. Then client projects can do <ant

If we want shell/bat scripts, does that imply bundling Ant into the
distribution? I'd really rather not include Ant, since most Forrest users will
be invoking Forrest from their own Ant scripts (ant preinstalled), or
indirectly via Maven or Centipede.

However, if you mean shell/bat scripts that just runs Cocoon directly, then
that's great.

> Anyone care to join in the fun?
> Can I commit the very general (non-working) framework (==set of
> new buildfiles) I already have?

Please do, I'd like to see how it's going. It sounds like we're definitely on
the same wavelength.


> -marc=

View raw message