Manual

Creating a Project

The bones command line tool is used to create a new project from a code template called a skeleton. A default Ruby library skeleton comes with the Mr Bones gem; however, you can create your own skeletons as discussed later in this document.

I’m a fan of the comic strip “Get Fuzzy” by Darby Colney, so let’s create a new Ruby gem called “get_fuzzy”.

bones create get_fuzzy

This command creates a new directory called “get_fuzzy” and populates it with code from our default project skeleton. If the “get_fuzzy” directory already existed, then the create command will raise an error.

There are other options available when using the create command, and some options are added by other plugins (such as the bones-git plugin). You can see the create options by using the —help flag.

bones create --help

The —help flag is available for all the various bones command modes.

Rake & Mr Bones

After your project is created, Mr Bones provides an assortment of Rake tasks to automate common development chores. The list of tasks can be shown using the standard rake -T command; this lists all available rake tasks along with a brief description of each.

Mr Bones relies on a “Bones” configuration block in the Rakefile to customize the available tasks. There are many configuration options available. These options have sensible defaults but are available to tailor the tasks to suit your needs.

A list of the options can be displayed.

rake bones:options

And a description of each option along with it’s current value can also be displayed.

rake bones:help

However, this list can be rather large. The list can be filtered by giving the name of an option (or a partial name) that you would like to see more information about.

rake bones:help gem

This would show information about all the options available for creating and releasing a gem for your project. If you would like to see just the configuration values without the helpful descriptions …

rake bones:debug

Skeletons

A skeleton is a project template that is used by Mr Bones when creating a new project. A default skeleton is provided, but the user is free to create and use their own skeletons. A skeleton for each type of project (library, web application, etc.) is a common pattern.

Mr Bones can even be used to create projects for programming languages other than Ruby; writing projects, templates for user manuals. Let your imagination run wild.

Freezing

Freezing allows you to define your own project code skeleton to instantiate when creating a new project. Freezing copies the default Mr Bones project skeleton to the “.mrbones” directory in your home directory. From there, the skeleton can be modified however you like (add new files and tasks, add new directories, etc).

bones freeze

Typical use of this feature would be to fill in user specific data like the author, e-mail address, etc. You can also add more code files to the default skeleton, different testing frameworks, and so on. The choice is entirely up to you.

You can have multiple skeletons with different names. Your projects can be instantiated from any of these skeletons. Just supply a name when freezing.

bones freeze foo

You can instantiate a project from the “foo” skeleton.

bones create --skeleton foo new_foo_project.

You could create a separate skeleton for the various types of projects you create. One for Ruby libraries, one for Rails applications, one for Sinatra applications, one for JRuby libraries, etc.

The default skeleton name is “default”. If no skeleton name is provided, then this is the skeleton that will be used.

Unfreezing

Unfreezing a skeleton will remove your customized project skeleton from the “.mrbones” directory. It will no longer be available when creating new projects. The default Mr Bones project skeleton will be used instead. Before it is removed, a copy of your custom skeleton is stored in an archive directory in the “.mrbones” folder.

bones unfreeze

You can unfreeze named skeletons, too.

bones unfreeze foo

Repositories

You can instantiate a new project from a git or svn repository. For example, if you would like to use the “bort” rails template from github, you can type in the following:

bones create --repository git://github.com/fudgestudios/bort.git new_rails_project

Typing in the full path to the repository each time is tedious. You can create an alias by freezing the repository and giving it an easy to remember name.

bones freeze --repository git://github.com/fudgestudios/bort.git bort

This does not checkout a copy of the repository; it give us an easy to use alias when we want to create a new proejct based on the repository. The following command will use our new alias to create a new rails project based on the bort template:

bones create --skeleton bort new_rails_project

If the repository contains ‘.bns’ files they will be filtered through the ERb templating system. All the custom modifications described in the next section apply to repository based skeletons as well.

Customizing

Mr Bones will perform a limited set of substitutions on the files in the skeleton when it generates a new project. ERb is used to insert the project name and the derived class name into template files. Filenames must end in an “.bns” suffix for ERb substitutions to take place. The “.bns” suffix is stripped from the file during project generation.

Only two values can be substituted into files using ERb — the project name and the derived class name.

<%= name %>
<%= classname %>

The project name is passed in from the command line and used “as is” (with the exception that spaces are converted to underscores). The classname is generated by pascal casing the project name where underscores occur.

get fuzzy  =>  GetFuzzy
foo_bar    =>  FooBar

Finally, file names can be modified by substituting in the project name. If a file name contains the string “NAME” it is replaced with the project name. If our project is called “get fuzzy” then the following transformations will take place.

NAME.rb       =>  get_fuzzy.rb
test_NAME.rb  =>  test_get_fuzzy.rb
NAME_spec.rb  =>  get_fuzzy_spec.rb