The rails new command is probably the first bit of the Rails command line we all learned. Give it an application name, and that command will create a fully functional (sic) Rails web application. Much of the convention over configuration plays out in the generated structure, with the app directory holding our model, view, controller, and (now, at Rails 3.1) client-side assets.
My added emphasis on “fully functional” in the previous statement exists to point out that the site is hardly production-ready. More often than not, there are database, security, or other concerns, but the generated app is a great foundation. So, how can we tweak this foundation to put us a bit further us down more specific development paths?
The options available to rails new are shown in the screenshot below.
Let’s go through each one and discuss what it does, and why you may want to use it.
Ruby Path (-r, --ruby)
The PATH to the Ruby binary that will be used for this Rails application. You might use this to test your app against another version of Ruby or lock it into certain version. On the development side, this is unnecessary due to tools like RVM, but your production or staging environments may have multiple Ruby versions.
Application Builder (-b, --builder)
In the last post, I briefly mentioned the ability to specify an application builder. The builder is responsible for creating the application structure, so providing your own builder allows you to change that structure and content as you see fit. In short, you create a class that inherits from Rails::AppBuilder and overrides the things you want to change. You can specify a different Test framework (say, RSpec) or automatically include your favorites gems or rake tasks…well, you get the idea. Here is the best post I could find on the process (thanks Mike Barinek!)
Application Template (-m, --template)
Application Templates are another way to change how the application is generated. In this case, the parameter you pass to -m is a Ruby file that allows the addition of gems or initializers to a generated Rails application. The major difference between using a builder and using a template is when the customizations occur. Using a builder, you could modify the structure of the app as it is generated (for example, I could call the lib directory “bibloteca”), which you can’t (read: shouldn’t) do with a template.
Application Templates are more about selecting the right gems, running rake tasks, and adding initializers to the base application structure. Templates seem to be the much more popular method for customizing Rails application generation, and there is even RailsWizard to make creating templates a breeze. Also, I feel any mention of Rails application templates is incomplete without highlighting the awesome work of Daniel Kehoe and his RailsApp repository.
Things you can skip
Many of the options to the rails new command allow you to NOT do something.
- (
--skip-gemfile): Do not create the Gemfile, because I am bringing my own or I am not using Bundler. - (
--skip-bundle): Do not runbundle installafter generating the app, because I want to do something before Bundler does its thing. - (
-G, --skip-active-record): Don’t include ActiveRecord, because I am using a different ORM or a NoSQL database. - (
-J, --skip-javascript): Don’t supply the default javascript files, because I am bringing my own. - (
-T, --skip-test-unit): Don’t create the default Test::Unit test files (BTW, this doesn’t even create the test directory), because I am using a different test framework (like RSpec). - (
-F, --skip-git): Don’t create Git files (.gitgnore and .gitkeep) because I am using a different source control system or (NOOOO!) none at all. It’s interesting to note, that, in the official guides, a--gitoption is mentioned. From what I can tell, this option is not valid (and is ignored by the command) but must be a hangover from when the Git files were not created by default.
Specify a Database(-d, --database)
By default, Rails presumes a new application will be using a database and that database will be SQLite. This allows for easy spiking of Rails apps without brining in the overhead of a typical RDBMS. However, the cases for which you want to use a different RDBMS, you can specify one of them using this option and supplying one of the supported parameters. Those supported parameters are: mysql/oracle/postgresql/sqlite3/frontbase/ibm_db/jdbcmysql/jdbcsqlite3/jdbcpostgresql. Supply one of these and your Gemfile and config/database.yml will be generated appropriately.
Specify a Rails Location
There are two options (--dev and --edge) that allow you to point to a particular version of Rails. Using --dev that allows you to point to a local Rails Git repository. In this case, the version of Rails from your local repository either needs to be in the PATH or needs to be specified as the full path when generating the application. For example:
ruby /path/to/rails/bin/rails new theapp --dev # from rubyonrails.orgThe --edge option will point to the HEAD version of the main Rails Github repository. In either case, you want to freeze your Rails version.
Specify a javascript library (-j, --javascript=JAVASCRIPT)
If you don’t want to use a different option beside jQuery, you can specify ‘prototype’ to the -j option and get an app with the Prototype library.
Runtime options
The various runtime options affect the feedback of the command, as well as how to treat existing files. The parameters -f and --force will overwrite any existing files. You might want to do this if you’ve corrupted some of the base files and (for shame!) aren’t using source control. The parameters -s and --skip are the opposite of force and will not overwrite any existing files. Perhaps my favorite command line switch is -p, --pretend, which doesn’t actually create anything, but still emits the output of the command so you can see what it would do. And finally, -q, --quiet suppresses all output. I like to run rails new existential_app -p -q and wonder aloud if it every really existed…
To finish up, let’s generate an application to be used by the remainder of the articles in this series. Sadly, we’ll just use all the defaults.
rails new deep_diveThe output of this command is here
Before we go, let’s make sure we are up and running. Change into the deep_dive directory and type rails s. You should see output like:
Now, if you open http://localhost:3000 you should see the familiar “Ruby on Rails: Welcome Aboard” page that we will delete with extreme prejudice in the next post and start really creating our app.
Glenn GoodrichGlenn works for Skookum Digital Works by day and manages the SitePoint Ruby channel at night. He likes to pretend he has a secret identity, but can't come up with a good superhero name. He's settling for "Roob", for now.
