Every Rails application looks basically the same. Each has the same directories, and even files with the same names. The reason for this is that Rails provides a command (rails) for creating a stock set of directories and stub files as a starting point for any new application, to be fleshed out as development progresses. These files and directories are arranged in such a way that the different parts of Rails (in fact, it is a framework of frameworks) can work together effectively. When starting a new application, running the rails command is the first step.
If you followed the tutorial sections in Chapter 3, you will have checked out the Intranet project from Subversion. This means, you already have an empty Intranet directory inside your Eclipse workspace, "connected" to the code repository. Rather than create a new directory for your application, you can use this existing one for your application as shown below:
$ cd workspace
$ rails Intranet
(Note that you may need to replace workspace with the directory you are using for your Eclipse workspace.)
More generally, use this command from a prompt to start a new Rails application in situations where you haven't created a project directory yet:
$ rails /path/to/application
Where /path/to/application is the path to the directory where you want your application to live. If the directory doesn't exist, or if any directories in the path are missing, they are created too. If you use a non-absolute path, the directories are created below the current working directory.
Note that you must use operating-system-specific path separators, so on Windows you would do:
$ rails c:path oapplication
When you run the rails command, you should see something like this:
$ rails Intranet
exists
create app/controllers
create app/helpers
create app/models
create app/views/layouts
create config/environments
create components
...
create log/server.log
create log/production.log
create log/development.log
create log/test.log
(This has been truncated for brevity: the rails command generates a lot of stuff.)
The absolute path to the top-level directory containing the application is referred to inside Rails as the RAILS_ROOT directory. In our case (as we're developing with Rory), this directory is:
/home/rory/workspace/Intranet
Rather than going into too much detail, below is a summary of what is contained in a fresh RAILS_ROOT directory. Directories which are particularly important are marked with an asterisk, as we'll be spending most of our time inside them:
*appcontains the core MVC classes of the application (see the earlier section Rails and MVC), separated into four subdirectories:controllerscontains controller definitions, which handle the control flow of the application.*modelshold model definitions, which act as the layer between the controllers and the database.viewscontains templates for generating interface elements, such as XHTML or XML output.helpersare companions to views. They are intended to move heavy lifting out of view templates and into "helper" methods, which (generally) generate HTML elements.
Componentsis largely deprecated, and remains for historical reasons. Originally, components were intended to encapsulate reusable chunks of code, which could be shared across applications. They were superseded by plugins (see the section on plugins in Chapter 8). You can safely delete this directory.*configholds the application's configuration. Most of the time, you only need to worry about setting up the connection to the database (which we'll do in the section Setting Up a Database Connection, later this chapter).*dbholds all database-related files and scripts. This includes dumps of the database and schema definitions. We'll be working in this directory throughout the chapter.docholds an auto-generated API documentation for your application. This is covered briefly in the section introducing Rdoc in Chapter 5.libholds library files, which are not necessarily Rails-specific, e.g. generic Ruby libraries. Any Ruby file you drop in here (anything ending in *.rb) is automatically loaded during your application's startup. It is most often used as the location for new Rake task definitions, which are added to thetaskssub-directory (see the bullet point below on theRakefile).logholds log files for your application.publiccontains static files, such as images and Javascripts.*scriptcontains helper scripts for your application, such as the interactive console and code generators. We'll be using these later in this chapter.testcontains test cases for your code. Each time you auto-generate a new model or controller, tests are added here. Testing is covered later in this chapter.tmpcontains temporary files, namely cached output, session data, and server sockets.vendorhouses thepluginsdirectory (for plugins, naturally—see the section on Plugins in Chapter 8. It is also used to store the libraries you haven't written yourself (such as external gems).- The
READMEfile in the root of your application directory contains generic information for people who may be installing your application. TheREADME_FOR_APPfile in thedocdirectory is probably a better place to add your information, as this becomes part of any auto-generated documentation. - Rake is an important tool in your arsenal, enabling you to automate repetitive development tasks. The
Rakefiledefines the set of tasks available in your project. By default, these include things like running your test suite, maintaining your database, and clearing temporary data. You can add your own Rake tasks underlib/tasks.
This is a whirlwind tour, but should hopefully give some idea of what all that stuff is for.
Note
If you switch to Eclipse to browse your new Rails application, you might wonder where the files have gone. This is because Eclipse doesn't monitor changes to the filesystem. When we added our application files outside Eclipse (by running the rails command), Eclipse didn't know anything about it.
The solution is to refresh Eclipse's view of the filesystem. Right-click on the name of the project and select the Refresh option from the context menu. You should now be able to see your files.
Now we have a skeletal application, we are finally ready for some magic.
I expect you're dying to see your first Rails application up and running? It turns out this is no work at all. Connect into your application's directory using the command line, and run the following command:
$ ruby script/server
Or, on Windows:
$ ruby scriptserver
This command runs one of the Rails built-in scripts, located in the script directory, which starts a Mongrel server whose single purpose is running your Rails application.
If the server starts correctly, you should see:
=> Booting Mongrel (use 'script/server webrick' to force WEBrick)
=> Rails application starting on http://0.0.0.0:3000
=> Call with -d to detach
=> Ctrl-C to shutdown server
** Starting Mongrel listening at 0.0.0.0:3000
** Starting Rails with development environment...
** Rails loaded.
** Loading any Rails specific GemPlugins
** Signals ready. TERM => stop. USR2 => restart. INT => stop (no restart).
** Rails signals registered. HUP => reload (without restart). It might not work well.
** Mongrel available at 0.0.0.0:3000
** Use CTRL-C to stop.
Note that the application is served on port 3000 by default and is accessible at the URL http://localhost:3000/. If you open this URL in a browser, you should see something like this:
Click on the About your application's environment link to see some information about the versions of Ruby and Rails you are running with.
On Linux, you can dispense with the ruby command and just use this command to run the server:
$ script/server
The only requirement for this to work is that the script should be able to find your Ruby binary. This is defined in the shebang line (the first line of the file). Usually, the default line works correctly:
#!/usr/bin/env ruby
However, if your Ruby installation isn't in your PATH environment variable, you may have to modify the ruby part of this line to point at its location. For example, if your Ruby installation is in /opt/ruby1.8.4 you would use the shebang:
#!/usr/bin/env /opt/ruby1.8.4/bin/ruby
Our application isn't too exciting so far, we can't interact with it very much, and it has little data to serve. In the next sections, we're going to build it up, taking a data-centric approach.
Note
As of Rails 1.2, if Mongrel is installed on your machine, it is used as the default web server for your application. However, if you don't have Mongrel installed, Mongrel isn't on your path, or you are using an older version of Rails, WEBrick is used instead. The only difference is that WEBrick is significantly slower, and not suitable for running Rails applications in a production environment. Other than that, you can happily develop an application using either.