jake 1.0.1 → 1.1.0

data/History.txt

@@ -1,3 +1,8 @@
+=== 1.1.0 / 2012-04-07
+
+* Add support for source maps from Packr 3.2
+
+
 === 1.0.0 / 2009-07-06
 
 * A proper test suite is now in place.

data/README.rdoc

@@ -0,0 +1,273 @@
+= Jake
+
+Jake is a command-line line tool for building JavaScript packages from source
+code. It's basically a thin wrapper around {Packr}[http://rubygems.org/gems/packr]
+that lets you easily configure builds for multiple packages with different
+compression settings, using a simple YAML config file.
+
+It supports all the same compression settings as Packr, including generation of
+{source maps}[http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/]
+for your package files. You can also use ERB in your source files to generate
+code.
+
+
+== Usage
+
+To begin with, create a file called <tt>jake.yml</tt> in the root directory of
+your project; you will run the +jake+ command from here. A basic config looks
+like this:
+
+  ---
+  source_directory:     source
+  build_directory:      build
+  
+  layout:               together
+  
+  header:               COPYRIGHT
+  
+  builds:
+    src:
+      minify:           false
+    min:
+      shrink_vars:      true
+      private:          true
+  
+  packages:
+    [ DESCRIBED BELOW ]
+
+* +source_directory+ is the directory relative to <tt>jake.yml</tt> where your
+  source files are, and +build_directory+ is where all the generated build files
+  will be placed.
+* +layout+ describes whether files from separate builds should go in separate
+  directories. For example if you have a package called +foo+, with the above
+  config the +together+ layout will generate <tt>build/foo-src.js</tt> and
+  <tt>build/foo-min.js</tt>, whereas a +layout+ value of +apart+ will generate
+  <tt>build/src/foo.js</tt> and <tt>build/min/foo.js</tt>.
+* +header+ specifies a file whose content should appear at the top of all
+  generated build files. The content of this file will typically be JavaScript
+  comments containing copyright and license information. This content is never
+  minified. The +header+ option may be omitted.
+
+
+=== Build listing
+
+The build listing, given by the +builds+ option in the config file, lists all
+the builds you want to produce for distribution, and what minification settings
+each build should use. JavaScript projects typically distribute both compressed
+and uncompressed copies of their code to suit both production and development
+environments.
+
+You can have as many builds as you like and the names are up to you. I'm using
++src+ and +min+ as readily understood examples. Each build may specify some
+combination of the following options:
+
+* <tt>minify: false</tt> -- Disables minification for this build. This precludes
+  use of further minification options.
+* <tt>shrink_vars: true</tt> -- Tells the minifier to compress local variable
+  names inside functions.
+* <tt>private: true</tt> -- Tells the minifier to obfuscate 'private' variables
+  with numeric replacements. JavaScript convention is that any name beginning
+  with an underscore, e.g. <tt>_foo</tt> or <tt>obj._bar</tt> should be
+  considered private. They are replaced with <tt>_0</tt>, <tt>_1</tt>, etc.
+* <tt>base62: true</tt> -- Produces base-62 encoded minification.
+* <tt>suffix: false</tt> -- Files from this build should not have a suffix if
+  using the +together+ layout, so you get <tt>build/foo.js</tt> rather than
+  <tt>build/foo-src.js</tt>, for example. Only one build may use this option,
+  otherwise file name clashes will occur.
+* <tt>source_map: $build_name</tt> -- Generates a source map for each file in
+  this build, relative to a corresponding file in <tt>$build_name</tt>. For
+  example, a <tt>min</tt> build with <tt>source_map: src</tt> will produce a
+  files <tt>foo-min.js</tt> and <tt>foo-min.js.map</tt> where the source map
+  refers to locations in <tt>foo-src</tt>. You can make the source map relative
+  to the original source code by setting <tt>:source</tt> as the value of
+  <tt>$build_name</tt>.
+
+
+=== Package listing
+
+The package listing, given under the +packages+ config option, describes the
+packages you want to produce and which source files are used to generate them. A
+package is named using the path under +build_directory+ where it should be
+generated, e.g. <tt>foo</tt> or <tt>ext/awesome</tt> (you may omit the
+<tt>.js</tt> extension). Each package lists one or more source files used to
+build it, and may optionally list some extra options as described below.
+
+For the examples, assume the source directory is +src+ and the build directory
+is +dist+. This package uses a single source file <tt>src/foo.js</tt> and
+generates <tt>dist/foo_dist.js</tt>:
+
+  foo_dist:     foo
+
+This package generates <tt>dist/bar.js</tt> from <tt>src/bar1.js</tt> and
+<tt>src/bar2.js</tt>
+
+  bar:
+    - bar1
+    - bar2
+
+This generates a package at <tt>dist/sub/dir.js</tt> from <tt>src/path/file.js</tt>
+and <tt>src/path/baz.js</tt>:
+
+  sub/dir:
+    - path/file
+    - path/baz
+
+If all the source files for a package live in the same subdirectory, you can
+tidy things up using the +directory+ option. If you use any package-level
+options, you must list the files under the +files+ option (the above examples
+are just syntactic shorthands for this):
+
+  sub/dir:
+    directory:  path
+    files:
+      - file
+      - baz
+
+The full list of package options is as follows:
+
+* +files+ - lists the source files used to build the package. Shorthand may be
+  used as above if no further options are used.
+* +extends+ - name of another package from which to inherit configuration.
+  Useful for making a package that includes all the files from another, plus a
+  few extras.
+* +directory+ - the directory under +source_directory+ in which to find source
+  files. May be omitted.
+* +header+ - a custom header file to use on this package. Overrides the root
+  +header+ option. May be omitted.
+* +packer+ - lists minification settings that override settings being used for
+  the current build. If a build listed above uses <tt>minify: false</tt>, this
+  takes precedence over package-specific instructions. Typically used to
+  override options for the minified build.
+* +meta+ - should be a YAML dictionary containing arbitrary data useful to
+  user-defined build events. May be omitted. See 'Event hooks' below.
+
+For example, here's a package listing that uses all the options:
+
+  packages:
+    foo_dist:         foo
+    
+    bar:
+      - bar1
+      - bar2
+    
+    sub/whizz:
+      extends:        foo_dist
+      directory:      path
+      header:         CUSTOM_HEADER
+      files:
+        - file1
+        - file2
+    
+    last:
+      packer:
+        private:      false
+      meta:
+        requires:
+          - jQuery
+          - GMap2
+      files:
+        - one_file
+        - another_file
+      
+In conjunction with the build options listed above, this matches the following
+project layout (omitting build name suffixes for brevity):
+
+  - build/
+      - sub/
+          - whizz.js
+      - bar.js
+      - foo_dist.js
+      - last.js
+  - source/
+      - path/
+          - CUSTOM_HEADER
+          - file1.js
+          - file2.js
+      - another_file.js
+      - bar1.js
+      - bar2.js
+      - foo.js
+      - one_file.js
+  - COPYRIGHT
+  - jake.yml
+
+
+=== Using ERB in source files
+
+Jake lets you use Ruby's ERB templating system within your source code so you
+can insert values generated from Ruby functions. To use this feature, you need
+to create a file called <tt>Jakefile</tt> in the root of your project. This
+contains helper functions that are called in your source code to inject data.
+
+For example, say you want to extract a version number from your version control
+system and inject it into your code along with the build name. Your source code
+should contain something like this:
+
+  MyJavaScriptLib.VERSION = "<%= version %>-<%= build %>";
+
+And your <tt>Jakefile</tt> should contain a helper called +version+:
+
+  jake_helper :version do
+    # extract version number from svn, git, whatever
+    # e.g. return '1.0'
+  end
+
+Jake has a built-in helper called +build+ that returns the current build name.
+When built, the output would contain the following:
+
+  MyJavaScriptLib.VERSION = "1.0-src";    // or "1.0-min" for the 'min' build
+
+
+=== Event hooks
+
+The +Jakefile+ may also define event hooks that are fired during a build when
+interesting things happen. This allows you to extend your build process using
+configuration data from Jake. All event callbacks are passed a +Build+ object as
+the first argument, and may receive additional arguments depending on the
+event type. We currently have two events:
+
++file_created+ is fired whenever a new build file is created. The callback is
+passed the +Buildable+ package object, the current build type (+src+ or +min+
+using the above examples), and the full path to the newly created file. The
+package object may contain metadata (set using the +meta+ option, see above)
+which you can use for further code generation.
+
++build_complete+ is fired after a build has finished running, that is after all
+sets of minification options have been run. At this point you can use any
+metadata you've gathered to generate more code, copy files to your distribution
+directory, etc.
+
+  $register = {}
+  
+  jake_hook :file_created do |build, pkg, build_type, path|
+    $register[path] = pkg.meta
+  end
+  
+  jake_hook :build_complete do |build|
+    FileUtils.cp 'README', build.build_directory + '/README'
+    # generate code from $register
+  end
+
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2008-2012 James Coglan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the 'Software'), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/bin/jake

@@ -1,7 +1,10 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+
+$VERBOSE = nil
+
 require 'rubygems'
 require 'oyster'
-require File.dirname(__FILE__) + '/../lib/jake'
+require File.expand_path('../../lib/jake', __FILE__)
 
 spec = Oyster.spec do
   name    'jake -- automated build tool for JavaScript projects'
@@ -11,7 +14,7 @@ spec = Oyster.spec do
   EOS
   
   description <<-EOS
-  Jake builds JavaScript library packages from source code using PackR and
+  Jake builds JavaScript library packages from source code using Packr and
   ERB. Use --force to force a rebuild of files deemed up-to-date. DIR specifies
   where to find the jake.yml configuration file, by default this is set to the
   current working directory.
@@ -20,7 +23,7 @@ spec = Oyster.spec do
   flag :force, :default => false,
   :desc => 'Force a rebuild even if files are up-to-date'
   
-  author 'James Coglan <jcoglan@googlemail.com>'
+  author 'James Coglan <jcoglan@gmail.com>'
 end
 
 begin; opts = spec.parse
@@ -34,11 +37,11 @@ build = Jake::Build.new(dir, opts)
 
 build.on(:file_created) do |build, pkg, build_type, path|
   size = (File.size(path) / 1024.0).ceil
-  puts LOG_FORMAT % [pkg.name, build_type, path.gsub(dir, ''), "#{ size } kB"]
+  puts LOG_FORMAT % [pkg.name, build_type, path.gsub(dir + '/', ''), "#{ size } kB"]
 end
 
 build.on(:file_not_changed) do |build, pkg, build_type, path|
-  puts LOG_FORMAT % [pkg.name, build_type, path.gsub(dir, ''), 'UP-TO-DATE']
+  puts LOG_FORMAT % [pkg.name, build_type, path.gsub(dir + '/', ''), '--']
 end
 
 build.run!

data/lib/jake.rb

@@ -1,8 +1,6 @@
 require 'erb'
 require 'fileutils'
-require 'observer'
 require 'yaml'
-require 'rubygems'
 require 'packr'
 require 'eventful'
 
@@ -12,41 +10,41 @@ rescue LoadError
 end
 
 module Jake
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
   
   CONFIG_FILE = 'jake.yml'
   HELPER_FILE = 'Jakefile'
   EXTENSION   = '.js'
   
-  # Runs a build in the given directory. The directory must contain a jake.yml
-  # file, and may contain a Jakefile. See README for example YAML configurations.
+  dir = File.expand_path('../jake', __FILE__)
+  autoload :Build,     dir + '/build'
+  autoload :Buildable, dir + '/buildable'
+  autoload :Bundle,    dir + '/bundle'
+  autoload :Helper,    dir + '/helper'
+  autoload :Package,   dir + '/package'
+  
   def self.build!(path, options = {})
     build = Build.new(path, options)
     build.run!
   end
   
-  # Removes all registered build event hooks.
   def self.clear_hooks!
     Build.delete_observers
   end
   
-  # Returns a path made by joining the given pieces and removing unnecessary
-  # /. sections using expand_path.
   def self.path(*parts)
     parts = parts.compact.map { |p| p.to_s }
     File.expand_path(File.join(*parts))
   end
   
-  # Returns the contents of the given path, which may be missing a .js extension.
   def self.read(path)
     path = File.expand_path(path)
-    [path, "#{path}#{EXTENSION}"].each do |p|
-      return File.read(p).strip if File.file?(p)
+    [path, "#{path}#{EXTENSION}"].each do |file|
+      return File.read(file) if File.file?(file)
     end
     return nil
   end
   
-  # Returns a copy of the given hash with the keys cast to symbols.
   def self.symbolize_hash(hash, deep = true)
     hash.inject({}) do |output, (key, value)|
       value = Jake.symbolize_hash(value) if deep and value.is_a?(Hash)
@@ -55,18 +53,11 @@ module Jake
     end
   end
   
-  # Returns either an Erubis or ERB instance, depending on what's available.
   def self.erb(template)
     defined?(Erubis) ? Erubis::Eruby.new(template) : ERB.new(template)
   end
-  
-end
-
-%w(helper build buildable package bundle).each do |file|
-  require File.dirname(__FILE__) + '/jake/' + file
 end
 
-# Adds a helper method that can be called from ERB.
 def jake_helper(name, &block)
   Jake::Helper.class_eval do
     define_method(name, &block)
@@ -74,7 +65,6 @@ def jake_helper(name, &block)
 end
 alias :jake :jake_helper
 
-# Registers an event listener that will fire whenever a build is run.
 def jake_hook(type, &block)
   Jake::Build.on(type, &block)
 end

data/lib/jake/build.rb

@@ -1,18 +1,11 @@
 module Jake
-  # A +Build+ encapsulates a single instance of running <tt>Jake.build!</tt>. It
-  # is responsible for running the build and provides access to any configuration
-  # data used to set up the build.
   class Build
     include Eventful
+    include Enumerable
+    attr_reader :config_files, :helper
     
     DEFAULT_LAYOUT = 'together'
     
-    include Enumerable
-    attr_reader :helper
-    
-    # Builds are initialized using a directory in which to run the build, and an
-    # options hash. Options are passed through to helper methods in the +options+
-    # object.
     def initialize(dir, options = {})
       @dir    = File.expand_path(dir)
       @helper = Helper.new(options)
@@ -21,10 +14,14 @@ module Jake
       path    = Jake.path(dir, CONFIG_FILE)
       yaml    = File.read(path)
       
+      @config_files = [path]
       @config = Jake.symbolize_hash( YAML.load(Jake.erb(yaml).result(@helper.scope)) )
       
       helpers = Jake.path(dir, HELPER_FILE)
-      load helpers if File.file?(helpers)
+      if File.file?(helpers)
+        load helpers
+        @config_files << helpers
+      end
       
       @builds = @config[:builds] || {:src => false, :min => @config[:packer]}
       
@@ -39,22 +36,18 @@ module Jake
       end
     end
     
-    # Yields to the block for each build in the group.
     def each(&block)
       @builds.each(&block)
     end
     
-    # Forces the build to generate new files even if target files appear up-to-date.
     def force!
       @forced = true
     end
     
-    # Returns +true+ iff this is a forced build.
     def forced?
       defined?(@forced)
     end
     
-    # Returns a list of names for all packages in the build.
     def packages
       list = []
       @packages.each { |name, pkg| list << name }
@@ -62,12 +55,10 @@ module Jake
       list
     end
     
-    # Returns the +Buildable+ with the given name.
     def package(name)
       @packages[name.to_sym] || @bundles[name.to_sym]
     end
     
-    # Runs the build, generating new files in +build_directory+.
     def run!
       FileUtils.cd(@dir) do
         @packages.each { |name, pkg| pkg.write! }
@@ -76,44 +67,34 @@ module Jake
       end
     end
     
-    # Returns the path to the build directory, where generated files appear.
     def build_directory
       Jake.path(@dir, @config[:build_directory] || '.')
     end
     alias :build_dir :build_directory
     
-    # Returns the path to the source directory, where source code is read from.
     def source_directory
       Jake.path(@dir, @config[:source_directory] || '.')
     end
     alias :source_dir :source_directory
     
-    # Returns the header string used for the build, or an empty string if no
-    # header file has been set.
     def header
       @config[:header] ?
           Jake.read(Jake.path(source_directory, @config[:header])) :
           ""
     end
     
-    # Returns the minification settings for PackR for the given build name. Each
-    # +Build+ object can build all its packages multiple times with different
-    # minification settings in each run.
     def packer_settings(build_name)
       build = @builds[build_name.to_sym]
       return false unless build
       build[:packer].nil? ? build : build[:packer]
     end
     
-    # Returns +true+ iff filename suffixes based on build name should be added
-    # to generated files for the given build name.
     def use_suffix?(build_name)
       build = @builds[build_name.to_sym]
       return true unless build
       build[:suffix] != false
     end
     
-    # Returns the name of the layout being used, either +together+ or +apart+.
     def layout
       @config[:layout] || DEFAULT_LAYOUT
     end