spring 0.0.1 → 0.0.2

data/README.md

@@ -1,29 +1,209 @@
 # Spring
 
-TODO: Write a gem description
+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
+[commands](https://github.com/rails/commands).
 
-## Installation
+I made it because we are having a discussion on the rails core team
+about shipping something to solve this problem with rails. So this is my
+proposal, as working code.
 
-Add this line to your application's Gemfile:
+(At least I hope it's working code, but this is alpha software at the
+moment. Please do try it and let me know if you hit problems.)
 
-    gem 'spring'
+## Features
 
-And then execute:
+Spring is most similar to Zeus, but it's implemented in pure Ruby, and
+is more tightly integrated with Rails (it makes use of Rails' built-in
+code reloader).
 
-    $ bundle
+Spring tries to be totally automatic.
+It boots up in the background the first time you run a
+command. Then it speeds up subsequent commands. If it detects that your
+pre-loaded environment has changed (maybe `config/application.rb` has
+been edited) then it will reload your environment in the background,
+ready for the next command. When you close your terminal session, Spring
+will automatically shut down. There's no "server" to manually start and
+stop.
 
-Or install it yourself as:
+Spring operates via a command line interface. Other solutions (e.g.
+commands) take the approach of using a special console to run commands
+from. This means we will have to re-implement shell features such as
+history, completion, etc. Whilst it's not impossible to re-implement
+those features, it's unnecessary work and our re-implementation
+won't be as feature complete as a real shell. Using a real shell also
+prevents the user having to constantly jump between a terminal with a
+real shell and a terminal running the rails "commands console".
 
-    $ gem install spring
+## Compatibility
+
+At the moment only MRI 1.9.3 / Rails 3.2 is supported.
 
 ## Usage
 
-TODO: Write usage instructions here
+Add `spring` to your gemfile and do a `bundle`.
+
+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.
+
+For this walkthrough, I'm using the test app in the Spring repository:
+
+```
+cd /path/to/spring/test/apps/rails-3-2
+```
+
+We can run a test:
+
+```
+$ time spring test test/functional/posts_controller_test.rb
+Run options:
+
+# Running tests:
+
+.......
+
+Finished tests in 0.169882s, 41.2051 tests/s, 58.8644 assertions/s.
+
+7 tests, 10 assertions, 0 failures, 0 errors, 0 skips
+
+real	0m1.858s
+user	0m0.184s
+sys	0m0.067s
+```
+
+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 -r bundler/setup /home/turnip/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/spring-0.0.1/lib/spring/server.rb
+ 8698 pts/6    Sl     0:02 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup /home/turnip/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/spring-0.0.1/lib/spring/server.rb
+```
+
+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:
+
+```
+$ time spring test test/functional/posts_controller_test.rb
+Run options:
+
+# Running tests:
+
+.......
+
+Finished tests in 0.162963s, 42.9546 tests/s, 61.3637 assertions/s.
+
+7 tests, 10 assertions, 0 failures, 0 errors, 0 skips
+
+real	0m0.492s
+user	0m0.179s
+sys	0m0.063s
+```
+
+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.
+
+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`:
+
+```
+$ touch config/application.rb
+$ ps ax | grep spring
+ 8692 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup /home/turnip/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/spring-0.0.1/lib/spring/server.rb
+ 8876 pts/6    Sl     0:00 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup /home/turnip/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/spring-0.0.1/lib/spring/server.rb
+```
+
+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.
+
+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
+    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.763s
+user	0m0.185s
+sys	0m0.063s
+```
+
+We now have 3 processes: the server, and application in test mode and
+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 -r bundler/setup /home/turnip/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/spring-0.0.1/lib/spring/server.rb
+ 8876 pts/6    Sl     0:15 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup /home/turnip/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/spring-0.0.1/lib/spring/server.rb
+ 9088 pts/6    Sl     0:01 /home/turnip/.rbenv/versions/1.9.3-p194/bin/ruby -r bundler/setup /home/turnip/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/spring-0.0.1/lib/spring/server.rb
+```
+
+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
+```
+
+## Commands
+
+The following commands are shipped by default.
+
+Custom commands can be specified in `config/initializers/spring.rb`. See
+[`lib/spring/commands.rb`](https://github.com/jonleighton/spring/blob/master/lib/spring/commands.rb)
+for examples.
+
+### `test`
+
+Runs a test (e.g. Test::Unit, MiniTest::Unit, etc.) Preloads the `test_helper` file.
+
+### `rspec`
+
+Runs an rspec spec, exactly the same as the `rspec` executable. Preloads
+the `spec_helper` file.
+
+### `rake`
+
+Runs a rake task.
+
+### `console`
+
+Boots into the Rails console. Currently this is usable but not perfect,
+for example you can't scroll back through command history. (That will be
+fixed.)
+
+### `generate`
+
+Runs a Rails generator.
 
-## Contributing
+### `runner`
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+The Rails runner.

data/lib/spring/commands.rb

@@ -1,5 +1,3 @@
-# TODO: Need a way for applications to add their own commands.
-
 class Spring
   @commands = {}
 
@@ -15,6 +13,12 @@ class Spring
     commands.fetch name
   end
 
+  # Load custom commands, if any
+  begin
+    require "./config/initializers/spring"
+  rescue LoadError
+  end
+
   module Commands
     class Test
       def env

data/lib/spring/version.rb

@@ -1,3 +1,3 @@
 class Spring
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/test/acceptance/app_test.rb

@@ -195,4 +195,8 @@ class AppTest < ActiveSupport::TestCase
       File.write(application, application_contents)
     end
   end
+
+  test "custom commands" do
+    assert_stdout "#{BINFILE} custom", "omg"
+  end
 end

data/test/apps/rails-3-2/config/initializers/spring.rb

@@ -0,0 +1,7 @@
+class CustomCommand
+  def call(args)
+    puts "omg"
+  end
+end
+
+Spring.register_command "custom", CustomCommand

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spring
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -88,6 +88,7 @@ files:
 - test/apps/rails-3-2/config/initializers/mime_types.rb
 - test/apps/rails-3-2/config/initializers/secret_token.rb
 - test/apps/rails-3-2/config/initializers/session_store.rb
+- test/apps/rails-3-2/config/initializers/spring.rb
 - test/apps/rails-3-2/config/initializers/wrap_parameters.rb
 - test/apps/rails-3-2/config/locales/en.yml
 - test/apps/rails-3-2/config/routes.rb
@@ -181,6 +182,7 @@ test_files:
 - test/apps/rails-3-2/config/initializers/mime_types.rb
 - test/apps/rails-3-2/config/initializers/secret_token.rb
 - test/apps/rails-3-2/config/initializers/session_store.rb
+- test/apps/rails-3-2/config/initializers/spring.rb
 - test/apps/rails-3-2/config/initializers/wrap_parameters.rb
 - test/apps/rails-3-2/config/locales/en.yml
 - test/apps/rails-3-2/config/routes.rb
@@ -212,4 +214,3 @@ test_files:
 - test/apps/rails-3-2/vendor/plugins/.gitkeep
 - test/helper.rb
 - test/unit/application_watcher_test.rb
-has_rdoc: