h1. !http://railsapps.github.io/images/rails-36x36.jpg(Rails Apps Composer Gem)! Rails Apps Composer
!https://badge.fury.io/rb/rails_apps_composer.png!:http://badge.fury.io/rb/rails_apps_composer !https://travis-ci.org/RailsApps/rails_apps_composer.png!:https://travis-ci.org/RailsApps/rails_apps_composer
The Rails Apps Composer gem installs a command line tool to assemble a Rails application from a collection of "recipes."
What you can do with the rails_apps_composer gem:
* create a starter app from the command line
* make a reusable application template
You can use local recipes as well as recipes supplied with the gem.
The "Rails Composer":http://railsapps.github.io/rails-composer/ tool is built with the rails_apps_composer gem. The Rails Composer tool creates the "example applications":http://railsapps.github.io/ for the "RailsApps":http://railsapps.github.io/ project.
The "Guide to the Rails Apps Composer Gem":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer provides complete documentation:
* "Overview":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#overview
* "Recipes":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#recipes
* "Usage":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#usage
* "Diagnostics":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#diagnostics
* "Hacking the Gem":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#hacking-the-gem
* "Anatomy of a Recipe":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#anatomy-of-a-recipe
* "Architecture":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#architecture
* "Defaults File":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#defaults-file
Any issues? Please create a "GitHub issue":http://github.com/RailsApps/rails_apps_composer/issues.
h2. What's New
See the "CHANGELOG":https://github.com/RailsApps/rails_apps_composer/blob/master/CHANGELOG.textile for details.
If your favorite recipe is missing, please fork the repo, add the recipe and test it, then submit a pull request. I'm happy to add new recipes.
h2. Who This Is For
This gem is for experienced Rails developers who need a tool to create and maintain a Rails starter app or Rails application template. If you're regularly building Rails applications that use certain popular gems or rely on common functionality such as authentication, you can benefit from the rails_apps_composer gem.
If you are new to Rails, try the "Rails Composer":http://railsapps.github.io/rails-composer/ tool instead. It provides an application template that is generated from the rails_apps_composer gem's core recipes. The Rails Composer tool is easier to use. Use the rails_apps_composer gem if you want a custom application template, a custom combination of recipes, or the convenience of setting a defaults file.
See the "CONTRIBUTING":https://github.com/RailsApps/rails_apps_composer/blob/master/CONTRIBUTING.textile file for details about how you can contribute fixes or new features.
h2. Alternatives
The rails_apps_composer gem is derived from Michael Bleigh's "RailsWizard":https://github.com/intridea/rails_wizard gem. Early versions of the rails_apps_composer gem were a close fork of Michael Bleigh's gem; rails_apps_composer 2.0 differs substantially. Other notable alternatives are Dr. Nic Williams's "App Scrolls":http://appscrolls.org/ and Daniel Davey's "app_drone":http://drone.bz/. See a list of "Rails Application Template Projects":http://railsapps.github.io/rails-application-templates.html, particularly a list of "Application template-generating gems" for similar projects.
h2. Dependencies
Before using the rails_apps_composer gem, you will need:
* The Ruby language (version 2.2)
* Rails (versions 4.2)
The rails_apps_composer program uses the version of Rails that is currently installed when you launch the program. If you want to use the newest Rails version, upgrade before running rails_apps_composer.
See the article "Installing Rails":http://railsapps.github.io/installing-rails.html for advice about updating Rails and your development environment. You'll avoid many potential headaches if you review the article step by step before beginning development.
h4. Database
Unless you use SQLite, which runs by default on Mac OS X, you'll need to have a database server running before you run rails_apps_composer. This is true if you want to use PostgreSQL, MySQL, or MongoDB. I recommend using SQLite if you don't want to set up a database server.
h4. Gemsets and RVM
Ordinarily, when you create a new Rails application, you work with a single set of gems. Before you create your Rails application, the rails gem must be installed in your Ruby environment. If you wish to use rails_apps_composer commands to generate a Rails application or template, you must also install the rails_apps_composer gem.
The rails_apps_composer gem uses the @rails new@ command to create a new Rails application. The rails_apps_composer gem modifies the new Gemfile and runs Bundler to install the gems you want in your new application. The gems will be installed in your current Ruby environment (and must not conflict with other gems already installed).
Some developers like to use RVM, the "Ruby Version Manager":https://rvm.io/, to manage gemsets. The "extras" recipe offers an option of creating or using a project-specific RVM gemset. That means rails_apps_composer will switch from an initial gemset to a new gemset during the process of creating your new application. If you choose the option of using the project-specific RVM gemset from the "extras" recipe, before you start you must be using RVM and you must install the rvm gem in addition to the rails and rails_apps_composer gems.
If you choose the option of creating or using a project-specific RVM gemset, you will use two gemsets. First, the gems installed in the current Ruby environment (including rails and rails_apps_composer and perhaps rvm). Second, after the @rails new@ command creates a Gemfile, and before Bundler installs the gems you want, rails_apps_composer will use the rvm gem to use or create a new gemset that is specific to your new project. Configuration choices you make when you run rails_apps_composer often add gems to the new application Gemfile (such as html2haml if you select Haml). Rails_apps_composer will use Bundler to install these gems and run any @generate@ commands within the project-specific gemset.
If you answer "yes" to creating a project-specific gemset and you don't have the rvm gem installed, you will get an error during the generation process saying RVM cannot be loaded. It is important to recognize that the gemset you start with (when you launch rails_apps_composer) can be replaced with a new project-specific gemset by the "build and compose" script (the "extras.rb" recipe line @RVM.gemset_use!@ in the generated application template).
h2. Installation and Usage
I recommend installing and using RVM, the "Ruby Version Manager":https://rvm.io/, to create a new gemset for rails_apps_composer. Using an RVM gemset will make it easier to identify and isolate incompatibilities among gems. RVM will install Ruby and set up a global gemset with a minimal set of gems.
Here's how to generate a new Rails application using rails_apps_composer and RVM:
$ mkdir myapp
$ cd myapp
$ rvm use ruby-2.1.0@myapp --ruby-version --create
$ gem install rails
$ gem install rails_apps_composer
$ gem install rvm # (only needed if creating a project-specific rvm gemset)
$ rails_apps_composer new . -r core
This approach avoids conflicts with outdated gem versions that may be active in your shell environment.
h3. Troubleshooting
You may have trouble if you install the rails_apps_composer gem by including it in a Gemfile and running Bundler (reported in "issue 114":https://github.com/RailsApps/rails_apps_composer/issues/114).
h2. Usage Options
These commands are summarized here for your reference. See the "Guide to the Rails Apps Composer Gem":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer for details.
h3. List Recipes
You can list recipes with short descriptions:
$ rails_apps_composer list
controllers # Add controllers needed for starter apps.
core # Select all core recipes.
email # Configure email accounts.
example # Example of a recipe.
extras # Various extras.
frontend # Install a front-end framework for HTML5 and CSS.
gems # Add the gems your application needs.
git # Initialize git for your application.
init # Set up and initialize database.
models # Add models needed for starter apps.
railsapps # Install RailsApps example applications.
readme # Build a README file for your application.
routes # Add routes needed for starter apps.
setup # Make choices for your application.
testing # Add testing framework.
views # Add views needed for starter apps.
The above list is current for rails_apps_composer 2.1; later releases will contain more recipes.
See the Guide for more "detailed descriptions of recipes":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#recipes. You can find all available recipes in the repository "recipes directory":https://github.com/RailsApps/rails_apps_composer/tree/master/recipes. Examining the recipe source code is the very best way to learn what a recipe will do.
h3. Recommended Recipes
I recommend selecting the _core_ recipe if you are just getting started. The _core_ recipe installs a collection of the most useful recipes.
h3. Recipe Order and Interdependency
The order in which you input a list or recipes determines the order of execution unless a recipe contains a @requires@ or @run_after@ directive.
A recipe may contain a @requires@ directive which specifies other recipes which must be present before a recipe can run. The @requires@ constraint will force the rails_apps_composer program to load any required recipes, even if you don't add them explicitly.
Recipes may also contain a @run_after@ directive. The rails_apps_composer program will organize the order of execution so that any recipes in the @run_after@ list will execute earlier. That is, the recipe will run after everything else in the list.
In general, it's best to add (or list) recipes in the order they should execute as some recipes may not contain a necessary @requires@ or @run_after@ directive.
See the "Anatomy of a Recipe":https://github.com/RailsApps/rails_apps_composer/wiki/tutorial-rails-apps-composer#anatomy section in the Guide to learn about the format of a recipe.
h3. Skipping Test::Unit or Active Record
If you plan to use RSpec instead of Test::Unit, or use an ORM such as Mongoid instead of Active Record, you must pass the @-T@ or @-O@ flags to the program so it will skip Test::Unit or Active Record.
The rails_apps_composer program will ask if you want to skip Test::Unit or Active Record when you generate an application interactively.
Any recipe can set the @-T@ or @-O@ arguments using the @args@ directive.
Also, you can set @-T@ or @-O@ arguments in the defaults file.
Setting @-T@ or @-O@ arguments has no affect on application templates. An application template runs after the @rails new@ command so it cannot set the @-T@ or @-O@ arguments. When you generate an application template, the program will not ask if you want to skip Test::Unit or Active Record.
h3. Using Local Recipes
You can use local recipes you've created yourself by using the @-l@ flag and supplying the name of a directory that contains local recipes. The @-l@ flag can be combined with any other command so you can create application