spring 0.0.5 → 0.0.6

data/README.md

@@ -1,5 +1,7 @@
 # Spring
 
+[![Build Status](https://travis-ci.org/jonleighton/spring.png?branch=master)](https://travis-ci.org/jonleighton/spring)
+
 Spring is a Rails application preloader. It's trying to solve the same
 problem as [spork](https://github.com/sporkrb/spork),
 [zeus](https://github.com/burke/zeus) and
@@ -42,16 +44,9 @@ At the moment only MRI 1.9.3 / Rails 3.2 is supported.
 
 ## Usage
 
-Install the `spring` gem. You may wish to add it to your bundle, but
-it's not necessary. If you do, I don't recommend invoking `spring`
-via `bundle exec` as that will make it slow. Just call `spring`
-on its own.
-
-You now have a `spring` command. Do a `rbenv rehash` if necessary. Note
-that on my machine I had over 700 gems installed, and activating the gem
-to run the `spring` command added over 0.5s to the runtime. Clearing out
-my gems solved the problem, but I'd like to figure out a way to speed
-this up.
+Install the `spring` gem. You can add it to your Gemfile if you like but
+it's optional. You now have a `spring` command. Don't use it with
+`bundle exec` or it will be extremely slow.
 
 For this walkthrough, I'm using the test app in the Spring repository:
 
@@ -69,28 +64,28 @@ Run options:
 
 .......
 
-Finished tests in 0.169882s, 41.2051 tests/s, 58.8644 assertions/s.
+Finished tests in 0.127245s, 55.0121 tests/s, 78.5887 assertions/s.
 
 7 tests, 10 assertions, 0 failures, 0 errors, 0 skips
 
-real	0m1.858s
-user	0m0.184s
-sys	0m0.067s
+real	0m2.165s
+user	0m0.281s
+sys	0m0.066s
 ```
 
 That booted our app in the background:
 
 ```
 $ ps ax | grep spring
- 8692 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -I ... -r spring/server -r bundler/setup -e Spring::Server.boot
- 8698 pts/6    Sl     0:02 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -I ... -r spring/server -r bundler/setup -e Spring::Server.boot
+26150 pts/3    Sl     0:00 spring server | rails-3-2 | started 2013-02-01 20:16:40 +0000
+26155 pts/3    Sl     0:02 spring app    | rails-3-2 | started 2013-02-01 20:16:40 +0000 | test mode
 ```
 
 We can see two processes, one is the Spring server, the other is the
 application running in the test environment. When we close the terminal,
 the processes will be killed automatically.
 
-Running the tests is faster next time:
+Running the test is faster next time:
 
 ```
 $ time spring test test/functional/posts_controller_test.rb
@@ -100,42 +95,76 @@ Run options:
 
 .......
 
-Finished tests in 0.162963s, 42.9546 tests/s, 61.3637 assertions/s.
+Finished tests in 0.176896s, 39.5714 tests/s, 56.5305 assertions/s.
 
 7 tests, 10 assertions, 0 failures, 0 errors, 0 skips
 
-real	0m0.492s
-user	0m0.179s
-sys	0m0.063s
+real	0m0.610s
+user	0m0.276s
+sys	0m0.059s
+```
+
+Running `spring test`, `spring rake`, `spring console`, etc gets a bit
+tedious. It also suffers from a performance issue in Rubygems ([which I
+am actively working on](https://github.com/rubygems/rubygems/pull/435))
+which means the `spring` command takes a while to start up. The more
+gems you have, the longer it takes.
+
+Spring binstubs solve both of these problems. If you will be running the
+`test` command regularly, run:
+
+```
+$ spring binstub test
+```
+
+This generates a `bin/spring` and a `bin/test`, which allows you to run
+`spring` and `spring test` in a way that doesn't trigger the Rubygems
+performance bug:
+
+```
+$ time bin/test test/functional/posts_controller_test.rb
+Run options:
+
+# Running tests:
+
+.......
+
+Finished tests in 0.166585s, 42.0207 tests/s, 60.0296 assertions/s.
+
+7 tests, 10 assertions, 0 failures, 0 errors, 0 skips
+
+real	0m0.407s
+user	0m0.077s
+sys	0m0.059s
 ```
 
 If we edit any of the application files, or test files, the change will
-be picked up on the next run, without having the background process
-having to be restarted. This works even if you e.g. referenced your
-`Post` model in an initializer and then edited it.
+be picked up on the next run, without the background process
+having to be restarted.
 
 If we edit any of the preloaded files, the application needs to restart
-automatically. Note that the application process id is 8698 above. Let's
-"edit" the `config/application.rb`:
+automatically. Let's "edit" `config/application.rb`:
 
 ```
 $ touch config/application.rb
 $ ps ax | grep spring
- 8692 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -I ... -r spring/server -r bundler/setup -e Spring::Server.boot
- 8876 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -I ... -r spring/server -r bundler/setup -e Spring::Server.boot
+26150 pts/3    Sl     0:00 spring server | rails-3-2 | started 2013-02-01 20:16:40 +0000
+26556 pts/3    Sl     0:00 spring app    | rails-3-2 | started 2013-02-01 20:20:07 +0000 | test mode
 ```
 
 The application process detected the change and exited. The server process
 then detected that the application process exited, so it started a new application.
-All of this happens automatically in the background. Next time we run a
-command we'll be running against a fresh application.
+All of this happened automatically. Next time we run a
+command we'll be running against a fresh application. We can see that
+the start time and PID of the app process has changed.
 
 If we run a command that uses a different environment, then it gets
 booted up. For example, the `rake` command uses the `development`
 environment by default:
 
 ```
-$ time spring rake routes
+$ spring binstub rake
+$ bin/rake routes
     posts GET    /posts(.:format)          posts#index
           POST   /posts(.:format)          posts#create
  new_post GET    /posts/new(.:format)      posts#new
@@ -143,10 +172,6 @@ edit_post GET    /posts/:id/edit(.:format) posts#edit
      post GET    /posts/:id(.:format)      posts#show
           PUT    /posts/:id(.:format)      posts#update
           DELETE /posts/:id(.:format)      posts#destroy
-
-real	0m0.763s
-user	0m0.185s
-sys	0m0.063s
 ```
 
 We now have 3 processes: the server, and application in test mode and
@@ -154,26 +179,9 @@ the application in development mode.
 
 ```
 $ ps ax | grep spring
- 8692 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -I ... -r spring/server -r bundler/setup -e Spring::Server.boot
- 8876 pts/6    Sl     0:15 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -I ... -r spring/server -r bundler/setup -e Spring::Server.boot
- 9088 pts/6    Sl     0:01 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -I ... -r spring/server -r bundler/setup -e Spring::Server.boot
-```
-
-Running rake is faster the second time:
-
-```
-$ time spring rake routes
-    posts GET    /posts(.:format)          posts#index
-          POST   /posts(.:format)          posts#create
- new_post GET    /posts/new(.:format)      posts#new
-edit_post GET    /posts/:id/edit(.:format) posts#edit
-     post GET    /posts/:id(.:format)      posts#show
-          PUT    /posts/:id(.:format)      posts#update
-          DELETE /posts/:id(.:format)      posts#destroy
-
-real	0m0.341s
-user	0m0.177s
-sys	0m0.070s
+26150 pts/3    Sl     0:00 spring server | rails-3-2 | started 2013-02-01 20:16:40 +0000
+26556 pts/3    Sl     0:08 spring app    | rails-3-2 | started 2013-02-01 20:20:07 +0000 | test mode
+26707 pts/3    Sl     0:00 spring app    | rails-3-2 | started 2013-02-01 20:22:41 +0000 | development mode
 ```
 
 ## Commands
@@ -184,15 +192,27 @@ Custom commands can be specified in `config/spring.rb`. See
 [`lib/spring/commands.rb`](https://github.com/jonleighton/spring/blob/master/lib/spring/commands.rb)
 for examples.
 
+A bunch of different test frameworks are supported at the moment in
+order to make it easy for people to try spring. However in the future
+the code to use a specific test framework should not be contained in the
+spring repository.
+
 ### `test`
 
 Runs a test (e.g. Test::Unit, MiniTest::Unit, etc.) Preloads the `test_helper` file.
 
+This command can also recursively run a directory of tests. For example,
+`spring test test/functional` will run `test/functional/**/*_test.rb`.
+
 ### `rspec`
 
 Runs an rspec spec, exactly the same as the `rspec` executable. Preloads
 the `spec_helper` file.
 
+### `cucumber`
+
+Runs a cucumber feature.
+
 ### `rake`
 
 Runs a rake task.
@@ -210,3 +230,23 @@ Runs a Rails generator.
 ### `runner`
 
 The Rails runner.
+
+## Configuration
+
+### application_root
+
+Spring must know how to find your rails application. If you have a
+normal app everything works out of the box. If you are working on a
+project with a special setup (an engine for example), you must tell
+Spring where your app is located:
+
+**config/spring.rb**
+
+```ruby
+Spring.application_root = './test/dummy'
+```
+
+### tmp directory
+
+Spring needs a tmp directory. This will default to `Rails.root.join('tmp', 'spring')`.
+You can set your own configuration directory by setting the `SPRING_TMP_PATH` environment variable.

data/bin/spring

@@ -1,5 +1,4 @@
 #!/usr/bin/env ruby
 
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
-require 'spring'
-Spring.run(ARGV)
+require 'spring/client'
+Spring::Client.run(ARGV)

data/lib/spring/application.rb

@@ -1,8 +1,9 @@
+require "spring/configuration"
 require "spring/application_watcher"
 require "spring/commands"
 require "set"
 
-class Spring
+module Spring
   class << self
     attr_accessor :application_watcher
   end
@@ -21,13 +22,10 @@ class Spring
 
       @stdout = IO.new(STDOUT.fileno)
       @stderr = IO.new(STDERR.fileno)
-      @stdin  = File.open('/dev/null', 'r')
-
-      STDIN.reopen(@stdin)
     end
 
     def start
-      require "./config/application"
+      require Spring.application_root_path.join("config", "application")
 
       # The test environment has config.cache_classes = true set by default.
       # However, we don't want this to prevent us from performing class reloading,
@@ -36,7 +34,7 @@ class Spring
         ActiveSupport::Dependencies.mechanism = :load
       end
 
-      require "./config/environment"
+      require Spring.application_root_path.join("config", "environment")
 
       watcher.add_files $LOADED_FEATURES
       watcher.add_files ["Gemfile", "Gemfile.lock"].map { |f| "#{Rails.root}/#{f}" }
@@ -60,6 +58,7 @@ class Spring
 
     def serve(client)
       redirect_output(client) do
+        stdin       = client.recv_io
         args_length = client.gets.to_i
         args        = args_length.times.map { client.read(client.gets.to_i) }
         command     = Spring.command(args.shift)
@@ -70,6 +69,8 @@ class Spring
         ActionDispatch::Reloader.prepare!
 
         pid = fork {
+          Process.setsid
+          STDIN.reopen(stdin)
           IGNORE_SIGNALS.each { |sig| trap(sig, "DEFAULT") }
           command.call(args)
         }
@@ -101,13 +102,11 @@ class Spring
     def redirect_output(socket)
       STDOUT.reopen socket.recv_io
       STDERR.reopen socket.recv_io
-      STDIN.reopen  socket.recv_io
 
       yield
     ensure
       STDOUT.reopen @stdout
       STDERR.reopen @stderr
-      STDIN.reopen  @stdin
     end
   end
 end

data/lib/spring/application_manager.rb

@@ -2,15 +2,17 @@ require "socket"
 require "spring/application"
 require "mutex_m"
 
-class Spring
+module Spring
   class ApplicationManager
     include Mutex_m
 
-    attr_reader :pid, :child, :env
+    attr_reader :pid, :child, :app_env, :spring_env
 
-    def initialize(env)
+    def initialize(app_env)
       super()
-      @env = env
+
+      @app_env    = app_env
+      @spring_env = Env.new
     end
 
     def start
@@ -56,6 +58,10 @@ class Spring
       @client = nil
     end
 
+    def stop
+      Process.kill('TERM', pid) if pid
+    end
+
     private
 
     def start_child(silence = false)
@@ -63,7 +69,8 @@ class Spring
       @pid = fork {
         [STDOUT, STDERR].each { |s| s.reopen('/dev/null', 'w') } if silence
         @client.close if @client
-        ENV['RAILS_ENV'] = ENV['RACK_ENV'] = env
+        ENV['RAILS_ENV'] = ENV['RACK_ENV'] = app_env
+        $0 = "spring app    | #{spring_env.app_name} | started #{Time.now} | #{app_env} mode"
         Application.new(child_socket).start
       }
       child_socket.close

data/lib/spring/application_watcher.rb

@@ -1,4 +1,4 @@
-class Spring
+module Spring
   class ApplicationWatcher
     attr_reader :mtime, :files, :globs
 
@@ -31,6 +31,9 @@ class Spring
 
     def compute_mtime
       expanded_files.map { |f| File.mtime(f).to_f }.max || 0
+    rescue Errno::ENOENT
+      # if a file does no longer exist, the watcher is always stale.
+      Float::MAX
     end
 
     def expanded_files

data/lib/spring/client.rb

@@ -0,0 +1,31 @@
+require "spring/configuration"
+require "spring/client/command"
+require "spring/client/run"
+require "spring/client/help"
+require "spring/client/binstub"
+require "spring/client/stop"
+
+module Spring
+  module Client
+    COMMANDS = {
+      "help"    => Client::Help,
+      "binstub" => Client::Binstub,
+      "stop"    => Client::Stop
+    }
+
+    def self.run(args)
+      command_for(args.first).call(args)
+    rescue ClientError => e
+      STDERR.puts e.message
+      exit 1
+    end
+
+    def self.command_for(name)
+      if Spring.command?(name)
+        Client::Run
+      else
+        COMMANDS.fetch(name) { Client::Help }
+      end
+    end
+  end
+end

data/lib/spring/client/binstub.rb

@@ -0,0 +1,67 @@
+module Spring
+  module Client
+    class Binstub < Command
+      attr_reader :bindir, :name
+
+      def initialize(args)
+        super
+
+        @bindir = env.root.join("bin")
+        @name   = args[1]
+      end
+
+      def call
+        if Spring.command?(name)
+          bindir.mkdir unless bindir.exist?
+          generate_spring_binstub
+          generate_command_binstub
+        else
+          STDERR.puts "The '#{name}' command is not known to spring."
+          exit 1
+        end
+      end
+
+      def spring_binstub
+        bindir.join("spring")
+      end
+
+      def command_binstub
+        bindir.join(name)
+      end
+
+      def generate_spring_binstub
+        File.write(spring_binstub, <<'CODE')
+#!/usr/bin/env ruby
+
+# This is a special way of invoking the spring gem in order to
+# work around the performance issue discussed in
+# https://github.com/rubygems/rubygems/pull/435
+
+glob       = "{#{Gem::Specification.dirs.join(",")}}/spring-*.gemspec"
+candidates = Dir[glob].to_a.sort
+
+spec = Gem::Specification.load(candidates.last)
+
+if spec
+  spec.activate
+  load spec.bin_file("spring")
+else
+  STDERR.puts "Could not find spring gem in #{Gem::Specification.dirs.join(", ")}."
+  exit 1
+end
+CODE
+
+        spring_binstub.chmod 0755
+      end
+
+      def generate_command_binstub
+        File.write(command_binstub, <<CODE)
+#!/usr/bin/env bash
+exec $(dirname $0)/spring #{name} "$@"
+CODE
+
+        command_binstub.chmod 0755
+      end
+    end
+  end
+end