=JumpStart JumpStart is a gem for quickly creating projects. It does this by running options from a YAML file that you can create, or you can let the gem do it for you. It's dead easy to do. ==Use Case Despite the many cool generators etc for a typical framework based project, there are always things that I wanted set up differently when starting a new Rails/Sinatra/(other cool framework) project. I figured that the way that these tools create code, and what that code is, will constantly change. With that in mind, the only way to be able to control the creation of genuinely unique project configurations would be to manipulate the files that these processes 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. My main use case is Rails. Application templates weren't adjustable or broad enough in scope for me, and 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. Git in my case.) 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. So that's why I wrote this gem. That, and it being fun :-) Give it a try, I think you'll like it. Finally, if you think that anything isn't clear in this README or you have other ideas about improving JumpStart, 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 it 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 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. 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 ===: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. Copyright Copyright (c) 2010 i0n. See LICENSE for details.