spring 0.0.8 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ab103d29ee132ac8637c7ddca8d5c41fc567c31e
+  data.tar.gz: 88e600c6e1d59b4150625769f20f6d543958087c
+SHA512:
+  metadata.gz: 7b4d762562b8d4c1832bcec43819b6bcc6d9168473095fac089a743c0c421d4450f77e7c0a3cf31902256ed42a3d0fa57e7767cd4a0cf9d0bd55dc24c758f460
+  data.tar.gz: 9c929b2636980dc30486f475caeacb1f3de296420c22e9f0a52c67ce732a8953e28f1b090258a18456d210ce217610e8e4df8ffeb7a1a8ebd0e2b546554235ec

data/.travis.yml

@@ -2,3 +2,6 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
+env:
+  - RAILS_VERSION="~> 3.2.0"
+  - RAILS_VERSION="~> 4.0.0"

data/CHANGELOG.md

@@ -1,3 +1,116 @@
+## 1.0.0
+
+* Enterprise ready secret sauce added
+
+## 0.9.2
+
+* Bugfix: environment variables set by bundler (`BUNDLE_GEMFILE`,
+  `RUBYOPT`, etc...) were being removed from the environment.
+* Ensure we only run the code reloader when files have actually changed.
+  This issue became more prominent with Rails 4, since Rails 4 will now
+  reload routes whenever the code is reloaded (see
+  https://github.com/rails/rails/commit/b9b06daa915fdc4d11e8cfe11a7175e5cd8f104f).
+* Allow spring to be used in a descendant directory of the application
+  root
+* Use the system tmpdir for our temporary files. Previously we used
+  `APP_ROOT/tmp/spring`, which caused problems on filesystems which did
+  not support sockets, and also caused problems if `APP_ROOT` was
+  sufficiently deep in the filesystem to exhaust the operating system's
+  socket name limit. Hence we had a `SPRING_TMP_PATH` environment
+  variable for configuration. We now use `/tmp/spring/[md5(APP_ROOT)]`
+  for the socket and `/tmp/spring/[md5(APP_ROOT)].pid` for the pid file.
+  Thanks @Kriechi for the suggestion. Setting `SPRING_TMP_PATH` no longer
+  has any effect.
+
+## 0.9.1
+
+* Environment variables which were created during application startup are no
+  longer overwritten.
+* Support for generating multiple binstubs at once. Use --all to
+  generate all, otherwise you can pass multiple command names to the
+  binstub command.
+* The `testunit` command has been extracted to the
+  `spring-commands-testunit` gem, because it's not necessary in Rails 4,
+  where you can just run `rake test path/to/test`.
+* The `~/.spring.rb` config file is loaded before bundler, so it's a good
+  place to require extra commands which you want to use in all projects,
+  without having to add those commands to the Gemfile of each individual
+  project.
+* Any gems in the bundle with names which start with "spring-commands-"
+  are now autoloaded. This makes it less faffy to add additional
+  commands.
+
+## 0.9.0
+
+* Display spring version in the help message
+* Remove workaround for Rubygems performance issue. This issue is solved
+  with Rubygems 2.1, so we no longer need to generate a "spring" binstub
+  file. We warn users if they are not taking advantage of the Rubygems
+  perf fix (e.g. if they are not on 2.1, or haven't run `gem pristine
+  --all`). To upgrade, delete your `bin/spring` and re-run `spring
+  binstub` for each of your binstubs.
+* Binstubs now fall back to non-spring execution of a command if the
+  spring gem is not present. This might be useful for production
+  environments.
+* The ENV will be replaced on each run to match the ENV which exists
+  when the spring command is actually run (rather than the ENV which
+  exists when spring first starts).
+* Specifying the rails env after the rake command (e.g. `rake
+  RAILS_ENV=test db:migrate`) now works as expected.
+* Provide an explicit way to set the environment to use when running
+  `rake` on its own.
+* The `rspec` and `cucumber` commands are no longer shipped by default.
+  They've been moved to the `spring-commands-rspec` and
+  `spring-commands-cucumber` gems.
+
+## 0.0.11
+
+* Added the `rails destroy` command.
+* Global config file in `~/.spring.rb`
+* Added logging for debugging. Specify a log file with the
+  `SPRING_LOG` environment variable.
+* Fix hang on "Run `bundle install` to install missing gems"
+* Added hack to make backtraces generated when running a command
+  quieter (by stripping out all of the lines relating to spring)
+* Rails 4 is officially supported
+
+## 0.0.10
+
+* Added `Spring.watch_method=` configuration option to switch between
+  polling and the `listen` gem. Previously, we used the `listen` gem if
+  it was available, but this makes the option explicit. Set
+  `Spring.watch_method = :listen` to use the listen gem.
+* Fallback when Process.fork is not available. In such cases, the user
+  will not receive the speedup that Spring provides, but won't receive
+  an error either.
+* Don't preload `test_helper` or `spec_helper` by default. This was
+  causing people subtle problems (for example see #113) and is perhaps
+  surprising behaviour. It may be desirable but it depends on the
+  application, therefore we suggest it to people in the README but no
+  longer do it by default.
+* Don't stay connected to database in the application processes. There's
+  no need to keep a connection open.
+* Avoid using the database in the application processes. Previously,
+  reloading the autoloaded constants would inadvertantly cause a
+  connection to the database, which would then prevent tasks like
+  db:create from running (because at that point the database doesn't
+  exist)
+* Removed ability to specify list of files for a command to preload. We
+  weren't using this any more internally, and this is easy to do by
+  placing requires in suitable locations in the Rails boot process
+  (which is not explained in the README).
+* Seed the random number generator on each run.
+
+## 0.0.9
+
+* Added `Spring::Commands::Rake.environment_matchers` for matching
+  rake tasks to specific environments.
+* Kill the spring server when the `Gemfile` or `Gemfile.lock` is
+  changed. This forces a new server to boot up on the next run, which
+  ensures that you get the correct gems (or the correct error message from
+  bundler if you have forgotten to `bundle install`.)
+* Fixed error when `Spring.watch` is used in `config/spring.rb`
+
 ## 0.0.8
 
 * Renamed `spring test` to `spring testunit`.

data/Gemfile

@@ -3,6 +3,4 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in spring.gemspec
 gemspec
 
-gem 'listen', :require => false
-gem 'rb-inotify', :require => false
-gem 'rb-fsevent', :require => false
+gem 'listen', "~> 1.0", :require => false

data/README.md

@@ -2,72 +2,45 @@
 
 [![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
-[commands](https://github.com/rails/commands).
-
-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.
-
-(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.)
+Spring is a Rails application preloader. It speeds up development by
+keeping your application running in the background so you don't need to
+boot it every time you run a test, rake task or migration.
 
 ## Features
 
-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).
-
-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.
-
-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".
+* Totally automatic; no need to explicitly start and stop the background process
+* Reloads your application code on each run
+* Restarts your application when configs / initializers / gem
+  dependencies are changed
 
 ## Compatibility
 
-Ruby versions supported:
-
-* MRI 1.9.3
-* MRI 2.0.0
+* Ruby versions: MRI 1.9.3, MRI 2.0.0
+* Rails versions: 3.2, 4.0
 
-Rails versions supported:
+Spring makes extensive use of `Process#fork`, so won't be able to
+provide a speed up on platforms which don't support forking (Windows, JRuby).
 
-* 3.2
+## Walkthrough
 
-Spring makes extensive use of `Process#fork`, so won't be able to run on
-any platform which doesn't support that (Windows, JRuby).
+Either `gem install spring` or add it to your Gemfile:
 
-## Usage
-
-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.
+``` ruby
+group :development do
+  gem "spring"
+end
+```
 
-For this walkthrough, I'm using the test app in the Spring repository:
+Spring is designed to be used *without* bundle exec, so use `spring
+[command]` rather than `bundle exec spring [command]`.
 
-```
-cd /path/to/spring/test/apps/rails-3-2
-```
+For this walkthrough I've generated a new Rails application, and run
+`rails generate scaffold posts name:string`.
 
-We can run a test:
+Let's run a test:
 
 ```
-$ time spring testunit test/functional/posts_controller_test.rb
+$ time spring rake test test/functional/posts_controller_test.rb
 Run options:
 
 # Running tests:
@@ -78,29 +51,26 @@ Finished tests in 0.127245s, 55.0121 tests/s, 78.5887 assertions/s.
 
 7 tests, 10 assertions, 0 failures, 0 errors, 0 skips
 
-real	0m2.165s
-user	0m0.281s
-sys	0m0.066s
+real    0m2.165s
+user    0m0.281s
+sys     0m0.066s
 ```
 
-That booted our app in the background:
+That wasn't particularly fast because it was the first run, so spring
+had to boot the application. It's now running:
 
 ```
 $ spring status
 Spring is running:
 
-26150 spring server | rails-3-2 | started 3 secs ago
-26155 spring app    | rails-3-2 | started 3 secs ago | test mode
+26150 spring server | spring-demo-app | started 3 secs ago
+26155 spring app    | spring-demo-app | started 3 secs ago | 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 test is faster next time:
+The next run is faster:
 
 ```
-$ time spring testunit test/functional/posts_controller_test.rb
+$ time spring rake test test/functional/posts_controller_test.rb
 Run options:
 
 # Running tests:
@@ -111,77 +81,53 @@ 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.610s
-user	0m0.276s
-sys	0m0.059s
+real    0m0.610s
+user    0m0.276s
+sys     0m0.059s
 ```
 
-Running `spring testunit`, `spring rake`, `spring rails`, 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.
+Writing `spring` before every command gets a bit tedious. Spring binstubs solve this:
 
-Spring binstubs solve both of these problems. If you will be running the
-`testunit` command regularly, run:
-
-```
-$ spring binstub testunit
 ```
-
-This generates a `bin/spring` and a `bin/testunit`, which allows you to run
-`spring` and `spring testunit` in a way that doesn't trigger the Rubygems
-performance bug:
-
+$ spring binstub rake rails
 ```
-$ time bin/testunit test/functional/posts_controller_test.rb
-Run options:
-
-# Running tests:
-
-.......
 
-Finished tests in 0.166585s, 42.0207 tests/s, 60.0296 assertions/s.
+This will generate `bin/rake` and `bin/rails`. They
+replace any binstubs that you might already have in your `bin/`
+directory. Check them in to source control.
 
-7 tests, 10 assertions, 0 failures, 0 errors, 0 skips
-
-real	0m0.407s
-user	0m0.077s
-sys	0m0.059s
-```
+If you don't want to prefix every command you type with `bin/`, you
+can [use direnv](https://github.com/zimbatm/direnv) to automatically add
+`./bin` to your `PATH` when you `cd` into your application.
 
-You can add "./bin" to your `PATH` when in your application's directory
-[with direnv](https://github.com/zimbatm/direnv), but you should
-recognise and understand the security implications of using that.
+If we edit any of the application files, or test files, the changes will
+be picked up on the next run without the background process having to
+restart. This works in exactly the same way as the code reloading
+which allows you to refresh your browser and instantly see changes during
+development.
 
-If we edit any of the application files, or test files, the change will
-be picked up on the next run, without the background process
-having to be restarted.
+But if we edit any of the files which were used to start the application
+(configs, initializers, your gemfile), the application needs to be fully
+restarted. This happens automatically.
 
-If we edit any of the preloaded files, the application needs to restart
-automatically. Let's "edit" `config/application.rb`:
+Let's "edit" `config/application.rb`:
 
 ```
 $ touch config/application.rb
 $ spring status
 Spring is running:
 
-26150 spring server | rails-3-2 | started 36 secs ago
-26556 spring app    | rails-3-2 | started 1 sec ago | test mode
+26150 spring server | spring-demo-app | started 36 secs ago
+26556 spring app    | spring-demo-app | started 1 sec ago | 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 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.
+The application detected that `config/application.rb` changed and
+automatically restarted itself.
 
-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:
+If we run a command that uses a different environment, then that
+environment gets booted up:
 
 ```
-$ spring binstub rake
 $ bin/rake routes
     posts GET    /posts(.:format)          posts#index
           POST   /posts(.:format)          posts#create
@@ -190,24 +136,21 @@ 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
-```
-
-We now have 3 processes: the server, and application in test mode and
-the application in development mode.
 
-```
-$ bin/spring status
+$ spring status
 Spring is running:
 
-26150 spring server | rails-3-2 | started 1 min ago
-26556 spring app    | rails-3-2 | started 42 secs ago | test mode
-26707 spring app    | rails-3-2 | started 2 secs ago | development mode
+26150 spring server | spring-demo-app | started 1 min ago
+26556 spring app    | spring-demo-app | started 42 secs ago | test mode
+26707 spring app    | spring-demo-app | started 2 secs ago | development mode
 ```
 
-To stop the background processes:
+There's no need to "shut down" spring. This will happen automatically
+when you close your terminal. However if you do want to do a manual shut
+down, use the `stop` command:
 
 ```
-$ bin/spring stop
+$ spring stop
 Spring stopped.
 ```
 
@@ -215,34 +158,34 @@ Spring stopped.
 
 The following commands are shipped by default.
 
-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)
+Custom commands can be specified in the Spring config file. See
+[`lib/spring/commands/`](https://github.com/jonleighton/spring/blob/master/lib/spring/commands/)
 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.
-
-### `testunit`
-
-Runs a test (e.g. Test::Unit, MiniTest::Unit, etc.) Preloads the `test_helper` file.
+You can add the following gems to your Gemfile for additional commands:
 
-This command can also recursively run a directory of tests. For example,
-`spring testunit test/functional` will run `test/functional/**/*_test.rb`.
+* [spring-commands-rspec](https://github.com/jonleighton/spring-commands-rspec)
+* [spring-commands-cucumber](https://github.com/jonleighton/spring-commands-cucumber)
+* [spring-commands-testunit](https://github.com/jonleighton/spring-commands-testunit) - useful for
+  running `Test::Unit` tests on Rails 3, since only Rails 4 allows you
+  to use `rake test path/to/test` to run a particular test/directory.
 
-### `rspec`
-
-Runs an rspec spec, exactly the same as the `rspec` executable. Preloads
-the `spec_helper` file.
-
-### `cucumber`
+### `rake`
 
-Runs a cucumber feature.
+Runs a rake task. Rake tasks run in the `development` environment by
+default. You can change this on the fly by using the `RAILS_ENV`
+environment variable. The environment is also configurable with the
+`Spring::Commands::Rake.environment_matchers` hash. This has sensible
+defaults, but if you need to match a specific task to a specific
+environment, you'd do it like this:
 
-### `rake`
+``` ruby
+Spring::Commands::Rake.environment_matchers["perf_test"] = "test"
+Spring::Commands::Rake.environment_matchers[/^perf/]     = "test"
 
-Runs a rake task.
+# To change the environment when you run `rake` with no arguments
+Spring::Commands::Rake.environment_matchers[:default] = "development"
+```
 
 ### `rails console`, `rails generate`, `rails runner`
 
@@ -253,39 +196,38 @@ speed-up).
 
 ## Configuration
 
-### application_root
+Spring will read `~/.spring.rb` and `config/spring.rb` for custom
+settings. Note that `~/.spring.rb` is loaded *before* bundler, but
+`config/spring.rb` is loaded *after* bundler. So if you have any
+`spring-commands-*` gems installed that you want to be available in all
+projects without having to be added to the project's Gemfile, require
+them in your `~/.spring.rb`.
+
+### Application root
 
-Spring must know how to find your rails application. If you have a
+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'
 ```
 
-### preload files
-
-Every Spring command has the ability to preload a set of files. The
-`test` command for example preloads `test_helper` (it also adds the
-`test/` directory to your load path). If the
-defaults don't work for your application you can configure the
-preloads for every command:
-
-```ruby
-# if your test helper is called "helper"
-Commands::Command::TestUnit.preloads = %w(helper)
+### Running code before forking
 
-# if you don't want to preload spec_helper.rb
-Commands::Command::RSpec.preloads = []
+There is no `Spring.before_fork` callback. To run something before the
+fork, you can place it in `~/.spring.rb` or `config/spring.rb` or in any of the files
+which get run when your application initializers, such as
+`config/application.rb`, `config/environments/*.rb` or
+`config/initializers/*.rb`.
 
-# if you want to preload additional files for the console
-Commands::Command::RailsConsole.preloads << 'extenstions/console_helper'
-```
+For example, if loading your test helper is slow, you might like to
+preload it to speed up your test runs. To do this you could put a
+`require Rails.root.join("test/helper")` in
+`config/environments/test.rb`.
 
-### after fork callbacks
+### Running code after forking
 
 You might want to run code after Spring forked off the process but
 before the actual command is run. You might want to use an
@@ -301,35 +243,35 @@ end
 If you want to register multiple callbacks you can simply call
 `Spring.after_fork` multiple times with different blocks.
 
-### 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.
-
 ### Watching files and directories
 
-As mentioned above, Spring will automatically detect file changes to any file loaded when the server
-boots. If you would like to watch additional files or directories, use
-`Spring.watch`:
+Spring will automatically detect file changes to any file loaded when the server
+boots. Changes will cause the affected environments to be restarted.
+
+If there are additional files or directories which should trigger an
+application restart, you can specify them with `Spring.watch`:
 
 ```ruby
-Spring.watch "#{Rails.root}/spec/factories"
+Spring.watch "spec/factories"
 ```
 
-### Filesystem polling
-
-By default Spring will check the filesystem for changes once every 0.2 seconds. This
+By default Spring polls the filesystem for changes once every 0.2 seconds. This
 method requires zero configuration, but if you find that it's using too
-much CPU, then you can turn on event-based file system listening by
-adding the following to to your `Gemfile`:
+much CPU, then you can turn on event-based file system listening:
 
 ```ruby
-group :development, :test do
-  gem 'listen'
-  gem 'rb-inotify', :require => false  # linux
-  gem 'rb-fsevent', :require => false  # mac os x
-  gem 'rb-kqueue',  :require => false  # bsd
-end
+Spring.watch_method = :listen
 ```
 
-Note that this make the initial application startup slightly slower.
+You may need to add the [`listen` gem](https://github.com/guard/listen) to your `Gemfile`.
+
+## Troubleshooting
+
+If you want to get more information about what spring is doing, you can
+specify a log file with the `SPRING_LOG` environment variable:
+
+```
+spring stop # if spring is already running
+export SPRING_LOG=/tmp/spring.log
+spring rake -T
+```

data/bin/spring

@@ -1,4 +1,31 @@
 #!/usr/bin/env ruby
 
+if defined?(Gem)
+  if Gem::Version.new(Gem::VERSION) < Gem::Version.new("2.1.0")
+    warn "Warning: You're using Rubygems #{Gem::VERSION} with Spring. " \
+         "Upgrade to at least Rubygems 2.1.0 and run `gem pristine --all` for better " \
+         "startup performance."
+  else
+    stubs = Gem::Specification.stubs.grep(Gem::StubSpecification)
+
+    # stubbed? method added in https://github.com/rubygems/rubygems/pull/694
+    if Gem::Specification.stubs.first.respond_to?(:stubbed?)
+      unstubbed = stubs.reject(&:stubbed?)
+    else
+      unstubbed = stubs.reject { |s| s.send(:data).is_a?(Gem::StubSpecification::StubLine) }
+    end
+
+    # `gem pristine --all` ignores default gems. it doesn't really matter,
+    # as there are probably not many of them on the system.
+    unstubbed.reject!(&:default_gem?)
+
+    if unstubbed.any?
+      warn "Warning: Running `gem pristine --all` to regenerate your installed gemspecs " \
+           "will improve the startup performance of Spring."
+    end
+  end
+end
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
 require 'spring/client'
 Spring::Client.run(ARGV)