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.
Groundwork uses subcommands:
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
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"
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.
As a convenience, to easily make recipes, you can do
which will make a basic recipe you can modify for the current directory.
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.
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