Project Sprouts

Ruby for ActionScripters

2011-01-20T00:00:00-08:00

Ruby for ActionScripters

20 Jan 2011 – Luke Bayes

Ruby is a dynamic, open source programming language with a focus on simplicity and productivity. It has an elegant syntax that is natural to read and easy to write.

Ruby Website

This means that Ruby has opinions, and many of Ruby’s opinions are exactly inverted from what you may have grown to love in ActionScript. There was a time when this made me uncomfortable, and I’m sure it will make some of you uncomfortable too. Well, not you of course, but maybe someone you know…

The intention of this article, is to provide a brief introduction to Ruby for developers that are already familiar with ActionScript 3.0. It is not my intention to provide comprehensive coverage of the Ruby language here. For a much more well-written and far more comprehensive explanation of Ruby, please take the time to read Why’s Poignant Guide to Ruby, quite possibly the most entertaining and well-written computer book in history.

Ruby Pomegranate Seeds courtesy of Greencolander and the Creative Commons license.

Quack like a what?

Ruby is a dynamic language, which means that a variable can be any concrete data type. The important thing is that an object define the methods and attributes that its clients attempt to access. This paradigm is often referred to as Duck Typing.

Trying Ruby

If you have installed Ruby (Preferably with RVM or something similar), you can kick off a Read Eval Print Loop (REPL) by typing:

irb

(Type ‘quit’ and hit enter to leave the REPL)

The puts method will send a String value to stdout and you can think of this like ActionScript’s trace method.

puts 'Hello World'

Try running irb and then puts some messages now.

When using irb, you can do the following to try out Sprout features.

require 'rubygems'
require 'sprout'

# Output the methods on Sprout (minus the detritus from Object):
puts Sprout.methods - Object.methods

# Output Sprout.home
puts Sprout.home
puts Sprout.cache

Strings

There are a handful of different ways to declare Strings in Ruby, but the main thing I’d like to highlight here is the difference between single quotes and double quotes.

A String that is defined within single quotes will contain literally whatever is defined within the quotes. This means that backslashes will not be rendered as escape sequences, they will just be backslash characters. There is no way to insert expressions in between single quotes, so if you want to assemble a string with single quotes, this is done by concatenating different strings together.

Single quoted strings are usually preferred as they cost less in terms of work. I usually use single quotes wherever I don’t need an evaluated expression or escape sequence, but for the benefit of people that don’t know about these differences, I do try to use double quotes in generated Rake files wherever someone might try an expression (like in task names).

A String that is defined within double quotes will be interpreted for embedded Ruby expressions and escape sequences will be resolved so that they are replaced with the character literal that they represent.

suffix = "World!\n"
str = "Hello #{suffix}"

If you’re thinking in ActionScript, you’ll probably be tempted to concatenate Strings with expressions like:

a = 'aaa'
b = 'bbb'
puts 'a: ' + a + ' b: ' + b

While this will usually work, it will explode if the expression values are nil. The preferred way to assemble Strings and expression values (especially for debugging), is to use double quotes and Ruby expression syntax like:

a = 'aaa'
b = 'bbb'
puts "a: #{a} b: #{b}"

This will call to_s on provided expressions and insert an empty String for values that are nil.

Symbols

Ruby has an interesting primitive called a Symbol. Symbols are not Strings, but are often used in places where a String might also suffice. There are some differences between Symbols and Strings and the first one is that Symbols are more memory efficient than Strings.

A Symbol is defined (or referenced) in Ruby with a leading colon as follows:

name = :beaker

A good rule of thumb that Jim Weirich shared and that I agree with, is as follows:

If the contents (i.e. the sequence of characters) of the object is important, use a String.
If the identity of the object is important, use a Symbol.

The idea here, is that if you’re just trying to give a meaningful name to a pointer (as in Hash keys, or referring to methods by name), then Symbols are probably appropriate. If the value is what’s important, Strings might make more sense.

You can transform a String to a Symbol with the to_sym method, and you can transform a Symbol to a String with the to_s method. Outside of a Rails application Strings are not considered equal to Symbols that look similar.

:beaker == 'beaker'        # false
:beaker.to_s == 'beaker'   # true
:beaker == 'beaker'.to_sym # true

Symbols are a tricky part of Ruby and it’s important when working with Rake files to understand when a Symbol is appropriate and when it is not.

In Rake, a Symbol is often used for a Rake task name, unless that task refers to a file, then a String must be used. This is because Symbols cannot include slashes, dots or other important components of a File name.

More information on Symbols

Parentheses

The parentheses that surround parameters in a Ruby method declaration (and method calls) are optional, and by convention, are only used when critical for proper execution, or to improve legibility for nested expressions. As with most things stylish there is little consensus on when to use or omit parentheses in Ruby.

Making parentheses optional does take some time to get used to, but eventually it leads to improved readability, especially in environments like Rake files.

Following are some examples to help you understand this issue.

This method in ActionScript:

public function foo(a:String, b:String):void {
  trace("a: " + a + " b: " + b);
}

Could be defined like this in Ruby:

def foo a, b
  puts "a #{a}, b #{b}"
end

But may also be written like this:

def foo(a, b)
  puts "a #{a}, b #{b}"
end

Additionally, to call that method in ActionScript you might:

foo("bar", "baz");

But in Ruby:

foo "bar", "baz"

Of course, the following is also valid Ruby:

foo("bar", "baz")

You may be wondering, “When should I add the parens?” at this point. Here is a reasonable example of an expression that probably should get parentheses:

assert foo("bar", "baz")

This expression is calling the imaginary foo method, sending it two arguments, bar and baz, then it’s sending the return value of that method call to the assert method.

Even though the interpreter can figure out what’s going on without them, it’s arguably more readable to parenthesize nested expressions.

Return values

You should also know that Ruby methods always return a value, whether you use the return keyword or not. The last expression that is evaluated within a Ruby method is what is returned. This can of course, be nil.

Hash Rockets

Ruby Hashes are historically delimited by a “Hash Rocket”, this is an equal sign, followed by a greater than sign, like:

=>

To show what I mean, the following ActionScript Hash:

var hash:Object = { a: 'a', b: 'b', c: 'c' };

Could be written in Ruby like this:

hash = { :a => 'a', :b => 'b', :c => 'c' }

Even though the Hash Rocket is no longer required in Ruby 1.9.x, Sprouts is still using it for the time being. We’ll likely update to the new (more ECMA-like) syntax at some point in the future, but while we generally work in legacy versions of Ruby, there’s no good reason to actively break backwards compatibility.

Hash Brackets

You should also note that, like parentheses on methods, curly brackets around Hashes are optional, so the previous Hash may also be declared like:

hash = :a => 'a', :b => 'b', :c => 'c'

Notice how the Ruby Hash prefixes the Hash keys with a colon. This indicates that we’re using Symbols as keys.

Rake

I believe that Rake (and how Sprouts uses) it is a large enough topic for it’s own post, but while we’re talking about duck typing, Strings, Symbols and Hashes, I really want to highlight how these syntactic concepts are exploited in Rake.

A simple, named Rake task:

# Note the Symbol name:
task :my_task do
  # Do some work here.
end

A simple, file Rake task:

# Note the single quotes:
name = 'SomeProject'

# Note the double-quotes and expression:
file "bin/#{name}Runner.swf" do
  # Create the file here.
end

A simple, named Rake task that depends on another:

# Note the hash with a single Symbol key
# and Symbol value:
task :my_task => :other_task do
  # Do some work here.
end

A simple, named Rake task that depends on multiple other tasks:

# Not the hash with a single Symbol key,
# and Array of Symbol values:
task :my_task => [:other_task_one, :other_task_two] do
  # Do some work here.
end

When referring to Rake tasks by name, it’s generally a good idea to use Symbols for tasks that were defined with Symbols and Strings for tasks that were defined as such.

For more detailed (and well-written) information, be sure to read Martin Fowler’s seminal post on Rake.

Conclusion

That’s probably enough Ruby to get you through reading and editing a Rake file. I sincerely hope you find yourself intrigued by this language and, like me, get drawn into a new way of considering programming problems.

If you find anything here in error, please let us know, or better yet – fork, fix and send a pull request.

Using the Flex DeBugger (FDB)

2011-01-19T00:00:00-08:00

Using the Flex DeBugger (FDB)

19 Jan 2011 – Luke Bayes

Debug what?

FDB is a command line debugger. It provides us with the ability to capture, introspect and control the execution flow of a running SWF file by connecting to the Debug Flash Player and exposing a variety of actions to its user. In order to use FDB, we need to first build a SWF file with the debug flag set to true, and secondly, we need to run that SWF within a debug Flash Player.

It just so happens that Sprouts downloads, installs and executes a debug Flash Player for whatever operating system you’re on.

As you’ll soon see, we also make it incredibly simple to drop into a debug session with any SWF file that you build with Sprouts.

To complete this tutorial, you’ll need the following RubyGems installed:

flashsdk >= 1.0.20.pre
sprout >= 1.1.10.pre

You can get both of these with:

gem update flashsdk --pre

layDeBugger courtesy of oceandesetoiles and the Creative Commons license.

How do I do what?

You can coerce any flashplayer task to drop into FDB by simply calling the fdb task first.

rake fdb test

This should produce something that approximates the following output:

(in /Users/lbayes/Projects/Sandbox/OtherProject)
mxmlc -debug 
      -library-path+=lib/asunit4/AsUnit-4.2.2.pre.swc 
      -output=bin/OtherProject-test.swf 
      -source-path+=test 
      -static-link-runtime-shared-libraries src/OtherProjectRunner.as

Loading configuration file flex-config.xml
bin/OtherProject-test.swf (49771 bytes)
[MXMLC] Compilation complete in 3.305054 seconds.
Adobe fdb (Flash Player Debugger) [build 16076]
Copyright (c) 2004-2007 Adobe, Inc. All rights reserved.
Waiting for Player to connect
(fdb) run

Player connected; session starting.
Set breakpoints and then type 'continue' to resume the session.
[SWF] bin:OtherProject-test.swf - 110,886 bytes after decompression
(fdb)

You should notice that the Flash Player has been initiated, but doesn’t have focus and is basically unresponsive. At this time, you can interact with FDB in preparation for the execution of your SWF file. This is usually the point in time when one might set some breakpoints.

Before we dig into break points, let’s ask FDB what else we can do here by typing ‘help’ and hitting enter.

(fdb) help

Typing help, should produce something like the following:

New to fdb? Do 'tutorial' for basic info.
List of fdb commands:
bt (bt)             Print backtrace of all stack frames
break (b)           Set breakpoint at specified line or function
catch (ca)          Halt when an exception is thrown
cf (cf)             Display the name and number of the current file
clear (cl)          Clear breakpoint at specified line or function
condition (cond)    Apply/remove conditional expression to a breakpoint
continue (c)        Continue execution after stopping at breakpoint
commands (com)      Sets commands to execute when breakpoint hit
delete (d)          Delete breakpoints or auto-display expressions
directory (dir)     Add a directory to the search path for source files
disable (disab)     Disable breakpoints or auto-display expressions
disassemble (disas) Disassemble source lines or functions
display (disp)      Add an auto-display expressions
enable (e)          Enable breakpoints or auto-display expressions
file (fil)          Specify application to be debugged.
finish (f)          Execute until current function returns
handle (han)        Specify how to handle a fault
help (h)            Display help on fdb commands
home (ho)           Set listing location to where execution is halted
info (i)            Display information about the program being debugged
kill (k)            Kill execution of program being debugged
list (l)            List specified function or line
next (n)            Step program
print (p)           Print value of variable EXP
pwd (pw)            Print working directory
quit (q)            Exit fdb
run (r)             Start debugged program
set (se)            Set the value of a variable
source (so)         Read fdb commands from a file
step (s)            Step program until it reaches a different source line
tutorial (t)        Display a tutorial on how to use fdb
undisplay (u)       Remove an auto-display expression
viewswf (v)         Set or clear filter for file listing based on swf
watch (wa)          Add a watchpoint on a given variable
what (wh)           Displays the context of a variable
where (w)           Same as bt
Type 'help' followed by command name for full documentation.

This is a list of commands (and shortcuts) for interacting with FDB. If you look closely at the history in your terminal, you should see that Sprouts has already called the run command and then opened your SWF file. You should also note that you can run the tutorial command any time to get another, slightly more terse introduction to command line debugging.

You can get more specific help on a given command by typing help followed by the command you’re interested in. Try this now, with the break command:

(fdb) help break

This should produce something like:

Set breakpoint at specified line or function.
Examples:
  break 87
    Sets a breakpoint at line 87 of the current file.
  break myapp.mxml:56
    Sets a breakpoint at line 56 of myapp.mxml.
  break #3:29
    Sets a breakpoint at line 29 of file #3.
  break doThis
    Sets a breakpoint at function doThis() in the current file.
  break myapp.mxml:doThat
    Sets a breakpoint at function doThat() in file myapp.mxml.
  break #3:doOther
    Sets a breakpoint at function doOther() in file #3.
  break
   Sets a breakpoint at the current execution address in the
   current stack frame. This is useful for breaking on return
   to a stack frame.
To see file names and numbers, do 'info sources' or 'info files'.
To see function names, do 'info functions'.
Abbreviated file names and function names are accepted if unambiguous.
If line number is specified, break at start of code for that line.
If function is specified, break at start of code for that function.
See 'commands' and 'condition' for further breakpoint control.

We can see from this help content, that there are a variety of ways that we might set a breakpoint. My project was created with the sprout-as3 command and was called OtherProject, which means that I have a test runner called OtherProjectRunner. I’m going to set a break point in that file now with:

(fdb) break OtherProjectRunner:15

And then I’m going to continue execution of the SWF until the breakpoint is encountered.

(fdb) continue

(If you remember the help content, this can also be done by simply typing c followed by the enter key)

The SWF will execute until it encounters the breakpoint that I set and once the breakpoint is hit, FDB will emit some context information like:

Breakpoint 1, OtherProjectRunner() at OtherProjectRunner.as:15
 15                core.start(AllTests, null, this);
(fdb)

Following are some of the things I might do here:

Introspect the running SWF file with the info commands (type info to see these options)
Set variables and values directly into the environment to see what happens using the set command
Step through the SWF, one line or function at a time using the step command, followed by list or i s (info stack).

When you’re done, you can type the quit command, or you can continue past your breakpoints and then manually close the SWF. Or you can just hit CTRL+C to kill the process – which should clean everything up for you.

Upcoming releases of Sprouts will combine a special test result printer, with the FDB task to figure out when your test harness has finished running and then automatically kill the Flash Player process.

This should be enough to get you going with the Flex DeBugger in your Sprout projects.

Conclusion

This brings us to the end of the “Using the Flex DeBugger (FDB)” post. If you find anything here in error, please let us know, or better yet – fork, fix and send a pull request.

Using the Flex Compiler SHell (FCSH)

2011-01-18T00:00:00-08:00

Using the Flex Compiler SHell (FCSH)

18 Jan 2011 – Luke Bayes

What the sHell?

MXMLC and COMPC, when run by themselves, are slow. Not a little slow, not kind of slow – but brutally, soul-crushingly, terribly SLOW. At least that’s how they feel to someone like me. Someone that suffers from chronic, advanced, impatience.

Fortunately, there is finally relief!

Sprouts Shell courtesy of Mike Epp and the Creative Commons license.

What is that at the end of this long, dark tunnel?

More than a few years ago, someone at Macrodobe realized how slow their compilers are, and released the inappropriately-named, yet awesomely helpful, “Flex Compiler SHell” (or FCSH for short). FCSH doesn’t necesarily have anything to do with the Flex framework, but provides a long-lived process that we can start up once, leave running, and ask to execute our compilation tasks. This process will retain lots of expensive information in memory and only recompile files that have changed since the last request. Using FCSH by hand is really not practical, and with previous versions of Sprouts, it was also not as easy as it should be.

I do believe that is a light!

After many, countless hours of deliberation and coding and testing and coding again, FCSH is finally exposed to Sprout projects in a very simple way:

1) In a new terminal, start the fcsh service.

# cd into your project:
cd ~/SomeProject
# Start the fcsh session:
rake fcsh:start

(Hit CTRL+C any time to terminate this FCSH process)

2) In another new terminal (I use GNU Screen thanks to a smart guy I work with), execute the fcsh task before any mxmlc or compc tasks that you would normally call.

# cd into your project:
cd ~/SomeProject
# Compile and run tests:
rake fcsh test
# or the 'default' task:
rake fcsh default
# or clean first:
rake clean fcsh test

That’s it!

Just run the fcsh task before any other tasks, no editing of source files necessary!

But how does it really work?

I’m so glad you asked!

Under the covers, in the latest release of the flashsdk, the mxmlc and compc tasks check for a couple of environment variables before actually calling out to the underlying process.

If the USE_FCSH environment variable value is ‘true’, then the compiler will attempt to connect to an FCSHSocket on FCSH_PORT (12321 by default). The fcsh task simply sets this value to ‘true’, but you can also set this value on the command line, like:

rake test USE_FCSH=true

In your .bashrc or .bash_profile (will impact all Sprout v1.x projects on your system):

export USE_FCSH=true

Or in your Rakefile to always use FCSH for this project:

# Yes, it's a smelly string, but that's what Ruby wants for some reason...
ENV['USE_FCSH'] = 'true'

Regardless of which method you choose to trigger a build with FCSH, you must have an instance of the FCSH server running from the same project directory before calling the build task, or else you’ll get a failure. Once again, you can start the FCSH server with:

rake fcsh:start

If you forget this mysterious incantation, you can always list out the available rake tasks with the -T option:

rake -T

The Railroad

If you want to run builds with FCSH from multiple directories, you’ll need to give each client and server a unique port to connect on. You can do this in any of the ways indicated above for the USE_FCSH parameter, except you’ll specify the FCSH_PORT instead.

On the command line:

rake fcsh test FCSH_PORT=12567

In each shell instance:

export FCSH_PORT=12567

(Note: To always use a custom port, the export could be placed into your .bashrc or .bash_profile)

Anywhere in your Rakefile:

ENV['FCSH_PORT'] = 12567

Conclusion

You should now be able to easily integrate FCSH into your Sprouts v1.x build process at whatever scope you prefer and customize it appropriately too.

This brings us to the end of the “Using the Flex Compiler SHell (FCSH)” post. If you find anything here in error, please let us know, or better yet – fork, fix and send a pull request.

Using Sprout Generators

2010-12-31T00:00:00-08:00

Using Sprout Generators

31 Dec 2010 – Luke Bayes

Generators have been rewritten from scratch for Project Sprouts v1. The new generators are much easier to test, distribute, and modify. This post is going to cover usage (or consumption) of existing generators, we’ll put together a second post where we go into more detail about creating generators.

Sprout Germinator image courtesy of Easy Green.

There are two kinds of generator, an Application generator and a Feature generator. The primary difference between them, is that a Feature generator expects to be run from a folder that contains a Gemfile. This is because feature generators can be easily overridden by gems that are loaded from the Gemfile.

For example, the default sprout-class generator calls a null TestClassGenerator that does nothing. But the AsUnit 4 Rubygem overrides the TestClassGenerator with one that generates an AsUnit 4 test case, and then calls the SuiteClassGenerator – which it also provides. Someone that is so inclined, could easily build a flexunit Rubygem that overrides the TestClassGenerator code so that it gets called instead of AsUnit (hint, hint).

The Application Generator

Let’s start out by demonstrating a few generators and talking about what they do. If you haven’t already, get the Flash SDK (>= 1.0.18) installed on your system:

# Install the ActionScript 3 / Flash / Flex bundle:
gem install flashsdk --pre

You can figure out what version you have installed with:

gem list flashsdk

Now, let’s see what generators we have available to us by running the following and then hitting the TAB key.

sprout-

You should see a collection of executables – something like:

sprout-as3        sprout-class      sprout-flex       sprout-generator  [etc]

We’re going to go ahead and create an ActionScript 3 project named, ‘SomeProject’ with the following:

sprout-as3 SomeProject

You should see something like the following in your terminal:

Created directory: ./SomeProject
Created file:      ./SomeProject/rakefile.rb
Created file:      ./SomeProject/Gemfile
Created directory: ./SomeProject/src
Created file:      ./SomeProject/src/SomeProject.as
Created file:      ./SomeProject/src/SomeProjectRunner.as
Created directory: ./SomeProject/assets
Created directory: ./SomeProject/assets/skins
Created file:      ./SomeProject/assets/skins/DefaultProjectImage.png
Created directory: ./SomeProject/lib
Created directory: ./SomeProject/bin

Let’s pretend we don’t like what just happened. Maybe we meant to call this OtherProject instead. All generator actions can easily be “un-executed” by appending the same command with the argument --destroy. Let’s try this now, by pressing the up-arrow in the terminal, to get the most recently executed command, and then add --destroy to the end.

sprout-as3 SomeProject --destroy

You should see something like:

Removed directory: ./SomeProject/bin
Removed directory: ./SomeProject/lib
Removed file:      ./SomeProject/assets/skins/DefaultProjectImage.png
Removed directory: ./SomeProject/assets/skins
Removed directory: ./SomeProject/assets
Removed file:      ./SomeProject/src/SomeProjectRunner.as
Removed file:      ./SomeProject/src/SomeProject.as
Removed directory: ./SomeProject/src
Removed file:      ./SomeProject/Gemfile
Removed file:      ./SomeProject/rakefile.rb
Removed directory: ./SomeProject

This removal is safe, in that it should only delete directories that the generator created, and it should only delete them if they’re empty. It should also only delete files if they’re identical to what would be generated.

Now, let’s run the generator again with ‘other_project’ for the input: (Note the snake case)

sprout-as3 other_project

You should see something like:

Created directory: ./other_project
Created file:      ./other_project/rakefile.rb
Created file:      ./other_project/Gemfile
Created directory: ./other_project/src
Created file:      ./other_project/src/OtherProject.as
Created file:      ./other_project/src/OtherProjectRunner.as
Created directory: ./other_project/assets
Created directory: ./other_project/assets/skins
Created file:      ./other_project/assets/skins/DefaultProjectImage.png
Created directory: ./other_project/lib
Created directory: ./other_project/bin

Notice how the snake case was respected for the project directory, but it was converted to camel case for the classes and files. This is one of the great features of the new generators. You can see how easy it is to do this by checking out the source file for the class generator.

The Feature Generator

Now, let’s go into the new project and make sure our gems are up to date:

cd other_project
bundle install

Create a new class using the fully-qualified name:

sprout-class utils.MathUtil

You should see output like:

Created directory: ./src/utils
Created file:      ./src/utils/MathUtil.as
Created directory: ./test/utils
Created file:      ./test/utils/MathUtilTest.as
Skipped existing:  ./test
Created file:      ./test/AllTests.as

Notice how a test case and test suite were created. These were only created because the project Gemfile loads the asunit4 gem.

Here’s what’s in that Gemfile:

source "http://rubygems.org"

gem "flashsdk", ">= 1.0.0.pre"
gem "asunit4", ">= 4.2.2.pre"

This Gemfile is how the ClassGenerator, TestClassGenerator and SuiteClassGenerator knew what to build. If you’re interested in learning more about Gemfiles in general, you should check out the GemBundler site.

Even though I’m sure no one would ever want to generate a class without an associated test case, let’s pretend we want to do just that. Since I can never remember exactly what parameters to use, let’s go ahead and run the generator with no arguments in order to see its help content:

sprout-class

You should see something like the following:

[ERROR - Sprout::Errors::MissingArgumentError] input is required and must not be nil

Usage: sprout-class [options]
        --help                       Display this help message
        --path=[STRING]              Default Description
    -d, --destroy                    Default Description
    -f, --force                      Default Description
    -q, --quiet                      Default Description
        --templates+=[a,b,c]         Default Description
    -i, --input=STRING               Default Description
    -p, --package=[STRING]           Default Description
    -a, --assets=[STRING]            Default Description
        --skins=[STRING]             Default Description
        --test=[STRING]              Default Description
    -l, --lib=[STRING]               Default Description
    -b, --bin=[STRING]               Default Description
    -s, --src=[STRING]               Default Description
    -t, --[no-]test-class            Default Description

Of course, now that we see the help output, we see that we could have run the generator with the --help parameter.

Notice how all of these say, “Default Description”, this is because I’d like to extract the rdoc comment directly from the source file in order to avoid duplication. I haven’t gotten around to this task, so if you’re interested in contributing, please fork and send a pull request.

Even though these directives don’t have descriptions, and we can experiment with some confidence thanks to the --destroy argument, I would still check my work into a Git repository before running any generators in an existing project.

In any case, let’s go ahead and try to run this class generator with the --no-test-class argument for a new class.

sprout-class utils.OtherUtil --no-test-class

You should see that the test case and test suite were not created:

Skipped directory: ./src/utils
Created file:      ./src/utils/OtherUtil.as

Working with Templates

The ability to easily customize and control generator templates is one of the main driving forces behind the generator rewrite. You can override a particular template for a single generator execution, a specific project, or globally for your system. Generator templates are simply named erb files – but allowances have been made for alternative template languages. Each template is loaded and rendered individually, so you you only need to replace those templates that you’re interested in.

The first thing you’ll want to figure out, is the name of the template you want to override. For the time being, you can find this out by checking the source code for the project that defined the generator. Following are some template folders to peruse:

Let’s assume we want to replace the template for the ClassGenerator, found in the Flash SDK. You can see on line 59 that the generator is looking for a template file named, ‘ActionScript3Class.as’.

This means that once we decide which scope to operate on, we need to place a file with the same name into the correct directory.

Execution Templates

Let’s start by replacing the template for a single generator execution. Let’s start with the contents of the original template.

package <%= package_name %>{

    public class <%= class_name %> {

        public function <%= class_name %>() {
        }
    }
}

While I’m sure you would never want to unsnuggle your brackets, let’s imagine your boss is going to force you to do it – just for this one file.

Create a new directory in your project (from above) called, “bossypoo” and within that directory, create a new file named ActionScript3Class.as, and paste the following contents into it.

/*********************
Copyright: Pointyhaired Bossypoo, 2010
*********************/
package <%= package_name %>

{

    public class <%= class_name %>

    {

        public function <%= class_name %>()
        {
        }
    }
}

Now run the class generator just like before, but provide the new, custom templates folder:

sprout-class utils.BossyUtil --templates+=bossypoo

You’ll have to forgive the extra carriage returns, as my ERB templating appears to be a little greedy with whitespace. After running the generator, you should see everything looks normal.

Now that approach is pretty neat, but we don’t want to have to remember to add that --templates argument every.single.time we run a generator. Which brings us to;

Project Templates

In addition to setting the --templates parameter manually, there are a number of locations that generators will scan for templates. You can get the definitive list of template paths for any generator that extends Sprout::Generator::Base by running the generator with the --show-template-paths parameter.

On my computer, this results in:

The following paths will be checked for templates:
  * --templates+=[value]
  * config/generators
  * vendor/generators
  * /Users/lbayes/Library/Sprouts/1.1/cache/generators
  * ENV['SPROUT_GENERATORS']
  * /Users/lbayes/.gem/ruby/1.9.2/gems/flashsdk-1.0.17.pre/lib/flashsdk/generators/templates

If you create either of the config/generators or vender/generators paths in your project directory and place that template in there, anytime you run the class generator, it will get picked up.

System Templates

If you look closely at the previous list, you’ll see that one of the folders is in the global Sprout cache, and another is an environmental variable. I hope you can figure out how to create a folder in the cache location. If you place a generator template here, it will be picked up for any Application generators, and any projects that don’t override the template in their own scope.

You can set the environmental variable in a number ways, one of which is on the command line like this:

sprout-class utils.MathUtil SPROUT_GENERATORS=relative/or/absolute/path/to/templates

Or you can set it within your .bash_profile or .bashrc file like:

export SPROUT_GENERATORS=/absolute/path/to/templates

You could also set it in any Ruby source file that gets loaded from your Gemfile. In Ruby, this would look like:

ENV['SPROUT_GENERATORS'] = /absolute/path/to/templates

Conclusion

This brings us to the end of the “Using Generators” tutorial. If you find anything here in error, please let us know, or better yet – fork, fix and send a pull request.

The next article in the series will describe how to create generators.

Migrating from 0.7 to 1.0 beta

2010-12-29T00:00:00-08:00

Migrating from 0.7 to 1.0 beta

29 Dec 2010 – Luke Bayes

There are some significant changes that have come with the new version of Sprouts. This guide should help you transition a legacy Sprouts project into the new hotness. Let’s get sideways.

Image courtesy of Rhys Alton and the Creative Commons license.

In order to simplify this, let’s start assuming you have a default version 0.7 project called ‘SomeProject’.

Assuming this is so, you’ll likely have some AsUnit 3.0 tests, and a Rakefile that looks something like the following:

require 'sprout'
# Optionally load gems from a server other than rubyforge:
# set_sources 'http://gems.projectsprouts.org'
sprout 'as3'

############################################
# Configure your Project Model
project_model :model do |m|
  m.project_name            = 'SomeProject'
  m.language                = 'as3'
  m.background_color        = '#FFFFFF'
  m.width                   = 970
  m.height                  = 550
  # m.use_fdb               = true
  # m.use_fcsh              = true
  # m.preprocessor          = 'cpp -D__DEBUG=false -P - - | tail -c +3'
  # m.preprocessed_path     = '.preprocessed'
  # m.src_dir               = 'src'
  # m.lib_dir               = 'lib'
  # m.swc_dir               = 'lib'
  # m.bin_dir               = 'bin'
  # m.test_dir              = 'test'
  # m.doc_dir               = 'doc'
  # m.asset_dir             = 'assets'
  # m.compiler_gem_name     = 'sprout-flex4sdk-tool'
  # m.compiler_gem_version  = '>= 4.0.0'
  # m.source_path           << "#{m.lib_dir}/somelib"
  # m.libraries             << :corelib
end

desc 'Compile and debug the application'
debug :debug

desc 'Compile run the test harness'
unit :test

desc 'Compile the optimized deployment'
deploy :deploy

desc 'Create documentation'
document :doc

desc 'Compile a SWC file'
swc :swc

desc 'Compile and run the test harness for CI'
ci :cruise

# set up the default rake task
task :default => :debug

One of the (many) problems with this Rakefile, is that there is too much magic.

All of this magic makes it very difficult for new users to learn what’s going on here. While it looks simple, there is an enormous amount of work happening. If we wanted all of the same features that are exposed in this project, but using Sprouts v 1.0, here’s what should happen.

1) Add a Gemfile

Add a new file to the root of the project named Gemfile, with the following contents:

source "http://rubygems.org"

gem "flashsdk", ">= 1.0.0.pre"
gem "asunit4", ">= 4.2.2.pre"

This Gemfile is a feature of Gem Bundler which is an awesome tool that does a great job of helping us decouple our applications from the mechanism that is used to distribute them – generally RubyGems.

This file describes all of the Ruby Gems that our application should load in order for the require statements within it to work.

Of course, some Ruby Gems require others, which themselves require others. Gem Bundler does a great job of managing these dependencies for us, so we should only declare our outermost dependencies.

It’s important to note, that if you rely on any externally distributed library or tools (like the Robot Legs library for example), you should add that dependency to this Gemfile.

2) Update the Rakefile

Project Sprouts has always been an ambitious effort that probably attempts to do a little too much. One of the things that has been difficult to manage is how much or how little magic sauce to use. I believe that the 0.7 release of Sprouts uses too much magic, and the version 1.0 beta is a major attempt to remedy that.

Some things that are noticably absent in the new version are the ProjectModel and Rake Task Helpers. There are other major features that aren’t quite ready yet too, like AsDoc and Continuous Integration support.

As of right now, there is no plan to bring back the Project Model or the Task Helpers, but you can expect AsDoc and CI support in the near future – it will be even sooner if you fork and build them yourself!

Getting back to this new Rakefile, the idea here, is that someone who is new to Ruby and new to Rake, should be able to read a newly generated Sprouts project, and have at least some idea as to how they might modify it. In the past, this was not possible – you would need to investigate quite a lot before you could make sense of what this Rakefile did.

This new Rakefile is obviously much more verbose, but it’s also much more natural and readable.

require 'rubygems'
require 'bundler'
require 'bundler/setup'

require 'rake/clean'
require 'flashsdk'
require 'asunit4'

# Use the Flex Compiler SHell (FCSH)
# ENV['USE_FCSH'] = true

##############################
# Debug

# Compile the debug swf
mxmlc "bin/SomeProject-debug.swf" do |t|
  t.input = "src/SomeProject.as"
  t.debug = true
end

desc "Compile and run the debug swf"
flashplayer :run => "bin/SomeProject-debug.swf"

##############################
# SWC

compc "bin/SomeProject.swc" do |t|
  t.input_class = "SomeProject"
  t.source_path << 'src'
end

desc "Compile the SWC file"
task :swc => 'bin/SomeProject.swc'

##############################
# Test

library :asunit4

# Compile the test swf
mxmlc "bin/SomeProject-test.swf" => :asunit4 do |t|
  t.input = "src/SomeProjectRunner.as"
  t.source_path << 'test'
  t.debug = true
end

desc "Compile and run the test swf"
flashplayer :test => "bin/SomeProject-test.swf"

task :default => :run

I’m going to assume you have some slightly more sophisticated work in your Rakefile. Perhaps you were even using the ProjectModel to set up your source_path?

With the new version, you do this by creating a Plain Old Ruby method, and sending your tasks to it by reference.

It goes a little like this:

##
# This task must be *above* any 
# line that calls it.
def configure_task t
  t.library_path << 'lib/corelib.swc'
  t.source_path << 'lib/your_custom_lib_folder'
end

mxmlc 'bin/SomeProject.swf' do |t|
  configure_task t
  t.input = 'src/SomeProject.as'
end

library :asunit4

mxmlc 'bin/SomeProjectRunner.swf' => :asunit4 do |t|
  configure_task t
  t.input = 'src/SomeProjectRunner.as'
end

If you have a more sophisticated Rakefile, and find yourself struggling with the migration, feel free to ask questions on the list.

Project Sprouts Version 1.0 Beta Released!

2010-12-28T00:00:00-08:00

Project Sprouts Version 1.0 Beta Released!

28 Dec 2010 – Luke Bayes

The Thinker

After over 4 years of thinking, rethinking, designing, implementing and reimplementing, I’m elated to announce the immediate availability of the Project Sprouts version 1.0 beta.

Image courtesy of Santhosh Nandakumar and the Creative Commons license.

You can install the beta as follows:

gem install sprout --pre

You can test out the Flash SDK with:

gem install flashsdk --pre

You should receive further instructions in your terminal after installation.

Moar Plz!

This release represents a nearly complete rewrite of Sprouts internals with a focus on testability, extensibility and decoupling. This build sets out to solve – in a general way – many problems associated with building cross platform, distributed tools with Ruby, and along the way, it makes life much easier for those of us that work with ActionScript or Flex. As you dig around and uncover various dark corners, you’re likely to notice areas that could use some improvement. You may even stumble over an error or two. If you see anything at all suspicious (especially full-blown failures), please do let us know.

If you’re working with ActionScript 3.0 or Flex projects, please check out this latest release. This release does not include support for ActionScript 2.0 projects, and unless someone from the community contributes that functionality, it probably isn’t going to get done.

While the new style of Rake tasks should be familiar to anyone using Sprouts 0.7, legacy Rakefiles will not run without modification.

If you’re migrating a legacy Sprouts project, please check out the migration guide.

We are also working hard to completely revamp our documentation using the Yard documentation engine.

We still have a handful of features that need some attention, so if you’ve been meaning to contribute some time to an open-source project, this could be a great opportunity.

This is also the inaugural post to the new Project Sprouts Blog!

Be sure to subscribe to the atom feed.

This blog (and site) was created with Jekyll, and is stored in the gh-pages branch. If you have an article (or correction) that you’d like to contribute, please fork and send me a pull request!

Thanks for your support!

I sincerely hope you enjoy this new release of Sprouts, it is truly so much easier to test and extend and work with. I have high hopes for our growing community in the coming months and years.