Sprouts is an open-source, cross-platform project generation and configuration tool for ActionScript 2, ActionScript 3, Adobe AIR and Flex projects. It is built on top of Ruby Gems, Rubigen Generators and is intended to work on any platform that Ruby runs on including specifically, Windows XP, Windows Vista, Cygwin, OS X and Linux.

Sprouts can be separated into some core concepts as follows:

Tools

A Tool is a Ruby Gem that usually refers to an executable or binary application. These applications are either natively cross platform, or the Ruby Gem should include a YAML document that tells Sprouts where to go in order to get the appropriate binary for which platform the user is currently running.

CLI Tools are usually referenced by subclasses of Sprout::ToolTask.

Once installed, many Tool Sprouts are made available from your path. For example if you install the sprout-mtasc-tool gem, from that point forward you can execute mtasc from the terminal as follows:

  mtasc -help # Should throw an error
  sudo gem install sprout-mtasc-tool
  mtasc -help # Should download and execute mtasc

Using just Sprout tools by themselves, we now have have the ability to install and manage requisite executables across platforms with zero configuration.

In reality, ‘Tool Sprouts’ are actually nothing more than a naming convention and expected gem configuration, but once those requirements are met, the core Sprout::Sprout can do some important work with them.

Libraries

A Library is simply shared code. Some libraries are distributed with only source, others are only pre-compiled binaries (SWC for ActionScript libraries), and still others are made available in both forms.

The Sprout::LibraryTask will download and copy a remote library sprout gem. The remote archive can include (or reference) either source or a pre-compiled file. For ActionScript libraries, this would be a SWC file.

This task is integrated with some of the compiler tasks in such a way that if an Sprout::MXMLCTask has any number of library tasks in it‘s prerequisites list, each of those libraries will be added to the compiler directive appropriately.

Following is a simple example of a library task. Using only this simple task definition, the Adobe corelib library sprout gem will be downloaded, installed and copied to your Sprout::ProjectModel lib_dir.

  library :corelib

By adding this named task as a prerequisite to your compilation task, that SWC will also be added to the Sprout::MXMLCTask library_path parameter.

  mxmlc 'bin/SomeProject.swf' => :corelib

You can also specify a particular library gem version if the library has changed since your project began.

  library :asunit3 do |t|
    t.version = '3.0.1'
  end

This will ensure that only that particular library version is used for this project.

You may want to refer to a library using a particular task name, but have it use a different library sprout gem. This can be done using the gem_name parameter as follows:

  library :asunit do |t|
    t.gem_name = 'sprout-asunit3-library'
  end

This may be useful because now the AsUnit sources will be installed to:

  lib/asunit

instead of:

  lib/asunit3

and you can now depend on this library as simply +:asunit+ in your compiler tasks.

You can easily create your own library gems using the Sprout::GemWrapTask and then refer to them by gem name.

In order to share your library tasks, you will need to do one of the following:

• Tell interested developers to manually install your library gem
• Upload your gem to any Rubyforge project file releases area.

    If your gem name begins with 'sprout-' and ends with '-library', you (and others) can refer to it by only
    the string in between that prefix and suffix. Otherwise, you (and others) will always have
    to set the gem_name parameter to the full name of your custom library.
  

• Submit your library for inclusion from the ProjectSprouts project.
• Add your gem to your own custom gem_server, and set up your rakefiles to pull from that server

You can search for all available libraries as follows:

  gem search -r sprout-*library

Only results that begin with ‘sprout-’ are known, valid libraries.

Bundles

A Sprout Bundle is a collection of Ruby code that supports a particular interest or technology. At the time of this writing, we have two bundles available.

• ActionScript 2 Bundle (link) which supports ActionScript 2.0 development
• ActionScript 3 Bundle (link) which supports ActionScript 3.0, MXML and AIR development

Bundles are the named entry point that the sprout shell tool uses to find project generators.

Bundles should be packaged and published to the RubyForge gem repository with very specific names as follows:

sprout-#{bundle_name}-bundle where ${bundle_name} is what will be given to the -n parameter of the sprout gem.

The as3 bundle is released as sprout-as3-bundle on RubyForge, but we can simply enter the short name when creating new as3 projects.

Generators

A SproutGenerator is a set of specifically configured folders and files that have been placed in a particular, expected location on disk. The Sprout generator feature is a minor modification to the standard Rubigen generators.

Sprouts modifies the underlying Rubigen Generator implementation in that we need support for multiple languages or technologies while Rubigen is able to simply expect that it‘s generating Ruby code.

Generators can exist in multiple different locations on disk, to learn how to create a new generator, see the Rubigen documentation.

To use a new or existing generator, simply enter it‘s name from within a project after calling

  script/generate

When a string is passed to the generate command, sprouts will look in the following locations in the following order with ‘name’ being the generator name that you have requested:

• #{project_path}/generators/#{name}
• #{project_path}/script/generators/#{name}
• #{project_path}/vendor/generators/#{name}
• #{Sprout::Sprout.sprout_cache}/generators/#{Sprout::ProjectModel.language}/#{name}
• All Rubygems with a name ending with ’-bundle’ and with contents that match ’/lib/sprout/**/generators/[name]’

This means that when you have a new project and enter:

  script/generate foo

We will first look in your project for, ‘generators/foo’, ‘script/generators/foo’ and ‘vendor/generators/foo’.

Assuming no viable generator is found in your project, we will then look in your Sprout::Sprout sprout_cache for a folder named ‘generators/foo’.

Assuming no viable generator is found in your system wide path, we will begin looking inside of installed Ruby Gems. The expected gem will have a file at:

  lib/sprout/**/generators/foo/foo_generator.rb

If no named generator is found in any of these places an exception will be encountered.

Sprouts generators can be initiated from one of two places, either from a project directory with script/generate or directly from the Sprout gem.

When executing generators directly from the Sprout gem, you must send in a bundle base name and know that only ‘project’ generators found in that bundle will be executed.

When executing generators from a project, the Sprout::ProjectModel language parameter is used to determine the bundle (if necessary), and then the Generator name is used to execute any found generator.

Tasks

In Sprouts, a Task is referring to a Rake Task.

Rake is the automated build to written in Ruby. This tool is similar to Ant and Make if you‘re familiar with those technologies.

The main thing that differentiates Rake from it‘s competitors is the fact that Rake tasks are defined and configured in Ruby code rather than XML or C. This lets us more easily avoid repetition throughout a rakefile, and we gain the full power of the Ruby language to apply to our build scripts.

Essentially, Rake allows us to write and maintain much smaller, more digestible build scripts.

To learn more about Rake, check out Martin Fowler‘s seminal article on the subject.

At the time of this writing, Sprouts makes the following Rake tasks available:

• Core Sprout::SFTPTask
• Core Sprout::ZipTask
• Core Sprout::LibraryTask
• As3Bundle Sprout::AsDocTask
• As3Bundle Sprout::AsUnitTask
• As3Bundle Sprout::COMPCTask
• As3Bundle Sprout::MXMLCTask
• As2Bundle Sprout::MTASCTask
• As2Bundle Sprout::SWFMillTask

Sprout

Tools, Libraries and Bundles are distributed as RubyGems and given a specific gem name suffix. For some examples:

  sprout-flex3sdk-tool
  sprout-asunit-library
  sprout-as3-bundle

The Sprout application provides shared functionality for each of the different types of Sprouts.

The Sprout command line tool primarily provides access to project generators from any sprout bundle that is available to your system, either locally or from the network.

When executed from the system path, this class will download and install a named bundle, and execute a project generator within that bundle. Following is an example:

  sprout -n as3 SomeProject

The previous command will download and install the latest version of the sprout-as3-bundle gem and initiate the project_generator with a single argument of ‘SomeProject’. If the string passed to the -n parameter begins with ‘sprout-’ it will be unmodified for the lookup. For example:

  spout -n sprout-as3-bundle SomeProject

will not have duplicate strings prepended or suffixed.

Some additional resources or references:

Rake: rake.rubyforge.org martinfowler.com/articles/rake.html

RubyGems:

• www.rubygems.org
• www.linuxjournal.com/article/8967

Ruby Raven (Mostly Inspiration)

• raven.rubyforge.org