Re: genesis design

Reinout van Rees wrote:
> 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?

So what about reading the destination files?  Is genesis aiming for
roundtrip?  I think that it should at least parse the code that is
already in place to see what needs to be replaced and what needs to stay.

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

I think you guys intended to use the CA for configuration?  Which I
think makes a lot of sense.  Plug in your own profile or stereotype
handler or whatever and off you go.

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

So profiles are a way to add special behaviour based on tagged values
and stereotypes?

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

Why do profiles live in both profiles and generator?  From what I
understand, profiles are only configuration and documentation, whereas
the implementation is in the generator?

> 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 last sentence baffles me.

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

Oh wait, first the generator pulls and then the model pushes?  I'm not
sure I understand why configuration files should be responsible for
telling the generator that IPloneClass needs an Archetypes class.  Isn't
that too much logic for a configuration file?  Aren't targets supposed
to do that?

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

Query package for contained items and create import lines?  Could you
eloborate on what those imports are for?  Are they inside the __init__.py?

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

I think I get it.  Every class contained in a package gets imported in
the __init__.py until it explicitely says it doesn't want to?

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

Makes much sense!

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

OK, I think i know what internal model does.

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

... but not sure about profiles yet.  I'll take a look and come back
with questions.

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

Ouch. :-)


Thanks for the clarification, Reinout!


Daniel



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