bee 0.1.0

data/README

@@ -0,0 +1,4 @@
+Bee is a simple build tool. It is inspired from Make (for intensive 
+usage of command line to build projects) and Ant (for its build file).
+The result is aimed to keep benefits of both and get rid of their
+defaults (if any :o). Enjoy!

data/bin/bee

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'bee'
+
+Bee.start_command_line

data/bin/beedoc

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'beedoc'
+
+Bee::Doc.start_command_line

data/doc/html/documentation.html

@@ -0,0 +1,444 @@
+<!--
+Copyright 2006 Michel Casabianca <casa@sweetohm.net>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+<p>Bee is a build tool parsing YAML build files. These files can embed
+shell and/or Ruby scripts. It is as fast as Make and its build files are
+far more readable than Ant ones (without the bloated XML syntax ;o).</p>
+
+<h2>Installation</h2>
+
+<p>Bee is a Ruby script, thus an interpreter must be installed on your 
+machine. You can get one for free at 
+<a href="http://www.ruby-lang.org">http://www.ruby-lang.org</a>.</p>
+
+<p>If <a href="http://docs.rubygems.org/">RubyGems</a> is installed on
+your machine, type <code>gem install bee</code> (you might need to have
+administrator privileges to do so).</p>
+
+<p>If you are reluctant to install RubyGems (which is not a good idea),
+you can still install bee the old fashion way: unzip installation
+archive somewhere and put its <i>bin</i> directory in your PATH.</p>
+
+<p>You can test your installation typing <code>bee -h</code>.</p>
+
+<h2>Usage</h2>
+
+<p>Type <code>bee</code> in directory of your build file (which name
+defaults to <i>build.yml</i>). To get help about usage, type 
+<code>bee -h</code>:</p>
+
+<pre class="code"><code>$ bee -h
+Usage: bee [options] [targets]
+-h        Print help about usage and exit.
+-b        Print help about build and exit.
+-t        Write template build file on disk.
+-v        Enable verbose mode.
+-s style  Define style for output (see documentation).
+-f file   Build file to run (defaults to "build.yml").
+targets   Targets to run (default target if omitted).</code></pre>
+
+<p>You can get help about loaded build file (using <code>-f</code>
+option if necessary) typing <code>bee -b</code>:</p>
+
+<pre class="code"><code>$ bee -b
+- Build: "bee"
+  Description: 
+    This build file needs zip command line tool to generate distribution
+    archive.
+- Properties:
+  - api: "/Users/casa/Desktop/bee/build/api"
+  - archive: "bee-beta-1.zip"
+  - base: "/Users/casa/Desktop/bee"
+  - build: "/Users/casa/Desktop/bee/build"
+  - dist: "/Users/casa/Desktop/bee/build/bee"
+  - doc: "/Users/casa/Desktop/bee/build/doc"
+  - files: "README bin"
+  - name: "bee"
+  - src: "/Users/casa/Desktop/bee/bin/*"
+  - syntax_report: "/Users/casa/Desktop/bee/build/syntax.txt"
+  - test: "/Users/casa/Desktop/bee/test"
+  - test_report: "/Users/casa/Desktop/bee/build/tests.txt"
+  - version: "beta-1"
+- Targets:
+  - all: Generate all
+  - api: Generate API documentation
+  - clean: Clean generated files
+  - dist: Generate distribution archive
+  - doc: Generate documentation
+  - syntax: Check syntax of ruby files
+  - syntax-report: Check syntax of ruby files and generate report
+  - test: Run unit tests
+  - test-report: Run unit tests and gerenate report
+- Default: all</code></pre>
+
+<p>This will print help about:</p>
+
+<ul>
+<li>Build file.</li>
+<li>Defined properties.</li>
+<li>Build targets.</li>
+<li>Default target.</li>
+</ul>
+
+<p>The <code>-t</code> option writes a template build file. This is
+convenient to quickly write a new build file editing this example.
+You can use option <code>-t file</code> to write template to another
+location than <i>build.yml</i> in current directory. Note that bee
+will refuse to overwrite an existing build file with a template.</p>
+
+<p>The <code>-v</code> option enables verbose mode (printing loaded
+build file, executed scripts and build time). Option <code>-s style</code>
+defines a style for output (see above section <i>Defining styles</i>
+for more information). The <code>-f file</code> enables you to load
+an alternate build file. Without this option, bee will look for
+a file named <i>build.yml</i> in current directory.</p>
+
+<h2>Configuration</h2>
+
+<p>bee doesn't load configuration file st startup, but you can set
+command line options in environment variable <code>BEEOPT</code> that
+is appended on command line at startup. For instance, setting:</p>
+
+<pre class="code">BEEOPT="-v"<code></code></pre>
+
+<p>Would always run bee in verbose mode.</p>
+
+<h2>Project files</h2>
+
+<p>Here is a sample project file (simplified version to generate bee
+distribution archive):</p>
+
+<pre class="code"><code># Build info
+- build: bee
+  default: all
+  description: |
+    This build file needs zip command line tool to generate distribution
+    archive.
+
+# Build properties
+- properties:
+  - name: bee
+  - version: "beta-1"
+  - test: "test"
+  - build: "#{base}/build"
+  - dist: "#{build}/#{name}"
+  - files: "README bin"
+  - archive: "#{name}-#{version}.zip"
+
+# Build targets
+- target: test
+  description: Run unit tests
+  script: 
+  - "testrb #{test}"
+
+- target: dist
+  description: Generate distribution archive
+  depends: test
+  script: |
+    if [ ! -d #{build} ]
+    then 
+      mkdir #{build}
+    fi
+    if [ ! -d #{dist} ]
+    then 
+      mkdir #{dist}
+    fi
+    cp -r #{files} #{dist}
+    rm -rf `find #{dist} -name "CVS"`
+    rm -rf `find #{dist} -name ".??*"`
+    cd #{build}
+    zip -r #{archive} #{name}
+
+- target: clean
+  description: Clean generated files
+  script: |
+    rm -rf #{build}
+    rm -f `find #{base} -name "*~"`
+    rm -f `find #{base} -name ".DS_Store"`
+
+- target: all
+  description: Generate all
+  depends: [clean, dist]</code></pre>
+
+<p>This is a <a href="http://www.yaml.org/">YAML</a> file. In such 
+files, list elements are lines starting with a dash (<i>-</i>
+character) and hash entries are lines made of a key / value pair
+separated with a colon (<i>:</i> character). Thus, you might already
+have noticed that this file is a list of hash which can be:</p>
+
+<h3>Project information</h3>
+
+<p>This is a piece of information that is not mandatory but used 
+while displaying build help. This looks like:</p>
+
+<pre class="code"><code>- build: bee
+  default: all
+  description: |
+    This build file needs zip command line tool to generate distribution
+    archive.</code></pre>
+
+<p>This hash may have following keys:</p>
+
+<ul>
+<li><b>build</b>: for the build name (mandatory).</li>
+<li><b>default</b>: to indicate default target to run (optional). If no
+default target is set, bee will set default as first target declared in
+the build file.</li>
+<li><b>description</b>: build description (optional). This is the place
+to list dependencies for the build (such as <code>zip</code> in this
+example).</li>
+<li><b>context</b>: this is a list of scripts to load at startup in
+the build context. These scripts can define variables and functons
+used in embedded scripts. See section <i>Build Context</i> above for
+more information.</li>
+</ul>
+
+<h3>Build properties</h3>
+
+<p>These are properties used by build file scripts or other properties.
+They can be seen as build file variable declarations:</p>
+
+<pre class="code"><code>- properties:
+  - name: bee
+  - version: "beta-1"
+  - test: "test"
+  - build: "#{base}/build"
+  - dist: "#{build}/#{name}"
+  - files: "README bin"
+  - archive: "#{name}-#{version}.zip"</code></pre>
+
+<p>This entry has a single key <i>properties</i> that contains a list
+of property definitions. Each definition is a Hash with a single key
+which is the property name associated to its value. Properties can
+reference each other using a Ruby syntax <code>#{property}</code>.</p>
+
+<h3>Targets</h3>
+
+<p>A target can be seen as build file functions. A target is defined
+to implement a given goal. For instance, in sample hereafter, target
+named <i>dist</i> generates distribution archive:</p>
+
+<pre class="code">- target: dist
+  description: Generate distribution archive
+  depends: test
+  script: |
+    if [ ! -d #{build} ]
+    then 
+      mkdir #{build}
+    fi
+    if [ ! -d #{dist} ]
+    then 
+      mkdir #{dist}
+    fi
+    cp -r #{files} #{dist}
+    rm -rf `find #{dist} -name "CVS"`
+    rm -rf `find #{dist} -name ".??*"`
+    cd #{build}
+    zip -r #{archive} #{name}<code></code></pre>
+
+<p>A target entry might have following keys:</p>
+
+<ul>
+<li><b>target</b>: the target name (mandatory).</li>
+<li><b>description</b>: description printed in build help (optional).</li>
+<li><b>depends</b>: a list of target's dependencies (optional). This 
+might be a list or a single string. Dependencies are executed before a
+given target.</li>
+<li><b>script</b>: script to run to achive this target (optinal). This is
+a single script or a list of scripts to run. Each script might be a
+shell script or a Ruby script (when prefixed with <code>- rb:</code>).</li>
+</ul>
+
+<p>bee writes executed scripts in verbose mode. For instance, running
+sample script would print on console:</p>
+
+<pre class="code"><code>$ bee
+----------------------------------------------------------------------- clean --
+------------------------------------------------------------------------ test --
+Loaded suite test
+Started
+..
+Finished in 0.003776 seconds.
+
+2 tests, 2 assertions, 0 failures, 0 errors
+------------------------------------------------------------------------ dist --
+  adding: bee/ (stored 0%)
+  adding: bee/bin/ (stored 0%)
+  adding: bee/bin/bee (deflated 73%)
+  adding: bee/bin/beedoc (deflated 69%)
+  adding: bee/README (deflated 30%)
+------------------------------------------------------------------------- all --
+OK</code></pre>
+
+<p>While running in verbose mode, it would output:</p>
+
+<pre class="code">$ bee -v
+Starting build 'build.yml'...
+----------------------------------------------------------------------- clean --
+- rm -rf #{build}
+. rm -f `find #{base} -name "*~"`
+. rm -f `find #{base} -name ".DS_Store"`
+------------------------------------------------------------------------ test --
+- testrb #{test}
+Loaded suite test
+Started
+..
+Finished in 0.003944 seconds.
+
+2 tests, 2 assertions, 0 failures, 0 errors
+------------------------------------------------------------------------ dist --
+- if [ ! -d #{build} ]
+. then 
+.   mkdir #{build}
+. fi
+. if [ ! -d #{dist} ]
+. then 
+.   mkdir #{dist}
+. fi
+. cp -r #{files} #{dist}
+. rm -rf `find #{dist} -name "CVS"`
+. rm -rf `find #{dist} -name ".??*"`
+. cd #{build}
+. zip -r #{archive} #{name}
+  adding: bee/ (stored 0%)
+  adding: bee/bin/ (stored 0%)
+  adding: bee/bin/bee (deflated 73%)
+  adding: bee/bin/beedoc (deflated 69%)
+  adding: bee/README (deflated 30%)
+------------------------------------------------------------------------- all --
+Built in 0.567582 s
+OK<code></code></pre>
+
+<p>First line of a script starts with a dash (<i>-</i> character) while
+following ones start with a dot (<i>.</i> character). In verbose mode,
+bee also prints loaded build file and build time.</p>
+
+<h2>Build Context</h2>
+
+<p>Setting <code>context</code> key in build info entry load a given
+Ruby script in the build context. This context is the place where
+embedded Ruby scripts run (this is similar to the workspace where you
+run code you type in IRB). This is a simple way to load a library you
+will call in your Ruby scripts. Let's say you would like to call function
+<code>say_hello</code> defined in script named <i>hello.rb</i>:</p>
+
+<pre class="code"><code>def say_hello(who)
+  puts "Hello #{who}!"
+end</code></pre>
+
+<p>You would load it in context with following build file: </p>
+
+<pre class="code"><code>- build: hello
+  context: hello.rb
+
+- properties:
+  - world: "World"
+
+- target: hello
+  script:
+  - rb: "say_hello(world)"</code></pre>
+
+<p>The contex path is relative to the build file. Furthermore, you can
+load more than one file in your context, using a list:</p>
+
+<pre class="code"><code>- build: hello
+  context: [foo.rb, bar.rb]</code></pre>
+
+<h2>Defining Style</h2>
+
+<p>You can define a style using the <code>-s syle</code> option. This 
+is a way to colorize output on console using ANSI colors for Unix
+terminals. For instance, on a Unix box, running bee with option
+<code>-s lc:,tf:yellow,ts:underscore,ss:bright,sf:green,es:bright,ef:red,kf:blue</code>
+would output:</p>
+
+<center><img src="style.png"></center>
+
+<p>Styles are defined as coma separated key/value pairs. Keys are the
+following:</p>
+
+<table>
+<tr>
+<th>Key</th>
+<th>Description</th>
+</tr>
+<tr>
+<td><b>lc</b></td>
+<td>Character for target title (defaults to dash <i>-</i>). To set space,
+set to an empty value, such as: <code>...,lc:,...</code> as there should
+not be spaces in style option (this would break command line parsing).</td>
+</tr>
+<tr>
+<td><b>ll</b></td>
+<td>Line length. If not set, will try to determine it calling IOCTL
+function. If this call fails, will set line length to <i>80</i>
+characters.</td>
+</tr>
+<tr>
+<td><b>ts</b></td>
+<td>Target style.</td>
+</tr>
+<tr>
+<td><b>tf</b></td>
+<td>Target foreground.</td>
+</tr>
+<tr>
+<td><b>tb</b></td>
+<td>Target background.</td>
+</tr>
+<tr>
+<td><b>ks</b></td>
+<td>Task style.</td>
+</tr>
+<tr>
+<td><b>kf</b></td>
+<td>Task foreground.</td>
+</tr>
+<tr>
+<td><b>kb</b></td>
+<td>Task background.</td>
+</tr>
+<tr>
+<td><b>ss</b></td>
+<td>Success style.</td>
+</tr>
+<tr>
+<td><b>sf</b></td>
+<td>Success foreground.</td>
+</tr>
+<tr>
+<td><b>sb</b></td>
+<td>Success background.</td>
+</tr>
+<tr>
+<td><b>es</b></td>
+<td>Error style.</td>
+</tr>
+<tr>
+<td><b>ef</b></td>
+<td>Error foreground.</td>
+</tr>
+<tr>
+<td><b>eb</b></td>
+<td>Error background.</td>
+</tr>
+</table>
+
+<p>If a given key is not set, it will keep its default value. The bee
+options environment variable <code>BEEOPT</code> is the best place
+to set you style settings.</p>
+
+<p>Enjoy!</p>