Permalink
Browse files

Improved documentation. Should probably add inline documentation to B…

…uild and Buildable classes before documenting event hooks.
  • Loading branch information...
1 parent 516d34c commit fca9e451331678704dbe2a1c5c27007d7f8f4ad7 @jcoglan committed Jun 17, 2009
Showing with 238 additions and 114 deletions.
  1. +1 −0 .gitignore
  2. +237 −0 README.rdoc
  3. +0 −114 README.txt
View
@@ -1,2 +1,3 @@
+README.txt
pkg
test/output
View
@@ -0,0 +1,237 @@
+= Jake
+
+* http://github.com/jcoglan/jake
+
+Jake is a command line tool for building JavaScript packages from source
+code. Using simple YAML config files, you can specify any number of build
+files to be generated by concatenating and minifying groups of source files.
+It allows ERB to be used inside source files to generate code, and provides
+event hooks into the build process so you can extend it for your own needs.
+
+
+== Installation
+
+ sudo gem install jake
+
+
+== 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:
+ packer: 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 that 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>packer: 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.
+
+
+=== 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>packer: false</tt>,
+ this takes precedence over package-specific instructions. Typically used
+ to override options for the minified build.
+
+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
+ 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
+
+
+== License
+
+(The MIT License)
+
+Copyright (c) 2008-2009 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.
View
@@ -1,114 +0,0 @@
-= Jake
-
-* http://github.com/jcoglan/jake
-
-== Description
-
-Jake is a tool for building JavaScript library packages from source code. It allows
-builds to be specified using simple YAML files, and provides a command-line tool for
-generating package files. It also allows ERB to be embedded in JavaScript source code
-so that build data or new code can be generated during the build process.
-
-== Features
-
-* Easy automated builds of JavaScript packages with a single command
-* Uses lightweight YAML to specify files and compression options
-* Compression is configurable both globally and per-package
-* Multiple builds with different compression setups
-* Headers such as copyright information can be injected into all build files
-* ERB can be used to inject code at build time using Ruby functions
-
-== Usage
-
-Jake builds are configured using a YAML file and (optionally) a 'Jakefile' containing
-helper methods for use with Jake's ERB features. You place a file called <tt>jake.yml</tt>
-in the root directory of your project (you will run the +jake+ command from this
-directory). If you use a Jakefile, place this in the same directory.
-
-This example <tt>jake.yml</tt> demonstrates the layout of the file:
-
- --
- source_directory: src
- build_directory: dist
- header: COPYRIGHT
- packer:
- shrink_vars: true
- private: true
- base62: true
-
- packages:
- foo: foo
-
- bar:
- - bar_file1
- - bar_file2
-
- baz:
- directory: baz
- header: COPYRIGHT
- packer:
- base62: false
- files:
- - model
- - view
- - controller
-
- bundles:
- my_lib:
- - foo
- - bar
- - baz
-
-This configuration would match a project layed out as follows:
-
- - dist/
- - bar.js
- - baz.js
- - foo.js
- - my_lib.js
- - src/
- - baz/
- - controller.js
- - COPYRIGHT
- - model.js
- - view.js
- - bar_file1.js
- - bar_file2.js
- - foo.js
- - COPYRIGHT
- - jake.yml
-
-== Requirements
-
-* Rubygems
-* Oyster
-* PackR
-
-== Installation
-
-* sudo gem install jake -y
-
-== License
-
-(The MIT License)
-
-Copyright (c) 2008 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.

0 comments on commit fca9e45

Please sign in to comment.