serve 0.11.2 → 0.11.3

data/CHANGELOG.rdoc

@@ -1,5 +1,9 @@
 = Change Log
 
+== 0.11.3 (May 26, 2010) 
+
+* Check for config.ru and use the `rackup` command instead if present.
+
 == 0.11.2 (May 25, 2010) 
 
 * Add dependency on Rack to gemspec [jlong]

data/README.rdoc

@@ -1,56 +1,136 @@
-= Serve
+= Serve - A Rapid Prototyping Framework for Web Applications
 
-Serve is a small web server (based on WEBrick) that makes it easy to serve
-HTML, ERB, or HAML from any directory.
+Serve is a small Rack-based web server that makes it easy to serve HTML, ERB, or HAML from any directory.
 
-Serve is an ideal tool for building HTML prototypes of Rails applications. One
-of the advantages of developing an HTML prototype is the opportunity to
-explore the flow of an application before developing the backend. The “Design
-First” approach also allows for substantial problem solving in the design
-phase and the ability to estimate features with accuracy. When views are
-ready, they can be copied over from the HTML prototype to the application
-almost as is. This process is eased since Serve has full support for partials
-and layouts with either ERB or HAML.
+But Serve is much more than a simple web server.
 
-Serve can also handle SASS, Textile, and Markdown if the appropriate gems are
-installed.
+Serve's primary purpose is to provide a rapid prototyping framework for Web
+applications (specifically Rails apps). It is designed to compliment web
+application development and enforce a strict separation of concerns between
+designer and developer. Using Serve allows the designer to work in a separate
+prototype project, while the developer can work on the actual application and
+utilize resources from the prototype as needed. This allows the designer to
+focus on presentation and flow, while the developer can focus on
+implementation.
+
+This "Design First" approach can help a designer identify and fix a large
+number of problems before a feature is ever touched by the developer. Once a
+feature has been completed in the prototype project it can also be estimated
+with a high degree of accuracy.
+
+A Serve prototype can work much like the finished application and be virtually
+indistinguishable. The only difference being that state is not saved as a user
+clicks around.
+
+Serve can be used alongside any Web development framework, but Rails
+developers will find it especially familiar. One way of thinking about Serve
+is that it is essentially a Rails application with only one part of the Rails
+MVC stack -- the views. Serve basically allows you to have a separate project
+just for designing the views for the application. When views are ready, they
+can be copied over from the prototype to the application almost as is. This
+process is eased since Serve has full support for partials and layouts with
+either ERB or HAML. Serve can also handle SASS, Textile, and Markdown if the
+appropriate libraries are installed.
+
+
+== Installation
+
+Serve is distributed as a Ruby gem and can be installed from the command prompt. Just type:
+
+  gem install serve
+
+Some systems, like the Mac, may require that you type:
+
+  sudo gem install serve
+
+If you are new to the command prompt see:
+
+http://kb.iu.edu/data/amog.html
+
+You may also want to google "command prompt windows" if you are on a PC or
+"command prompt osx" if you are on a Mac to find a simple tutorial.
 
 
 == Usage
 
-At a command prompt all you need to type to start serve is:
+Once the gem is installed the `serve` command will be available from the command prompt. To launch Serve, just type the command and press enter:
 
-  $ serve
+  serve
 
-This will launch a WEBrick server which you can access from any Web browser at
-the following address:
+This will launch a simple web server which you can access from any web browser
+at the following address:
 
   http://localhost:4000
 
 Once the server is going it will output a running log of its activity. To
 stop the server at any time, type CTRL+C at the command prompt. By default the
 serve command serves up files from the current directory. To change this
-behavior, `cd` to the appropriate directory before starting serve.
-
+behavior, `cd` to the appropriate directory before starting serve or pass the directory as the final parameter to the command:
 
-== Advanced Options
+  serve project_directory
 
-The serve command automatically binds to 0.0.0.0 (localhost) and uses port
+The `serve` command automatically binds to 0.0.0.0 (localhost) and uses port
 4000 by default. To serve files over a different IP (that is bound to your
 computer) or port specify those options on the command line:
 
-  $ serve 4000               # a custom port
-
-  $ serve 192.168.1.6        # a custom IP
-
-  $ serve 192.168.1.6:4000   # a custom IP and port
+  serve 4000               # a custom port
+  
+  serve 192.168.1.6        # a custom IP
+  
+  serve 192.168.1.6:4000   # a custom IP and port
 
 For your convenience if the file "script/server" exists in the current
 directory the serve command will start that instead of launching a WEBrick
-server. You can specify the environment that you want to start the server
-with as an option on the command line:
-
-  $ serve production         # start script/server in production mode
+server. You can specify the environment that you want to start the server with
+as an option on the command line:
+
+  serve production         # start script/server in production mode
+
+
+== Rack and Passenger
+
+Advanced users may also want to run Serve as a Rack application. To do this
+you will need to create a "config.ru" file in the root of your Serve project.
+Here is an example "config.ru" file:
+
+  #\ -p 4000
+  
+  gem 'activesupport', '2.3.5'
+  gem 'serve'
+  
+  require 'serve'
+  require 'serve/rack'
+  
+  # Middleware
+  use Rack::ShowStatus      # Nice looking 404s and other messages
+  use Rack::ShowExceptions  # Nice looking errors
+  
+  # The project root directory
+  root = File.dirname(__FILE__)  
+  
+  # Rack Application
+  run Rack::Cascade.new([
+    Serve::RackAdapter.new(root),  # Handle ERB, HAML, and other Serve files
+    Rack::Directory.new(root)      # Directory listings and everything else
+  ])
+
+Assuming that you have Rack installed, you will then be able to start your
+application with the `rackup` command. Type `rackup --help` for more
+information.
+
+If you would like to run Serve as a Rack application with Passenger you will
+need to create two additional directories: "tmp" and "public". In the temp
+directory put an empty "restart.txt" file. In the public directory put your
+static assets like images and javascripts (anything that does not require
+special processing by Serve). You may also want to replace the last four lines of "config.ru" with a single reference to the Serve::RackAdapter:
+
+  run Serve::RackAdapter.new(root)
+
+By default, Passenger applications serve static assets from the "public"
+directory so there is no need to use the Rack::Directory application to handle
+those. If you need directory listings your Web server probably provides
+something specifically for this purpose and there is no need to rely on Rack
+for this.
 
 
 == File Types
@@ -69,9 +149,9 @@ redirect :: Redirects to the URL contained in the document
 
 == View Helpers
 
-If you drop a file called view_helpers.rb in the root of a project, you can
-define custom helpers for your Haml and ERB views. Just declare the
-ViewHelpers module and begin declaring your helpers:
+If you drop a file called "view_helpers.rb" in the root of a project, you can
+define custom helpers for your Haml and ERB views. Just create a ViewHelpers
+module and define your helper methods there:
 
   module ViewHelpers
     def custom_method
@@ -79,23 +159,23 @@ ViewHelpers module and begin declaring your helpers:
     end
   end
 
+Helpers have full access to the request and response objects so you can
 
-== Installation and Setup
-
-It is recommended that you install serve via RubyGems:
 
-  $ sudo gem install serve
+== More Information
 
+You can find more information about Serve, including a detailed Screencast, on
+the GitHub wiki:
 
-== More Information
+http://wiki.github.com/jlong/serve
 
-For more information, be sure to look through the documentation over on the wiki: http://wiki.github.com/jlong/serve
+All development takes place on GitHub:
 
-All development takes place on GitHub: http://github.com/jlong/serve
+http://github.com/jlong/serve
 
 
 == License
 
 Serve is released under the MIT license and is copyright (c) 2007-2010
-John W. Long and Adam I. Williams. A copy of the MIT license can be found in
+John W. Long and Adam I. Williams. A copy of the MIT license can be found in 
 the LICENSE file.

data/VERSION

@@ -1 +1 @@
-0.11.2
+0.11.3

data/lib/serve/application.rb

@@ -24,8 +24,11 @@ module Serve
         puts help
       else
         Dir.chdir(options[:root])
-        if rails_app?
+        case
+        when rails_app?
           run_rails_app
+        when rack_app?
+          run_rack_app
         else
           run_server
         end
@@ -76,9 +79,14 @@ module Serve
         "  textile, and markdown file extensions.",
         "  ",
         "  If the Rails command script/server exists in the current directory the ",
-        "  script will start that instead with the specified environment or the ",
-        "  development environment if none is specified. Rails apps are started by ",
-        "  default on port 3000.",
+        "  script will start that instead.",
+        "  ",
+        "  If a Rack configuration file (config.ru) exists in the current directory the ",
+        "  script will start that using the rackup command.",
+        "  ",
+        "  A Rails or Rack app will start with the environment specified or the ",
+        "  development environment if none is specified. Rails and Rack apps are ",
+        "  started by default on port 3000.",
         "  ",
         "Options:",
         "  -h, --help      Show this message and quit.",
@@ -105,7 +113,7 @@ module Serve
       end
       
       def extract_port(args)
-        (args.delete(args.find {|a| /^\d\d\d*$/.match(a) }) || (rails_app? ? 3000 : 4000)).to_i
+        (args.delete(args.find {|a| /^\d\d\d*$/.match(a) }) || ((rails_app? or rack_app?) ? 3000 : 4000)).to_i
       end
       
       def extract_address(args)
@@ -134,6 +142,18 @@ module Serve
         system "#{rails_script_server} -p #{options[:port]} -b #{options[:address]} -e #{options[:environment]}"
       end
       
+      def rack_config
+        @rack_config ||= options[:root] + '/config.ru'
+      end
+      
+      def rack_app?
+        File.file?(rack_config)
+      end
+      
+      def run_rack_app
+        system "rackup -p #{options[:port]} -o #{options[:address]} -E #{options[:environment]} #{rack_config}"
+      end
+      
       def run_server
         root = options[:root]
         app = Rack::Builder.new do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: serve
 version: !ruby/object:Gem::Version 
-  hash: 55
+  hash: 53
   prerelease: false
   segments: 
   - 0
   - 11
-  - 2
-  version: 0.11.2
+  - 3
+  version: 0.11.3
 platform: ruby
 authors: 
 - John W. Long
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-25 00:00:00 -04:00
+date: 2010-05-26 00:00:00 -04:00
 default_executable: serve
 dependencies: 
 - !ruby/object:Gem::Dependency