documentation for Cake and Cakefiles

jaredp · Feb 21, 2010 · 07513ba · 07513ba
1 parent aded80c
commit 07513ba
Show file tree

Hide file tree

Showing 7 changed files with 127 additions and 79 deletions.
diff --git a/bin/cake b/bin/cake
@@ -2,7 +2,6 @@
 
 process.mixin(require('sys'));
 
-require.paths.unshift('/usr/local/lib/coffee-script/lib');
 require.paths.unshift('./lib');
 
 require('cake').run();
diff --git a/bin/coffee b/bin/coffee
@@ -2,7 +2,6 @@
 
 process.mixin(require('sys'));
 
-require.paths.unshift('/usr/local/lib/coffee-script/lib');
 require.paths.unshift('./lib');
 
 require('command_line').run();
diff --git a/documentation/coffee/cake_tasks.coffee b/documentation/coffee/cake_tasks.coffee
@@ -0,0 +1,5 @@
+process.mixin require 'assert'
+
+task 'test', 'run each of the unit tests', ->
+ for test in test_files
+ fs.readFile test, (err, code) -> eval coffee.compile code
diff --git a/documentation/css/docs.css b/documentation/css/docs.css
@@ -31,7 +31,7 @@ b.header {
  font-size: 16px;
 }
 li {
- margin-bottom: 7px;
+ margin-bottom: 10px;
 }
 table {
  margin: 16px 0 0 13px; padding: 0;

diff --git a/documentation/index.html.erb b/documentation/index.html.erb
@@ -59,6 +59,7 @@
  <a href="#try">Try/Catch/Finally</a>
  <a href="#comparisons">Chained Comparisons</a>
  <a href="#strings">Multiline Strings and Heredocs</a>
+ <a href="#cake">Cake, and Cakefiles</a>
  <a href="#resources">Resources</a>
  <a href="#change_log">Change Log</a>
  </div>
@@ -140,19 +141,19 @@ alert reverse '!tpircseeffoC'</textarea>
  The CoffeeScript compiler is written in pure CoffeeScript, and is available
  as a <a href="https://nodejs.org/">Node.js</a> utility. The core compiler however,
  does not depend on Node, and can be run in other server-side-JavaScript environments,
- or in the browser (see "Try CoffeeScript", above). 
+ or in the browser (see "Try CoffeeScript", above).
  </p>
- 
+
  <p>
- To install, either clone the 
- <a href="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/jashkenas/coffee-script">source repository</a>, 
+ To install, either clone the
+ <a href="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/jashkenas/coffee-script">source repository</a>,
  or download the latest
- release: <a href="https://github.com/jashkenas/coffee-script/tarball/0.5.0">0.5.0</a>. 
+ release: <a href="https://github.com/jashkenas/coffee-script/tarball/0.5.0">0.5.0</a>.
  Then, from within the <tt>coffee-script</tt> directory, run:
  </p>
 
  <pre>
-bin/cake install</pre>
+sudo bin/cake install</pre>
 
  <p>
  Installing the gem provides the <tt>coffee</tt> command, which can
@@ -201,8 +202,8 @@ bin/cake install</pre>
  <tr>
  <td><code>-l, --lint</code></td>
  <td>
- If the <tt>jsl</tt> 
- (<a href="https://www.javascriptlint.com/">JavaScript Lint</a>) 
+ If the <tt>jsl</tt>
+ (<a href="https://www.javascriptlint.com/">JavaScript Lint</a>)
  command is installed, use it
  to check the compilation of a CoffeeScript file. (Handy in
  conjunction with <tt>--watch</tt>)
@@ -270,11 +271,11 @@ coffee --print app/scripts/*.coffee > concatenation.js</pre>
  the left, and the direct compilation into JavaScript is on the right.
  </i>
  </p>
- 
+
  <p>
  <i>
  Many of the examples can be run (where it makes sense) by pressing the "run"
- button towards the bottom right. You can also paste examples into 
+ button towards the bottom right. You can also paste examples into
  "Try CoffeeScript" in the toolbar, and play with them from there.
  </i>
  <p>
@@ -310,7 +311,7 @@ coffee --print app/scripts/*.coffee > concatenation.js</pre>
  </p>
  <%= code_for('functions', 'cube(5)') %>
  <p>
- If you'd like to assign a function literal to a variable, but not have 
+ If you'd like to assign a function literal to a variable, but not have
  it be named, just wrap the function definition in parentheses:
  <tt>((x) -> x * x)</tt>
  </p>
@@ -690,6 +691,27 @@ coffee --print app/scripts/*.coffee > concatenation.js</pre>
  </p>
  <%= code_for('heredocs') %>
 
+ <h2>
+ <span id="cake" class="bookmark"></span>
+ Cake, and Cakefiles
+ </h2>
+
+ <p>
+ CoffeeScript includes a simple build system similar to Make and Rake. Naturally,
+ it's called Cake, and is used for the build and test tasks for the CoffeeScript
+ language itself. Tasks are defined in a file named <tt>Cakefile</tt>, and
+ can be invoked by running <tt>cake taskname</tt> from within the directory.
+ To print a list of all the tasks, just run <tt>cake</tt>.
+ </p>
+
+ <p>
+ Task definitions are written in CoffeeScript, so you can put arbitrary code
+ in your Cakefile. Define a task with a name, a long description, and the
+ function to invoke when the task is run. Here's a hypothetical task
+ that uses the Node.js API.
+ </p>
+ <%= code_for('cake_tasks') %>
+
  <h2>
  <span id="resources" class="bookmark"></span>
  Resources
@@ -698,12 +720,11 @@ coffee --print app/scripts/*.coffee > concatenation.js</pre>
  <ul>
  <li>
  <a href="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/jashkenas/coffee-script/">Source Code</a><br />
- Use <tt>bin/coffee</tt> to test your changes,
- <tt>rake test</tt> to run the test suite,
- <tt>rake build:parser</tt> to regenerate the Racc parser if you're
- working on the grammar,
- and <tt>rake gem:install</tt> to
- create and install a custom version of the gem.
+ Use <tt>bin/coffee</tt> to test your changes,<br />
+ <tt>bin/cake test</tt> to run the test suite,<br />
+ <tt>bin/cake build</tt> to rebuild the CoffeeScript compiler, and <br />
+ <tt>bin/cake build:parser</tt> to regenerate the Jison parser if you're
+ working on the grammar.
  </li>
  <li>
  <a href="https://github.com/jashkenas/coffee-script/issues">CoffeeScript Issues</a><br />
@@ -712,33 +733,19 @@ coffee --print app/scripts/*.coffee > concatenation.js</pre>
  <li>
  If you'd like to chat, stop by <tt>#coffeescript</tt> on Freenode.
  </li>
- <!--
- <li>
- <a href="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/mattly/rack-coffee">rack-coffee</a><br />
- Rack middleware for serving CoffeeScripts as JavaScript directly to
- the browser, without having to compile them first. From
- <a href="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/mattly">Matt Lyon</a>.
- </li>
- <li>
- <a href="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/jnicklas/bistro_car">BistroCar</a><br />
- A Rails plugin by
- <a href="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/jnicklas">Jonas Nicklas</a>
- that includes CoffeeScript helpers,
- bundling and minification.
- </li>
- <li>
- <a href="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/inem/coffee-haml-filter">coffee-haml-filter</a><br />
- A custom <a href="https://haml-lang.com/">HAML</a> filter, by
- <a href="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/inem">Ivan Nemytchenko</a>, that embeds
- snippets of CoffeeScript within your HAML templates.
- </li>
- -->
  </ul>
 
  <h2>
  <span id="change_log" class="bookmark"></span>
  Change Log
  </h2>
+
+ <p>
+ <b class="header" style="margin-top: 20px;">0.5.0</b>
+ CoffeeScript 0.5.0 is a major update, and the first release that removes
+ the Ruby compiler entirely, in favor of a compiler written entirely in
+ CoffeeScript, and self-hosting.
+ </p>
 
  <p>
  <b class="header" style="margin-top: 20px;">0.3.2</b>

diff --git a/documentation/js/cake_tasks.js b/documentation/js/cake_tasks.js
@@ -0,0 +1,14 @@
+(function(){
+ process.mixin(require('assert'));
+ task('test', 'run each of the unit tests', function() {
+ var _a, _b, _c, test;
+ _a = []; _b = test_files;
+ for (_c = 0; _c < _b.length; _c++) {
+ test = _b[_c];
+ _a.push(fs.readFile(test, function(err, code) {
+ return eval(coffee.compile(code));
+ }));
+ }
+ return _a;
+ });
+})();
diff --git a/index.html b/index.html
@@ -45,6 +45,7 @@
  <a href="#try">Try/Catch/Finally</a>
  <a href="#comparisons">Chained Comparisons</a>
  <a href="#strings">Multiline Strings and Heredocs</a>
+ <a href="#cake">Cake, and Cakefiles</a>
  <a href="#resources">Resources</a>
  <a href="#change_log">Change Log</a>
  </div>
@@ -237,19 +238,19 @@ <h2>
  The CoffeeScript compiler is written in pure CoffeeScript, and is available
  as a <a href="https://nodejs.org/">Node.js</a> utility. The core compiler however,
  does not depend on Node, and can be run in other server-side-JavaScript environments,
- or in the browser (see "Try CoffeeScript", above). 
+ or in the browser (see "Try CoffeeScript", above).
  </p>
- 
+
  <p>
- To install, either clone the 
- <a href="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/jashkenas/coffee-script">source repository</a>, 
+ To install, either clone the
+ <a href="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/jashkenas/coffee-script">source repository</a>,
  or download the latest
- release: <a href="https://github.com/jashkenas/coffee-script/tarball/0.5.0">0.5.0</a>. 
+ release: <a href="https://github.com/jashkenas/coffee-script/tarball/0.5.0">0.5.0</a>.
  Then, from within the <tt>coffee-script</tt> directory, run:
  </p>
 
  <pre>
-bin/cake install</pre>
+sudo bin/cake install</pre>
 
  <p>
  Installing the gem provides the <tt>coffee</tt> command, which can
@@ -298,8 +299,8 @@ <h2>
  <tr>
  <td><code>-l, --lint</code></td>
  <td>
- If the <tt>jsl</tt> 
- (<a href="https://www.javascriptlint.com/">JavaScript Lint</a>) 
+ If the <tt>jsl</tt>
+ (<a href="https://www.javascriptlint.com/">JavaScript Lint</a>)
  command is installed, use it
  to check the compilation of a CoffeeScript file. (Handy in
  conjunction with <tt>--watch</tt>)
@@ -367,11 +368,11 @@ <h2>
  the left, and the direct compilation into JavaScript is on the right.
  </i>
  </p>
- 
+
  <p>
  <i>
  Many of the examples can be run (where it makes sense) by pressing the "run"
- button towards the bottom right. You can also paste examples into 
+ button towards the bottom right. You can also paste examples into
  "Try CoffeeScript" in the toolbar, and play with them from there.
  </i>
  <p>
@@ -423,7 +424,7 @@ <h2>
 };
 ;alert(cube(5));'>run: cube(5)</button><br class='clear' /></div>
  <p>
- If you'd like to assign a function literal to a variable, but not have 
+ If you'd like to assign a function literal to a variable, but not have
  it be named, just wrap the function definition in parentheses:
  <tt>((x) -> x * x)</tt>
  </p>
@@ -1551,6 +1552,44 @@ <h2>
 <span class="String"> <span class="String">'''</span></span>
 </pre><pre class="idle"><span class="Storage">var</span> html;
 html <span class="Keyword">=</span> <span class="String"><span class="String">&quot;</span>&lt;strong&gt;<span class="UserDefinedConstant">\n</span> cup of coffeescript<span class="UserDefinedConstant">\n</span>&lt;/strong&gt;<span class="String">&quot;</span></span>;
+</pre><br class='clear' /></div>
+
+ <h2>
+ <span id="cake" class="bookmark"></span>
+ Cake, and Cakefiles
+ </h2>
+
+ <p>
+ CoffeeScript includes a simple build system similar to Make and Rake. Naturally,
+ it's called Cake, and is used for the build and test tasks for the CoffeeScript
+ language itself. Tasks are defined in a file named <tt>Cakefile</tt>, and
+ can be invoked by running <tt>cake taskname</tt> from within the directory.
+ To print a list of all the tasks, just run <tt>cake</tt>.
+ </p>
+
+ <p>
+ Task definitions are written in CoffeeScript, so you can put arbitrary code
+ in your Cakefile. Define a task with a name, a long description, and the
+ function to invoke when the task is run. Here's a hypothetical task
+ that uses the Node.js API.
+ </p>
+ <div class='code'><pre class="idle">process.mixin require <span class="String"><span class="String">'</span>assert<span class="String">'</span></span>
+
+task <span class="String"><span class="String">'</span>test<span class="String">'</span></span>, <span class="String"><span class="String">'</span>run each of the unit tests<span class="String">'</span></span>, <span class="Storage">-&gt;</span>
+ <span class="Keyword">for</span> test <span class="Keyword">in</span> test_files
+ fs.readFile test, <span class="FunctionArgument">(</span><span class="FunctionArgument">err, code</span><span class="FunctionArgument">)</span> <span class="Storage">-&gt;</span> eval coffee.compile code
+</pre><pre class="idle">process.mixin(require(<span class="String"><span class="String">'</span>assert<span class="String">'</span></span>));
+task(<span class="String"><span class="String">'</span>test<span class="String">'</span></span>, <span class="String"><span class="String">'</span>run each of the unit tests<span class="String">'</span></span>, <span class="Storage">function</span>() {
+ <span class="Storage">var</span> _a, _b, _c, test;
+ _a <span class="Keyword">=</span> []; _b <span class="Keyword">=</span> test_files;
+ <span class="Keyword">for</span> (_c <span class="Keyword">=</span> <span class="Number">0</span>; _c <span class="Keyword">&lt;</span> _b.<span class="LibraryConstant">length</span>; _c<span class="Keyword">++</span>) {
+ test <span class="Keyword">=</span> _b[_c];
+ _a.<span class="LibraryFunction">push</span>(fs.readFile(test, <span class="Storage">function</span>(err, code) {
+ <span class="Keyword">return</span> <span class="LibraryFunction">eval</span>(coffee.<span class="LibraryFunction">compile</span>(code));
+ }));
+ }
+ <span class="Keyword">return</span> _a;
+});
 </pre><br class='clear' /></div>
 
  <h2>
@@ -1561,12 +1600,11 @@ <h2>
  <ul>
  <li>
  <a href="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/jashkenas/coffee-script/">Source Code</a><br />
- Use <tt>bin/coffee</tt> to test your changes,
- <tt>rake test</tt> to run the test suite,
- <tt>rake build:parser</tt> to regenerate the Racc parser if you're
- working on the grammar,
- and <tt>rake gem:install</tt> to
- create and install a custom version of the gem.
+ Use <tt>bin/coffee</tt> to test your changes,<br />
+ <tt>bin/cake test</tt> to run the test suite,<br />
+ <tt>bin/cake build</tt> to rebuild the CoffeeScript compiler, and <br />
+ <tt>bin/cake build:parser</tt> to regenerate the Jison parser if you're
+ working on the grammar.
  </li>
  <li>
  <a href="https://github.com/jashkenas/coffee-script/issues">CoffeeScript Issues</a><br />
@@ -1575,33 +1613,19 @@ <h2>
  <li>
  If you'd like to chat, stop by <tt>#coffeescript</tt> on Freenode.
  </li>
- <!--
- <li>
- <a href="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/mattly/rack-coffee">rack-coffee</a><br />
- Rack middleware for serving CoffeeScripts as JavaScript directly to
- the browser, without having to compile them first. From
- <a href="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/mattly">Matt Lyon</a>.
- </li>
- <li>
- <a href="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/jnicklas/bistro_car">BistroCar</a><br />
- A Rails plugin by
- <a href="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/jnicklas">Jonas Nicklas</a>
- that includes CoffeeScript helpers,
- bundling and minification.
- </li>
- <li>
- <a href="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/inem/coffee-haml-filter">coffee-haml-filter</a><br />
- A custom <a href="https://haml-lang.com/">HAML</a> filter, by
- <a href="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/inem">Ivan Nemytchenko</a>, that embeds
- snippets of CoffeeScript within your HAML templates.
- </li>
- -->
  </ul>
 
  <h2>
  <span id="change_log" class="bookmark"></span>
  Change Log
  </h2>
+
+ <p>
+ <b class="header" style="margin-top: 20px;">0.5.0</b>
+ CoffeeScript 0.5.0 is a major update, and the first release that removes
+ the Ruby compiler entirely, in favor of a compiler written entirely in
+ CoffeeScript, and self-hosting.
+ </p>
 
  <p>
  <b class="header" style="margin-top: 20px;">0.3.2</b>