Class: Sprout::Specification

Inherits:
Object
  • Object
show all
Defined in:
sprout/lib/sprout/specification.rb

Overview

Sprouts provides us with the ability to distribute source files, precompiled libraries, and remote executables. It does all of this by (ab)using RubyGems.

RubyGems gives us the ability to version-manage, and distribute arbitrary text and binary payloads.

In order to support Flash development, we have one major problem that RubyGems does not solve for us. This is the fact that many elements of our executable chain are not open-source, and we do not have the rights to directly distribute them.

This restriction means that many of our tools and dependencies cannot be packaged and distributed directly within a RubyGem (or from any server other than Adobe's as a matter of fact).

In order to overcome this restriction, we have introduced a Sprout::Specification. This is a regular Ruby file with regular Ruby code in it. The main idea behind this file, is that it needs to be given a name and available in your load path.

Whenever a rake build task (Sprout::Executable) or library task, (Sprout::Library) is encountered, it will call Sprout::Executable.load or Sprout::Library.load (respectively).

These methods will attempt to require the provided specification and - if it's in your load path - the specification will be loaded, and any relevant file targets will be returned.

There are many ways to get Ruby code into your load path. One of the easiest to package it up in a RubyGem and configure the require_paths parameter of your Gem::Specification.

docs.rubygems.org/read/chapter/20#require_paths

To learn more about packaging RubyGems:

docs.rubygems.org/read/chapter/20#page85 rubygems.rubyforge.org/rdoc/Gem/Specification.html

To learn more about published RubyGems:

rubygems.org/pages/gem_docs

To package a SWC library into a Sprout RubyGem, you would create a file (usually) named [project_name.spec] in the root of the project.

This is your Gem::Specification.

You would also create a file named [projet_name.rb] and put that into the root of the project or some other folder that you have added to the Gem::Specification.require_paths parameter.

Example: Include a file directly in the RubyGem

In the case of AsUnit, this file would be named asunit4.rb and it's contents are as follows:

:include:../../test/fixtures/specification/asunit4.rb

Example: Refer to files that are not in the RubyGem

For projects like the Flex SDK, we can't distribute many of the required files, so we can refer to these files in our Sprout::Specification as remote_file_targets.

:include:../../test/fixtures/specification/flex4sdk.rb

Example: Create custom downloads for each supported platform

For projects like the Flash Player itself, we need to refer to different downloadable content for each supported platform.

:include:../../test/fixtures/specification/flashplayer.rb

Packaging and Sharing

Public RubyGems are hosted at rubygems.org.

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Specification) initialize {|_self| ... }

Create a new Sprout::Specification.

This method will yield the new Sprout::Specification to the provided block, and delegate most configuration parameters to a Gem::Specification.

To learn more about what parameters are available and/or required, please check out RubyGems documentation for their Gem::Specification.

Yields:

  • (_self)

Yield Parameters:



99
100
101
102
103
104
# File 'sprout/lib/sprout/specification.rb', line 99

def initialize
  filename   = Sprout.file_from_caller caller.first
  @load_path = File.dirname filename
  @name      = File.basename(filename).gsub('.rb', '')
  yield self if block_given?
end

Instance Attribute Details

- (Object) file_targets (readonly)

Returns the value of attribute file_targets



87
88
89
# File 'sprout/lib/sprout/specification.rb', line 87

def file_targets
  @file_targets
end

- (Object) load_path (readonly)

Returns the value of attribute load_path



88
89
90
# File 'sprout/lib/sprout/specification.rb', line 88

def load_path
  @load_path
end

- (Object) name

Returns the value of attribute name



84
85
86
# File 'sprout/lib/sprout/specification.rb', line 84

def name
  @name
end

- (Object) version

Returns the value of attribute version



85
86
87
# File 'sprout/lib/sprout/specification.rb', line 85

def version
  @version
end

Instance Method Details

- (Object) add_file_target(&block)

Add a file to the RubyGem itself. This is a great way to package smallish libraries in either source or already-packaged form. For example, one might add a SWC to a RubyGem library.

Each time this method is called, a new Sprout::FileTarget instance will be yielded to the provided block, and added to a collection for packaging.

Sprout::Specification.new do |s|
   ...
   s.add_file_target do |t|
      t.platform = :universal
      t.add_executable :asdoc, 'bin/asdoc'
   end
end


156
157
158
159
# File 'sprout/lib/sprout/specification.rb', line 156

def add_file_target &block
  target = FileTarget.new
  configure_target target, &block
end

- (Object) add_remote_file_target(&block)

Add a remote file target to this RubyGem so that when it is loaded, Sprouts will go fetch this file from the network.

Each time this method is called, a new Sprout::RemoteFiletarget instance will be yielded to the provided block and resolved after the block completes.

After this block is evaluated, Sprouts will first check the collection of env_names to see if the expected paths are available. If a valid env_name is found, Sprouts will return the path to the requested executable from the environment variable.

If no env_names are set, or the requested executable is not found within any that are identified, Sprouts will check to see if the archive has already been unpacked into the expected location:

#{SPROUT_HOME}/cache/#{SPROUT_VERSION}/flex4sdk/#{md5}/4.0.pre

If the archive been unpacked, Sprouts will return the path to the requested executable.

If the archive has not been unpacked, Sprouts will check to see if the archive has been downloaded to:

#{SPROUT_HOME}/cache/#{SPROUT_VERSION}/flex4sdk/#{md5}.zip

If the archive has been downloaded, it will be unpacked and the path to the requested executable will be returned.

If the archive has not been downloaded, it will be downloaded, unpacked and the path to the requested executable will be returned.



137
138
139
140
# File 'sprout/lib/sprout/specification.rb', line 137

def add_remote_file_target &block
  target = RemoteFileTarget.new
  configure_target target, &block
end