ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "James Duncan Davidson" <james.david...@eng.sun.com>
Subject Ant Principles
Date Tue, 18 Apr 2000 01:11:24 GMT
Ok, so if we are going to tighten up Ant to get to the point where it should
go, we should start off with a set of principles (or goals, or design
criteria, or whatever you want to call them) that we all agree on. It's
simple, it's basic, but maybe by starting off really basic, we can infuse
the rest of the process with a unified purpose.

Just for the curious, I'm not touching on specific tasks yet.. Most notably
I'm not going into conditional compilation, etc... That stuff comes after we
define how the framework within which conditional compilation can happen.

Design Goals (there should be no suprises here!)

  Simplicity:

  Ant must be simple to use and simple to extend. Of course, the
  definition of simple can vary depending on which audience is chosen.
  For Ant, since it is a build tool aimed at Java developers, the goal
  is simplicity of use and extension for a competent Java programmer.

  Understandability:

  The way Ant works should be clearly understandable for a first
  time as well as a veteran user. The mechanism to extend Utah must be
  understandable. And the build file syntax must be eminently
  understandable.

  Extensibility:

  Ant must provide an easy to use extensibility path. Extensions
  must be easy to write for the programmer and easy to place where they
  can best be used.

Conceptual Overview (here's a bit more detail, but still should be
relatively agreeable)

  The base unit of work is a Project. A Project is defined by an
  XML text file and as an object of type Project at runtime.
  A Project is a collection of Property definitions and Targets.

  Properties:

  Properties are mutable name-value pairs that are scoped to the
  Project and held in a List. The property list can be modified at
  runtime allowing properties to be added, removed, or changed. The
  property list is loaded from the XML based project file. It is useful
  to be able to override the properties contained in a project file and
  so optional parameters to the ant runtime can be defined to do so:

  ant projectfile.xml -props foo=bar;baz=bop [target]

  The current version of Ant allows the System property list to be
  consulted for a return value of the Project if the property requested
  doesn't exist in the Project property list. This can be considered to
  be confusion, and should not be carried forward.

  Yes, I'd like to see the props defined this way.. This does reserve
  the ; and = chars, but I don't see a huge problem with this.

  Targets:

  Targets are orderded collections of Tasks, units of work to be
  performed if a Target is executed. Targets can define dependancies on
  other targets within the Project. If a Target is deemed to be executed,
  either by direct definition on the command line, or via a dependancy
  from a currently running target, then all of it's dependancies must
  first be executed.

  Circular dependancies are broken by examination of the dependancy
  stack when a Target is evaluated. If a dependancy is already on the
  stack, then the dependancy is considered to have been satisfied.

  After all dependancies have been executed, the current target has
  its task list examined and the tasks within that list are configured
  and executed in sequential order. More accuratly, when a task is
  executed, an instance of the class that defines the behavior of that
  task is instantiated and then configured with the information from the
  project XML file. It is then executed so that it may be able to perform
  its function. It is important that this configuration happens just
  before execution, and after execution of the previous task, so that any
  configuration information that depends on properties can be properly
  conveyed.

  Tasks:

  A Task is a unit of work in the project. When a task is executed,
  it has access to the Project object allowing it to examine the property
  list of the Project and to resolve filenames into actual File objects.

Build File Structure:

  The top few levels of the build file are easy and shouldn't change much
  from what we have now:

    <project name="foo">
      <property name="bar" value="bop"/>
      <property name="far" value="out"/>
      <taskdef name="joy" class="com.joy.Kill"/>
      <target name="whoopie" depends="cushion">
         <taskimpl ...>
           ...
         </taskimpl>
      </target>
    </project>

  Now, notice that I haven't talked about taskdefs above. I'm starting
  to think that instead of taskdefs defined in the build.xml file, they
  should be defined by something that looks an awful lot like a tag
  library descriptor. See section on directory structure for more.

  The other part that needs work is what happens inside the taskimpl
  areas. Right now reflection is used to set attributes on bean methods
  but it's heniously unclear how the best way to reflect the rest
  of the elements within the taskimpl tag should be performed. For
  example:

    <script>
      <language="somelang">
         if (bar) { set-property("foo", "bar") };
      </language>
    </script>

  Sam, you're the scripting guy, not me, but something along these
  lines, along with a definition of the object model that is
  exposed to the scripting environment (project/target/task +
  properties) would be acceptable to me.

  But, the tough part once again is reflecting this stuff in. We
  need a simple, clearly defined way (just like attribs are set
  using bean methods) that works the same way for every task. And
  just passing in a DOM fragment doesn't cut it as far as I'm
  concerned as I'd like to ensure that the XML impl doesn't
  get too close to the runtime impl and vice versa. It's a data
  format! :)

Installation:

  Far far far too many people are inluding ant.jar with thier
  software. Do people include make? No. Do people include diff?
  No. So, we need to get Ant to the point where it's a first
  class citizen on the user's machine. This means an install
  and it means a directory structure.

  I'm proposing this:

    $install_dir/bin/ant.sh
                    /ant.bat
                /lib/ant.jar
                /ext
                /opt/tasktype1
                    /tasktype2/tasktype2.xml
                              /src/...

  The tasktype directories contain the source code for the
  optional tasks, along with a project file to build them.
  When they are built, they should be placed into the
  /ext directory in a jar format...

     $install_dir/ext/tasktype1.jar
                                   /META-INF/taskdef.xml

  The /META-INF/taskdef.xml file defines the task name and
  the task class.

  When ant starts, it scans the /ext dir, loads in all
  tasks and makes them available to the runtime. It doesn't
  do this by placing them on the classpath in the ant.sh
  script, but by using JAR class loaders.

  When ant is installed, a ant.xml file is placed into the
  user's user.dir that defines where the ant installation
  is. If this isn't present and ant is started, it should
  ask the user.

File Naming Conventions (we gots to have some.. the Project object should
provide the hook to translate these into local File objects)

  All tasks must be written to accept a common representation of
  filenames that can be translated at runtime to a File object that is
  valid for the runtime operating system. This common representation can
  be translated into a File object by a convience method on the Project
  object.

  All directory seperators are the forward slash character ('/')

  All path seperators are the colon (':')

  In cases where the user must specify an absolute path on a
  windows machine that starts with a drive letter, it should look like
  'C:/foo/bar'

OK. That's enought for now.. It's a huge chunk to chew on. Let's hammer on
this and I'll keep a master document (and will check it into CVS) and get
wide agreement on it and then we can move into the finer details.

.duncan



Mime
View raw message