harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Ellison <t.p.elli...@gmail.com>
Subject Re: [classlib] Preprocessor - an attempt at clarity
Date Fri, 03 Nov 2006 10:39:04 GMT
Geir Magnusson Jr. wrote:
> Tim Ellison wrote:
>> There are multiple 'devtarget's -- each contains all the source code
>> marked-up for every target being developed, but each is distinct by
>> having different targets uncommented.  Since each devtarget contains the
>> entire source code it is possible to accurately transform from any one
>> devtarget to any other devtarget.  One of the devtargets is actually
>> stored in svn, and that is the canonical form of the devtarget code.
> 
> So that's 'master'. and everythign else is a transformed master, right?

Yes, but some transforms preserve all mark-up and are used to switch the
compilable form between different targets (these are the 'devtarget's);
and some transforms are mark-up-lossy and are used to provide the end
user compilable form (this is the 'releasetarget').

>> Screech -- the releasetarget, by definition, does not contain the source
>> for all possible targets so that it is consumable by end-users.
> 
> That is correct.
> 
> The only code that contains all code is master.

Not in the technique that I'm talking about.  All devtargets contain all
the code (but they differ in which code is compilable and which is in
comments).

Let me try using very simple example for my favourite type, assuming we
were doing CLDC and SE1.5 development simultaneously.  The type
declaration for String is different for CLDC and SE1.5, and SE1.5 has
additional methods, etc.


If you are an SE developer you would compile and work in the devtarget
source for SE 1.5.  Notice that we have a @process mark-up tag in both
type declaration comments, and since this is devtarget SE1.5 the CLDC
type declaration is commented out.

  package java.lang;

  /* A String is an immutable sequence of chars.
   *
   * @Process(CLDC)
   * public final class String
   */

  /* A String is an immutable, serializable, comparable
   * sequence of chars.
   *
   * @Process(SE1.5)
   */
   public final class String implements Serializable,
                                   Comparable<String>, CharSequence
   {
     /*
      * This constructor is common to both so needs no mark-up
      */
      public String () {
        value = new char[0];
        offset = 0;
        count = 0;
      }

      /*
       * This method is SE1.5 only so needs to be marked.
       * @Process(SE1.5)
       */
       public String[] split(String expr) {
         return Pattern.compile(expr).split(this);
       }
    }


Now if you want to develop CLDC you don't want to do that by editing
comments, you want the CLDC code to be uncommented so you can compile
it, but you want to preserve the SE1.5 code so you can get back to the
SE1.5 version accurately.

I probably don't need to show you, but for completeness here's the
result of transforming to the CLDC devstream.  Note that the type
declaration comments flip-round, and the SE1.5-only method becomes
commented out.

  package java.lang;

  /* A String is an immutable sequence of chars.
   *
   * @Process(CLDC)
   */
   public final class String

  /* A String is an immutable, serializable, comparable
   * sequence of chars.
   *
   * @Process(SE1.5)
   * public final class String implements Serializable,
   *                                Comparable<String>, CharSequence
   */

   {
     /*
      * This constructor is common to both so needs no mark-up
      */
      public String () {
        value = new char[0];
        offset = 0;
        count = 0;
      }

      /*
       * This method is SE1.5 only so needs to be marked.
       * @Process(SE1.5)
       *
       * public String[] split(String expr) {
       *   return Pattern.compile(expr).split(this);
       * }
       */
    }


The big block comment for the split() method can be collapsed by the IDE
to a single line so you don't loose it but it is unobtrusive.

Now Mr CLDC developer can work in this stream and then transform back to
the canonical SE1.5 format and check-in his changes in.  Storing in a
canonical format means we maintain a sane single HEAD stream in SVN.

Of course, Mrs CLDC user doesn't want to see all the SE1.5 comment
nonsense, so we can destructively transform any devsource into a
releasetarget CLDC for her.  Again for completeness, here is the
releasetarget form of CLDC:


  package java.lang;

  /* A String is an immutable sequence of chars.
   */
   public final class String
   {
     /*
      * This constructor is common to both so needs no mark-up
      */
      public String () {
        value = new char[0];
        offset = 0;
        count = 0;
      }
    }


We then talked about how the different devtargets can be stored in
different working directories for use by Harmony developers with
file-based tools, or (thinking about it for a second now) it could be an
on the fly processing to/from canonical form on disk by the IDE editor.

We also talked about how patches to the source that Mrs CLDC developer
sees can be matched back to a devtarget.

Regards,
Tim

-- 

Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.

Mime
View raw message