genesis design

Hello all,

Here's my version of the architecture of genesis. If you don't like 
structuredtext, you can see the html version at 
http://vanrees.org/weblog/archive/2006/02/06/genesis-architecture :-)


**Genesis** is the next version of 
"archgenxml":http://plone.org/products/archgenxml/ . I used to call it 
agx 2.0, but I've since been cured of my evils :-)

Daniel Nouri stirred up the conversation on the archetypes development 
mailinglist this afternoon, prompting me to finally write down the 
architecture a bit. Good thing he did it.


Design

  Genesis has two basic steps: reading and writing. Reading the input
UML file and putting it into an internal model. And secondly writing
out the actual product from that internal model to the
filesystem. Simple, huh?

There are some configuration possibilities to steer this process. Of
course some commandline or config file parameters for setting some
global options. More directly important are the profiles and the
generator.

Profiles -- A profile is used to define what you're saying in your UML
model. Basic classes and attributes are OK, but you want to be able to
say "hey, this is no ordinary class, this is really a CMFMember class"
- with all the associated differences in handling.

   You can define your UML stereotypes and tagged values in a
   profile. Such a profile of course forces you to document those
   items, so that we won't ever have the bad undocumented days back! It
   is possible to mix profiles, so you can have a plone 2.1 profile
   plus a Membrane profile.

   The stereotypes defined in your profile(s) change the classes in the
   internal model. Instead of only providing an 'IGenericClass'
   interface, they now also provide, say, a 'ICMFMemberClass'
   interface. This will be used by the subsequent generator step.

   Did I mention that you can make your own profiles? You've got to
   add support for it in the generator, too. This gives you previously
   unknown customisation possibilities :-)

Generator -- This isn't too well-defined yet. There are two ways to
tackle this: making an in-memory representation of what's to be
written out or doing it in an almost xslt-like push/pull way. I'm way
in favour of ding it the push/pull way, so I'll blatantly describe
that here.

   For a certain profile, say plone 2.1, there are a number of fixed
   files and directories that need to be generated. The generator tries
   to create them and actively **pulls** information from the internal
   model. An adapter for the main model element might be best
   here. This gives you the 'Extensions/install.py' for instance.

   The second step is for the internal model to push all items to the
   generator and have the generator slug it out. There has to be a
   configuration file that tells the generator that for every incoming
   'IPloneClass', there should be an archetypes class, possibly a
   template in the skins directory and so on.

   All those little things like an '__init__.py' file in every
   directory are handled by creating it on every incoming
   'IPackage'. The adapter itself can of course query the package for
   contained items and calling an appropriate adapter that gives back
   an import line.

   The great thing here is that *if* you've got a certain class of item
   in the package for which you don't want an import line *then* you
   just need to provide an adapter for that interface that keeps quiet
   when asked for an import line.

So: genesis reads a file into an internal model, using one or more
profiles. Those profiles customise the base genesis to your needs. It
then uses a generator (which you again configure) to create your
product.

Profiles, the generator configuration and adapters look set to making
this pretty adaptable, maintainable and elegant.


Current state of the code

  The current code is nowhere near finished. About half of it is in the 
state that we left it when running for the train after September's 
castle sprint. I've done some work on a few parts. The parts that start 
to look a bit decent:

Internal model -- It can store most basic UML-like items. Stereotypes 
get turned into implemented interfaces, ready for the generator to use.

Profiles -- Used to define profiles of stereotypes and tagged values. 
Also includes documentation for those items.

Option/configparser -- Mostly copy-pasted from the existing code.

I've only recently started trying to wire it all together a bit, so stay 
tuned for more improvements. Jean-Paul Ladage plans on sitting with me 
for half a day a week to push it forward to get some basic functionality 
going before the "golden roof 
sprint":http://plone.org/events/sprints/goldenroof/ .


Reinout

-- 
Reinout van Rees                       r.van.rees @ zestsoftware.nl
http://vanrees.org/weblog/                  http://zestsoftware.nl/
"Military engineers build missiles. Civil engineers build targets."



-------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc. Do you grep through log files
for problems?  Stop!  Download the new AJAX search engine that makes
searching your log files as easy as surfing the  web.  DOWNLOAD SPLUNK!
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=103432&bid=230486&dat=121642