Groundwork

Groundwork generates project outlines. Often, there are a lot of boilerplate files you need to start a project; this helps you not only create those files, but make recipes to add new types of project.

Basic use

Groundwork uses subcommands:

groundwork list

lists the known recipes, both built-in and ones you’ve installed

groundwork <recipe> <name>

Runs the recipe given by name

groundwork install <recipe_file>

Installs the given recipe file into ~/.groundwork

You can get help on Groundwork with groundwork -h and help for a specific command (including recipes) with groundwork <command> -h

Making recipes

The recipe DSL

A recipe is a script written in a Ruby DSL. It’s pretty straightforward:

file "file1.txt", "File 1 contents"

directory "dir1" do
    file "file2.txt", :erb => "<%= 2 + 2 %>"
end

Most of the time you’ll want to make it generate files from other files, instead of putting the contents inline. You can do so like this:

file "filename", :from => "path/to/file"

Or, to generate a file from an ERb template:

file "filename", :from_erb => "path/to/file"

Compiling

If your recipe references external files, you should compile it like so:

groundwork compile <recipe_file>

This will include all the files your script reads from into the script itself, and make a self-contained file for installing.

Generating

As a convenience, to easily make recipes, you can do

groundwork generate

which will make a basic recipe you can modify for the current directory.

Unpacking

You can modify a recipe that’s been installed with:

groundwork unpack <recipe>

This will put the recipe file and the required external files into a directory under the current one. You can then modify them, recompile, and reinstall. A recipe that you’ve installed into .groundwork takes precedence over one that comes with the gem, so you can overload built-in recipes.

Options

Your recipes can take options from the command line. Groundwork uses Trollop for option parsing, so the syntax is like this:

options do
	opt :domain, "Domain name", :default => "geekfu.org"
end

if @domain_given
	file "domain.txt", :erb=> "The domain is <%= @domain %>"
end

Every script is guaranteed at least one argument: name, the name of the newly-created directory that we’re building running the recipe in. This is the first remaining command-line parameter after options and flags are parsed out:

groundwork example-recipe -a --foo-mode -n 10 name

groundwork example-recipe name -x

In both cases, Trollop is intelligent enough to figure out that name is the name, and the rest are options and flags described in options.