JumpStart

Quick! No time! Dinner burning! Tell me everything in three sentences!

  • JumpStart is a gem for quickly creating projects just the way you want them.

  • It uses YAML and your custom template files to automate all of that new project creation and configuration hoo-ha.

  • It’s dead easy to do.

Spiel

Are you:

  • Tired of customising newly created framework projects to get them just the way you want them?

  • On a holy quest for the almighty power to create any kind of project with a single command?

  • Dancing like MC Hammer in anticipation of a solution to starting framework-less projects with ease?

  • Offering to sell your granny for the opportunity to store all of your project templates in one handy git-able directory structure?

  • Frothing at the mouth for an easy command line way to create, copy, move or duplicate these templates?

  • If so you are in luck my friend. Have some Jumpstart!

Why?

Despite the many cool generators for a typical framework based project, there are always things that I want to set up differently. I figure that generated code will constantly change. With that in mind, the best way to control the creation of genuinely unique project configurations is to manipulate the files that the generators create. This is what JumpStart does, as well as some other cool stuff to avoid doing the same tedious setup dance over and over again. I also wanted one place to keep my setup templates for all kinds of different projects. I might want to create a Ruby Gem in a certain way, or a Sinatra app. I also like the idea of all of my templates residing in one source controlled space.

Use Case

My main use case is Rails. Application templates weren’t adjustable or broad enough in scope for me. I wanted a way of automatically configuring my local Nginx setup to include the new project, make a collection of changes to the files generated by Rails (for example changing the path of the Production MySQL database) as well as running a bunch of other stuff that needs to happen at a projects inception (Like running Capistrano and creating a custom deploy.rb file or checking the project in to source control.)

Ideas on improving JumpStart are welcome, give me a shout!

Features

With jumpstart you can:

  • Run many terminal commands in a specific order

  • Create new projects of any type quickly from templates

  • Create files from three different kinds of templates:

    • Whole templates. A like for like copy from the template to the new project.

    • Append templates. The template is appended to a file generated by a terminal command (e.g. rails)

    • Line templates. The template is inserted into a file generated by a terminal command at a specific line number.

  • Replace strings in the newly generated project with specified tags (like the project name)

  • Automatically configure local Nginx and hosts entries for a new project. (I’m using OS X so this is tailored for the Mac.)

  • Remove unwanted files that may have been created by a terminal command (e.g. rails)

Installation

gem install jumpstart

Or you can clone this git repo: 

git://github.com/i0n/jumpstart.git

Build jumpstart from the git repo’s gemspec:

gem build jumpstart.gemspec

Install the newly created gem: 

gem install jumpstart-WHATEVER_THE_CURRENT_VERSION_IS.gem

I’ve tested JumpStart with Ruby 1.8.7 and Ruby 1.9.2-head

If you’re on a Unix based system, you’re good to go!

If you are using Windows, what were you thinking! ;-) You’ll need the win32console gem to use JumpStart

gem install win32console

I can’t figure a good way to get this dependancy to install automatically for Windows users without disturbing their Unix bashing friends. If anyone knows how I might achieve this (with Bundler or otherwise) just let me know and I’ll implement it.

NOTE! If you install jumpstart using sudo then you will probably need to run jumpstart with sudo as well to grant writes to the YAML files in the gem.

Getting Started

There are a few ways to use jumpstart.

If you have a template and you would like to create a new project with it, pass the jumpstart command two arguments, the first being the new projects name, the second being the existing jumpstart template name. e.g.

jumpstart my_new_project my_existing_template

If you have already created a template and set it as the default jumpstart template (you can do this in the jumpstart menu), you can create a new project using it by passing just the new projects name to jumpstart. e.g. 

jumpstart my_new_project

If you haven’t created any templates yet, or you want to change one of JumpStarts configuration options, just call:

jumpstart

This will launch the jumpstart menu.

The JumpStart menu

JumpStart has a handy menu interface which will start up if you don’t pass the jumpstart command any (or enough) arguments. From the menu you can:

  • Create a new project from a list of existing templates

  • Create a new template from scratch (the config file and directory structure will be created for you.)

  • Create a new template by duplicating an existing one. (Everything the same except the name.)

  • Set the default template. (The template that will be used if you invoke the jumpstart command with only a project name)

  • Set the directory that JumpStart looks in for templates. This means you can have your own folder anywhere on your dev machine for templates. By default templates get created inside the JumpStart gems directory structure.

  • Easily reset the default template directory back to the original default (All of the templates in your current default templates directory will be copied back inside the gem.)

Template File Syntax

One of the core ideas behind jumpstart is the notion of generating files in a new project automatically from template files. The idea being that you specify a generator of some kind in the jumpstart YAML (the install command), which sets up a generic project (for example rails). Once this has happened the jumpstart template will be parsed for template files to apply to the new project. Anything inside the jumpstart_config directory will not be copied to the project, this is where the templates configuration YAML lives. Everything else is evaluated from the root of the template directory and applied to the new project, again with the projects containing folder treated as the beginning of file paths. So as an example, a jumpstart template called “my_template” containing the path /folder1/folder2/file.txt when parsed would generate the same path in the new project. e.g. my_project/folder1/folder2/file.txt The template files contained in a jumpstart template come in three flavours:

  • Whole templates.

Whole templates are copied to the new project verbatim. Any file that is not recognised as an append or line template is treated as a whole template.

  • Append templates: . or L.

Append templates append their contents to an existing file. You can get jumpstart to parse a file as an append template by prefixing the file name with . So for example say you have a jumpstart template that runs the rails command. After the new rails project has been generated you want jumpstart to append some information to the newly created Gemfile. You could use a whole template and overwrite everything, but this is a bit cumbersome. If things change in Rails (as they do all the time) then you will need to make constant changes to keep the template current. Better to just append what you need to the created file, just like you would do if handling the task manually. To create an append template for the Gemfile, you would create a file called: _._Gemfile There is one more option to bare in mind with append templates. If you specify an L as well, like this: L. The last line of the source file (ignoring whitespace) will be removed, and then the append template will be added as normal. Honestly, it’s handy.

  • Line templates: e.g. 123.

Line templates insert their contents into a file at a specified line, pushing existing contents down the page. This is very handy. Say for example that you want to insert some extra configuration information into your new rails projects config/environments/development.rb at line 18. In your jumpstart template you would create a file called config/environments/_18._development.rb If the file you specify doesn’t have as many lines as you said it would, whitespace will be added until the specified number is reached.

Task Execution Order

Jumpstart tasks are executed in the order that the YAML options below are displayed.

YAML Options

:install_path:

Can be omitted or left blank. If :install_path: is omitted, the new project will be created in whatever directory you are in when you run the command. It is the path where the project directory will be created e.g. 

:install_path: /Users/i0n/Sites

:install_command:

Can be omitted or left blank. The command that this template will run. The main shell command to create the project. e.g. 

:install_command: rails

:install_command_args:

Can be omitted or left blank. The arguments for :install_command. Broken into it’s own value to allow the project name to be inserted between the two values. e.g. 

:install_command_args: -d mysql -J -T

:run_after_install_command:

Can be omitted or left blank. Add extra commands that you want to run after the main install command, but before template generation has started. e.g. 

:run_after_install_command:
  - rails g controller home
  - rails g model home

:remove_files:

Can be omitted or left blank. List files that you would like removed from the newly generated project. Paths use the newly created project folder as root. e.g.

:remove_files:
  - /public/index.html
  - /public/favicon.ico
  - /public/images/rails.png

:run_after_jumpstart:

Can be omitted or left blank. Add extra commands that you want to run after template generation has completed. e.g.

:run_after_jumpstart:
  - rake db:create
  - capify!
  - git init
  - git add .
  - git commit -q -v -a -m "Initial commit"

:replace_strings:

Can be omitted or left blank. List files that you would like to perform string substitution on. This can be useful for populating files such as a capistrano deploy.rb file. Paths use the newly created project folder as root. Any key:value pair can be used for substitution, simply add the key name in CAPS to the template file then specify the symbol key and value as in the example. As of version 0.5 it is now possible to append _CLASS to the capitalised key name in your templates. This will capitalise the replacement value, which is very handy for files where you need a lowercase and capitalised version of the same string, like class or module definitions. Note! The value of :project_name is hard coded to be the same as the projects name, no matter the value entered in this config file. This helps with capistrano. e.g.

:replace_strings:
  - :target_path: /config/deploy.rb
    :symbols:
      :project_name: name_of_my_app
      :remote_server: thoughtplant
  - :target_path: /another/config/file.rb
    :symbols:
      :project_name: name_of_my_app
      :womble: uncle_bulgaria

:run_after_string_replace:

Can be omitted or left blank. Add extra commands that you want to run after templates have been parsed for string replacement. e.g.

:run_after_string_replace:
  - rake db:migrate

:local_nginx_conf:

Can be omitted or left blank. If you would like jumpstart to configure your local nginx setup specify a path. Handy for rails. e.g.

:local_nginx_conf: /usr/local/nginx/conf/nginx.conf

Example YAML

Example 1: Sets up a new Rails project, creating MySQL Dbs and other options. Creates a home controller. Removes superfluous files created by Rails generator. Capifys the project. Creates a git repo and checks everything in to it. Replaces PROJECT_NAME string in capistrano deploy.rb with the name of the new project. Creates and appends to files generated by Rails to get everything ready to go straight away. Configures local Nginx environment. Not bad for one YAML!

---  
:install_path: /Users/i0n/Sites  

:install_command: rails  

:install_command_args: -d mysql -J -T  

:run_after_install_command:  
  - rails g controller home  

:remove_files:  
  - /app/views/layouts/application.html.erb  
  - /public/index.html  
  - /public/favicon.ico  
  - /public/images/rails.png  

:run_after_jumpstart:  
  - rake db:create  
  - capify .  
  - git init  
  - git add .  
  - git commit -q -v -a -m "Initial commit"  

:replace_strings:  
  - :target_path: /config/deploy.rb  
    :symbols:  
      :project_name: name_of_my_app  
      :remote_server: thoughtplant  
  - :target_path: /config/environments/development.rb  
    :symbols:  
      :project_name: name_of_my_app  
  - :target_path: /config/environments/test.rb  
    :symbols:  
      :project_name: name_of_my_app  
  - :target_path: /config/environments/production.rb  
    :symbols:  
      :project_name: name_of_my_app  

:local_nginx_conf: /usr/local/nginx/conf/nginx.conf

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.