BuildTools-Introduction


The SproutCore build tools process your source code to produce static JavaScript, CSS, and HTML that are optimized for delivery over the web.  By using the build tools for your application, your application will not only load faster, but it will also be easier to maintain.

 

Intended Audience

 

This guide is for anyone who intends to use the SproutCore build tools in their application.  You will learn how to tweak the build tool settings to fit your particular deployment requirements as well as how you can organize and distribute your code using the build tools management system.

 

Outline

 

 

This is a work in progress.  We're still working through what needs to be covered here but some items might include:

 

Build Task Notes

 

This information needs to be put into one of the build pages above.  Placing here for now until it can be added.  

 

The SproutCore build tools work by running a set of build tasks to discover which files need to be built in your project and then building actual assets.  You can extend the build system by defining additional build task and hooking them into the existing set of build tasks.

Since the build system is based on Rake, extending the tasks is easy.  You just define additional tasks you want run inside your Buildfile.  See below for an example.

 

Most of the build tasks defined by the build tools are used to construct a manifest of your project.  A unique manifest is created for each unique target/language that you build.  It contains a list of all of the entries that need to be built in your application along with the Rake task that should be invoked to build that particular resource.   

 

Note that entries in your manifest can include both final products and intermediates.  For example, you will find entries in your manifest for every input JavaScript file in your project along with an entry for the combined javascript.js that combines all of them.  Entries that are "hidden" will not be included in the final build product, but may be used as intermediates for other targets.

 

The diagram below shows all of the built in tasks and the order they run in.  Click for a larger view.

 

(Found in "sproutcore-abbot/design/Technical Notes.graffle")

 

 

Adding Your Own Build Tasks Example

 

For example, let's say you wanted to generate an extra JavaScript file with some config information that will be included in the final combined file.  You would first need to add a task that is run before the manifest:prepare_build_tasks:combine task to add an entry in the manifest for your new file:

 

task :add_config_file do

  MANIFEST.add_entry 'config_file.js',

    :build_task => :build_config_file,

    :entry_type => :javascript

end

task 'manifest:prepare_build_tasks:combine' => :add_config_file

 

Now when you run your build, a manifest entry will be added for a file called "config_file.js".  Since the type is "javascript" it will be included in any combined javascript output.  When it comes time to build this file, the build tools will run the "build_config_file" build task.  You need to add this task to your Buildfile also:

 

task :build_config_file do

  File.open(DST_PATH, 'w+') do |f|

    f << "var CONFIG = { ... };"

 end

end