This page explains the internal design for the new "Abbot" line of build tools currently under development for SproutCore 1.0.  It does not apply to the build tools included in the 0.9.21 or earlier release of the tools.

About Build Tools Internals

This page describes the internal structure of the SproutCore build tools.  You should read this material if you plan on customizing the build tools beyond the hooks that are documented in the mainline source or if you want hack the build tools themselves. 

Getting Started

The SproutCore build tools are written as a single library in Ruby, with each component of the build tool separated out into its own set of classes.  To work with the build tools internals, you should have a basic understanding of Ruby.  The system for managing build tasks (i.e. the tasks you can define in your Buildfile), it would be helpful to understand a little bit about Rake, the Ruby-based replacement for Make, that the Buildfile system is based upon.

Basic Structure

The Build Tools Ruby library can be broken down into three basic subsystems.  These classes can be found in the "lib/sproutcore" folder of the source:

• Models.  The model classes are used to store the data used by the tool to do their work.  They include classes for Projects, Targets, Manifests, and ManifestEntries.
• Buildfiles.  The Buildfile and related classes implement support for loading and processing buildfiles.  A buildfile exports both configs, which can be used to customize the build system behavior, and tasks which are executed at key points in the process.
• Tools.  The tool classes implement the individual tools accessible from the command line in SproutCore.  Each tool can be invoked directly from code or it can process command line arguments sent directly from the command line.
• Builders.  These classes implement the functionality needed to build a particular resource.  Builders implement some of the more complex build support needed for manifests, JavaScript, stylesheets, html, and so on.
• Server.  The server classes implement a basic Rack-compatible server for dynamically building assets on demand.  The server classes are used by the sc-server tool, but you can also call them directly if you are hosting a Ruby-based web application and want to generate your SproutCore application on demand instead of having to run a pre-process build.

In addition to these core ruby classes, much of the actual build system logic is implemented as built-in build tasks accessible from a Buildfile.  You can find these files in the "buildtasks" folder of the source:

• Build Tasks.  These tasks actually build one or more source files into a destination output file.  Each entry in a manifest names a build task to execute when the entry is built.
• Generator Tasks.   These tasks can generate template files from source templates.  The templates are defined in the "generators" directory of the source.
• Model Tasks.  There are a few tasks that are invoked when a model is being loaded that provide hooks for developers to further customize the model.  These include tasks such as project:prepare, target:prepare, manifest:prepare, manifest:build, and entry:prepare. 

Unit Testing

The new SproutCore build tools contain comprehensive unit tests written in rspec.  When you modify the build tools, it is important that you run these tests to verify that nothing has broken.  When you add new features, be sure to add unit tests in the spec directly also.  In general, unit testing should be self explanatory if you peek at the other unit tests in the folder, but here are a few hints to get you started:

• Simply type "rake spec" on the command line to run the unit tests in short form or "rake" to run them in long form.
• The unit tests should follow the exact same structure as the main library and buildtask sources the reflect (except that we don't put the ruby source classes all the way down in ./lib/sproutcore to make it easier to manage).
• In general, each Ruby class or build task file should have a matching directory.   Each method or build task should have its own *_spec.rb file within that directory that contains tests for the method.  If a method does not have a matching file, it usually means the developer has not tested the method or decided it was too simply to warrant unit testing.

Please note that no commits will be taken into the master branch of any project if it fails unit tests.    Instead your changes will likely be merged into a branch and you will be asked to fix the unit tests first.