Overview of Amber

Amber is an enterprise scale build system that helps you manage hierarchical projects. Amber offers:

Simple project setup - start a new project in seconds
Consistent usage across projects, so new developers don’t need to ramp up
Superior dependency management, including transitive dependencies among projects
Easily work with multiple projects at one time
Extensible: add your own features in Ruby and/or Rake
Flexible: override Amber’s behaviors when necessary
Rake tasks for deployment outside of Amber
Meta-information based builds: one command builds multiple projects into several types of distribution packages… without extra scripting

Amber is similar in scope to Apache Maven: in fact much of the above feature list is derived from Maven’s feature list (even though Amber was written without any knowledge of Maven).

Amber is a layer on top of Rake that factors build files so that:

Code duplication (in Rakefiles) is minimized
Projects are very consistent.
Dependencies between projects are automatically handled gracefully
Projects can be run, tested, and packaged without installation, despite these dependencies
Packages can be constructed for different purposes:
- Windows stand alone .exe - for end users (works fine)
- Development - for project workers (works fine)
- RubyGems - for code users (not yet tested)
- RPA Base - for code users (not yet implemented)

Amber’s main disadvantage is that its consistency demands that simple projects have the same directory structure as complicated projects.

The Amber development package contains the following directories:

Amber - the Amber build system
Lib_AmberNeeds - externally maintained libraries required by Amber
Projects - projects managed by Amber

Status

Amber is currently pre-release software, which has not yet undergone internal reviews. Amber is used on a daily basis by several developers. The following Ruby projects are developed using Amber:

Pippin schema-based XML marshalling/unmarshalling
Yax expect-like scripting tool
OffspringViewer for visualizing printed circuits described by the IPC-2581 standard
Genie command pattern
Trimurti application assembler (plugin manager / dependency injector)

Installation

To use Amber, you must:

Define the "DevRoot" environmental variable that points to the package root (containing the Amber directory). This must use Unix style forward slashes, even under Windows.
Install the required libraries. The easiest way is to:
```
    cd into $DevRoot/Amber/bin
    sudo ruby bootstrap.rb
```
Of course you can instead install the required libraries manually if you already have some of them present. The libraries are located in Lib_AmberNeeds:
- RubyGems
- Rubywebdialogs
- Which
- Rake. This needs to be the manually installed version, not the RubyGem version (we have not yet investigated why this is case).

How Amber Works

Every project has a Rakefile.rb that:

Requires Amber/bin/phb.rb, which contains the PointyHairedBoss class that provides much of Amber’s behavior.
Deduces the name of the project from the directory name.
Requires metainfo/properties.
Requires Amber/bin/Rakefile_shared.rb, which provides the rake tasks common to all projects.

The following files may also be loaded by ‘require’:

metainfo/dependencies.rb - lists the libraries and additional projects that the project depends on
Amber/bin/directories.rb - the project directory structure
Amber/bin/properties_shared.rb - properties common to all projects (they can be overridden)
Amber/bin/Rakefile_system.rb - Rake tasks for managing projects

Common Tasks

Create a new project:

Build the directory structure:
```
     cd $DevRoot
     rake  name=NewProjectName  create_project
```
Your new project will be found in Projects/NewProjectName.
Edit metainfo/dependencies to specify
- The other Amber-managed projects required by this project
- Externally maintained libraries required by this project.
Put those externally maintained libraries in $DevRoot/Lib
Edit metainfo/proprties to specify:
- PHB[:run_file] - The Ruby file executed to run the program
- PHB[:summary] - A brief summary of the project
You can specify many other project properties, but they are optional.
Add your files to the directories specified in Manifest.txt:
- src_run - Source code
- src_test - Test code
- src_doc - Documentation source files (processed, along with src_run, by rdoc). Do not change the name of License.txt or ReadMe.txt (unless you modify PHB[:elevated_docs]).

Run your program:

      cd $DevRoot
      rake run

Amber will automatically add to Ruby’s load path the src_run directories for this Project, and (recursively) any other Projects specified in metainfo/dependencies.rb.

Run regression tests in src_test:

      cd $DevRoot
      rake test

Run rdoc to create HTML documentation from comments in source code:

      cd $DevRoot
      rake rdoc

Build .tgz, .zip, and RubyGem packages for distribution:

      cd $DevRoot
      rake package

You will find the resulting files in $DevRoot/Temp:

.zip and .tgz Development packages in DevRoot/Temp/devPackaging
Ruby Gem package in DevRoot/Temp/gemPackaging
All of these packages include rdocs

Windows only - ceate a double-clickable application that runs your program:

      cd $DevRoot
      rake rubyscript2exe

This will run your program: you need to exercise it to ensure that all the source files get loaded. Close the program when you are done, and you should find the executable in DevRoot/Temp/tar2exe.

Summary of Rake Targets

You can cd into one of directories in DevRoot/Projects, and execute:

rake -tasks # shows a listing of targets/operations
rake clean # Remove any temporary products, specified by PHB[:clean_fileList]
rake find_dirt # Shows files that will be removed by :clean and :clobber
sudo rake install_lib # Install libraries required by the project (rather than Amber)
rake rdoc # Creates HTML documentation from source files.
rake ri # Generate and install docs accessable to invoking user via ‘ri’.
rake ri_site # Generate and install docs accessable to all users via ‘ri’.
rake run # Run without installation. Used for debugging. Requires previous :install_lib
rake test # Run tests
rake package # Generate Distribution packages
rake rubyscript2exe # (Windows only) Generate a Windows executable
rake exerb # (Windows only) Generate a Windows executable (older method, not recommended)

There are a number of other targets, which have not been tested: don’t use them yet.

You can also cd $DevRoot, and execute:

rake -tasks # shows a listing of targests/operations
rake clean # removes temporary products
rake projects # shows a listing of project brief descriptions
rake name=NewProjectName create_project # make a new Project
rake name=RottenProjectName delete_project # delete existing Project
rake name=LibraryToFind find_library # invokes Devel::Which

Author: A. Griesser

Official contribution of the National Institute of Standards and Technology; not subject to copyright in the United States. Certain commercial equipment, instruments, or materials are identified in this paper to foster understanding. Such identification does not imply recommendation or endorsement by the National Institute of Standards and Technology, nor does it imply that the materials or equipment identified are necessarily the best available for the purpose.

ReadMe.txt