Re: [jamboost] Refactoring progress report

From: Rene Rivera (grafik666_at_[hidden])
Date: 2003-05-09 19:15:03

[2003-05-09] Ali Azarbayejani wrote:

>David and I have been discussing a number of issues relating to
>refactoring the BBv2 codebase and we thought it would be a good time
>to summarize some of them so you can see what we're planning and have
>an opportunity for early feedback.

Some brief feedback...

>o Dynamic Type Checking

[snip]

> Another related problem is that arguments are generally named to
> reflect the *type* of the argument, often resulting in confusion as
> to the *role* of the argument.
>
> The proposal is to introduce dynamic type checking. David can give
> more details, but the resulting syntax will allow the confusing
>
> rule split ( property-set )
> rule as-path ( properties * : feature-space ? )
>
> to be written more explicitly as something like 
>
> rule <property-list> path-to-list ( <property-path> input-path )
> rule <property-path> list-to-path ( <property-list> input-list :
> feature-space ? )
>
> or
>
> rule [property-list] path-to-list ( [property-path] input-path )
> rule [property-path] list-to-path ( [property-list] input-list :
> feature-space ? )
>
[snip]
> This type of readability problem is widespread throughout the
> system. The new syntax is backward compatible (arguments and rules
> do not require types) and the syntax can be introduced for better
> readability before actually implementing the dynamic type checking.
> The dynamic type checking would work by registering a type-checking
> function for each type. This would be done automatically for
> classes. The actual type checking could be turned off to avoid any
> possible performance hit.

That argument sounds very much like the in/out arguments thread ;-) I'm not
sure going to this much trouble to solve the "bad argument names" is worth
it. But then again I haven't written as much OO/Jam code as others.

neutral on this one

>o Explicit Importing
>
> Currently "import foo" in a module doesn't guarantee that the module
> is dependent upon foo and the absence of "import foo" doesn't
> guarantee that the module is NOT dependent on foo. The latter is
> because "import foo" in another module makes foo rules available
> globally.
>
> This presents a problem for determining which modules depend on
> which other modules.
>
> The solution is to modify "modules.import" to make foo rules
> available only to the module that is importing them.
>
> This would allow a better visual understanding each module through
> the import statements; would allow automatic determination of module
> layering/dependency relationships, leading possibly to automatic
> documentation of layering and automatic maintenance or enforcement
> of layering and dependencies; and would reduce sloppy and
> inconsistent coding practices.

+1 from me on this. In fact that's how I use the import in the code I write,
seems only natural. Additionaly, to me it seems that a more restrictive
modules.import is what I would expect. Instead of making the rules visible
in the importing module, the rules should only be visible in the importing
scope. For example there are some places where we import inside a rule. It
would make more sense to limit the rules to that scope only.

>o Class Declaration
>
> Each class declaration requires a "rule" declaration followed by a
> "class" declaration, making it difficult to see at a glance whether
> a rule is a regular rule or a class definition. Short of a core jam
> modification to allow a more obvious declaration, it may be possible
> to reduce confusion by allowing the placing of the "class"
> declaration just before the "rule" declaration. David plans to
> explore this possibility. We're not sure there is an easy solution.

Or just going more simply and commenting the rule as:

# Class something-or-other....
#...
rule something-or-other...

But since we are considering language changes... If you wan't a more
immediate indication that it's a class why not use the dynamic type syntax
as above:

rule [class] something-or-other ( ...

After all this is the construction rule, so in a sense it does return a
class.

If David does manage to make it possible to move the declaration before the
rule, please warn me because the doc module depends on the current ordering.

[snip]

>o Option plug-ins
>
> Module "bootstrap.jam" is conceptually low-level, but depends upon
> "doc.jam", which results in a great deal of unwanted dependency on
> text-processing modules. This is a minor architectural problem.
>
> Actually, bootstrap.jam depends only on the parsing of command line
> options representing help requests. One way to decouple bootstrap
> from doc and provide a general mechanism for extending command line
> options is to provide a plug-in architecture for command-line
> options. The "help" module would use the option plug-in technique
> to express that it wants to handle certain command line options and
> then exit. Other modules might do the same, or handle command line
> options and continue. Thus, doc is decoupled from bootstrap and we
> have a new command-line-option extension feature.

Ok at this point I'm getting confused about your use of "depends" (and it's
variants). Yes bootstrap depends on doc, but not just to parse the command
line. More precisely it depends on it to interpret the command line. I'm not
sure how a plugin concept can help. If bootstrap "depends" on
command-line-options and "depends" on doc, how is that different than the
current situation?

I'm afraid you'll have to be more descriptive about this one.

>o Layers (tools, build, core)

[snip]

> We propose eventual re-structuring of the BBv2 directory to have
> three main subdirectories "tools", "build", and "core" containing
> the functionality described above, after refactoring. This would
> result in import statements like:
>
> import tools/gcc ;
> import build/type ;
> import core/os ;
>
> We realize the proposed names result in source-tree paths like
> "boost/tools/build/tools" and "boost/tools/build/build", which is
> kind of ugly. Any suggestions?

How does this interact with the BOOST_BUILD_PATH?

Of source if we normalized the directories to the rest of Boost that would
be:

boost/tools/build/src/tools
boost/tools/build/src/build
boost/tools/build/src/core

Doesn't seem all that ugly with the "src" divider in there :-\

Of course along with that I would also normalize the "jam_src" directory
right out of there into a:

boost/tools/bjam/src
...etc...

>o Refactoring feature.jam, property.jam

[snip]

Yea better names are good ;->

>o Refactoring classes
>
> We propose that each class have its own file.
>
> This will have implications for module dependencies, because current
> implementations are rather sloppy about what depends on what.
> Classes depend on functions in the module they exist in and other
> functions in the module depend on the class. These circular
> dependencies are probably not necessary. Re-factoring will
> highlight more clearly where circular dependencies exist. Trying to
> eliminate circular dependencies will probably lead to a clearer
> design and better concepts.

I just don't see how this will be all that beneficial, but again I haven't
looked at code as much as others. Just having good names for classes would
go a long way. But the general idea of less classes per file seems like it
would help in clarifying interfaces.

[snip]

>o "Abstract Targets" vs. "Virtual Targets"

[snip]

Yes, please! I started out confused about the various "targets" and still
am.

>o Generate Process

[snip]

>o Project-root/Jamfile
>
> The requirement of having a "project-root.jam" file in addition to a
> "Jamfile" for every project means that each simple single-Jamfile
> project requires an additional file.

Not true. The only requirement is that there be at least "one"
project-root.jam. For example boost should only have one project-root.jam...
At the logical BOOST_ROOT/project-root.jam.

> In fact, the Jamfile is the unnecessary one of the two, which leads
> us to propose that the file performing the function of the current
> "project-root.jam" be called "Jamfile", allowing simple projects to
> exist with a single Jamfile. The current function of "Jamfile" is
> really as a sub-Jamfile and should be called something else, but
> we're not sure quite how to rename.
>
> project-root.jam -> Jamfile, Jamroot ??
> Jamfile -> SubJamfile ??

No. There is no requirement that there be a Jamfile in the directory where
project-root.jam is located. If you don't have buildable targets at your
project-root than you should not have a Jamfile there.

And now that I look at the "Jamfile.v2" in the boost_root, it should be
renamed to project-root.jam. Of course we can only do this when BBv2 is
fully adopted, as it clashes with the current project-root.jam. Or perhaps
they can be merged with the use of a version check?

To say the least I'm -1 on this idea.

-- grafik - Don't Assume Anything
-- rrivera_at_[hidden] - grafik_at_[hidden]
-- 102708583_at_icq