engineer 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009-2010 Phil Smith
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,336 @@
+= Engineer
+
+It makes engines, get it?
+
+== Explanation
+
+Engines are rails apps which can be run from inside other rails apps.
+
+Engineer is a small gem that lets a sufficiently normal rails application quickly become an
+engine.  It provides necessary bits of engine anatomy, and also gives the engine author a way to
+publish changes (such as migrations) to users as the engine evolves.  This has been a sticking
+point in the past, and is one of the few remaining areas of engine support not yet covered by
+rails itself.
+
+Engineer targets rails 3 engines hosted inside rails 3 applications.  If you are looking for rails
+2.3 support, try the engines plugin (http://rails-engines.org).
+
+== Getting Started
+
+Let's say you have a new rails app named +my_engine+ that you wish to package as an engine.  Drop
+this in your +Gemfile+ and do the bundler thing:
+
+<tt>gem "engineer"</tt>
+
+A new generator named <tt>engineer:install</tt> will be available; run it.
+ $ rails g engineer:install
+       exist  lib
+      create  lib/my_engine/engine.rb
+      create  lib/my_engine.rb
+      create  lib/generators/my_engine/install/install_generator.rb
+      create  lib/generators/my_engine/install/templates/my_engine.rake
+      create  lib/generators/my_engine/install/USAGE
+      create  app/controllers/my_engine
+      create  app/controllers/my_engine/application_controller.rb
+      remove  app/controllers/application_controller.rb
+      append  Rakefile
+        gsub  config/routes.rb
+
+The two major take-aways from this are
+1. <tt>application_controller.rb</tt> has moved under +my_engine+.
+2. Your +Rakefile+ has grown a bit.
+
+The Gory Details below explain more deeply, but for now let's just look at the new +Rakefile+
+content:
+ $ cat Rakefile
+  # ...
+
+  Engineer::Tasks.new do |gem|
+    gem.name = "my_engine"
+    gem.summary = %Q{TODO: one-line summary of your engine}
+    gem.description = %Q{TODO: longer description of your engine}
+    gem.email = "TODO"
+    gem.homepage = "TODO"
+    gem.authors = ["TODO"]
+    gem.require_path = 'lib'
+    gem.files =  FileList[
+      "[A-Z]*",
+      "{app,config,lib,public,spec,test,vendor}/**/*",
+      "db/**/*.rb"
+    ]
+
+    # Include Bundler dependencies
+    Bundler.definition.dependencies.each do |dependency|
+      next if dependency.name == "engineer"
+
+      if (dependency.groups & [:default, :production, :staging]).any?
+        gem.add_dependency dependency.name, *dependency.requirement.as_list
+      else
+        gem.add_development_dependency dependency.name, *dependency.requirement.as_list
+      end
+    end
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+If you've used jeweler (http://github.com/technicalpickles/jeweler) before, this should look
+eerily familiar.  Engineer engines are shipped as gems, so engineer throws a (very light) wrapper
+around jeweler for wrangling the gem-related tasks.  Jeweler in turn keeps your gem's metadata in
+the +Rakefile+, so here it is.
+
+<b>Unlike jeweler, dependencies should still be declared in +Gemfile+, and not here.</b>
+
+As you can see, your bundler dependencies will be included in the generated gemspec.
+
+Let's make a gem:
+ $ rake build
+  (in /Users/phil/Public/code/my_engine)
+  Expected VERSION or VERSION.yml to exist. See version:write to create an initial one.
+
+Whoops.  Our gem needs to know what version it is, and we haven't told it.  Start off at 0.0.0 by
+ $ rake version:write
+  (in /Users/phil/Public/code/my_engine)
+  Updated version: 0.0.0
+
+ $ rake build
+  (in /Users/phil/Public/code/my_engine)
+  Generated: my_engine.gemspec
+  my_engine.gemspec is valid.
+  rake aborted!
+  "FIXME" or "TODO" is not an author
+
+  (See full trace by running task with --trace)
+
+Doh.  Remember all those TODOs (summary, author, etc) in the Rakefile metadata?  Go fill those out.
+
+Once more:
+ $ rake build
+  (in /Users/phil/Public/code/my_engine)
+  Generated: my_engine.gemspec
+  my_engine.gemspec is valid.
+  WARNING:  no rubyforge_project specified
+    Successfully built RubyGem
+    Name: my_engine
+    Version: 0.0.0
+    File: my_engine-0.0.0.gem
+
+There we go, there's an engine gem sitting in <tt>pkg/</tt>, go nuts.  See jeweler's documentation
+for managing the version, pushing to gemcutter and other goodies.
+
+== Installing Engine Gems
+
+How about the other side of the fence?  To install an engine into a host application, the host
+author follows a similar workflow.
+
+First, add a line to the +Gemfile+ and call bundler:
+
+<tt>gem "my_engine"</tt>
+
+A new generator will be available, named <tt>my_engine:install</tt>; run it.
+ $ rails g my_engine:install
+         exist  lib/tasks
+        create  lib/tasks/my_engine.rake
+          rake  my_engine:assets my_engine:db:schema my_engine:db:migrate
+  rm -rf /.../host/public/my_engine
+  ln -s /.../gems/my_engine-0.0.0/public /.../host/public/my_engine
+  mkdir -p db/migrate
+  cp /tmp/20100428232715_my_engine_schema_after_create_comments.rb /.../host/db/migrate/20100428232715_my_engine_schema_after_create_comments.rb
+
+This includes the engine's static assets in a subdirectory under the host's +public+.  Voodoo in
+the engine takes care of looking there for assets (see Gory Details below.)  If your OS is
+allergic to symlinks, the files are copied instead.
+
+The engine's schema is also added as a new database migration without running it.  The host author
+is free to take a peek at it before deciding to <tt>rake db:migrate</tt> for real.
+
+Run your pending migrations and fire up <tt>rails s</tt>, you're good to go.
+
+== Managing Engine Gems
+
+After installation, some new rake tasks are available:
+ $ rake -T my_engine
+  (in /Users/phil/Public/code/host)
+  rake my_engine:assets[copy]               # Link (or copy) my_engine's static assets
+  rake my_engine:db:migrate                 # Import my_engine's new db migrations
+  rake my_engine:db:schema                  # Import my_engine's schema as a db migration
+  rake my_engine:db:seed                    # Load my_engine's seed data
+  rake my_engine:update                     # Import my_engine's assets and new db migrations
+
+There are catch-all tasks as well:
+ $ rake -T engines
+  (in /Users/phil/Public/code/host)
+  rake engines:assets[copy]                 # Link (or copy) static assets from all engines
+  rake engines:db:migrate                   # Import new migrations from all engines
+  rake engines:db:seed                      # Load seed data from all engines
+  rake engines:update                       # Import assets and new db migrations from all engines
+
+These let the host author manage the newly-installed (or updated!) engine.  If the host
+application revs the version of the engine gem, any new engine db migrations can be imported into
+the host app with:
+ $ rake my_engine:db:migrate
+  (in /Users/phil/Public/code/host)
+  mkdir -p db/migrate
+  cp /tmp/20100428232715_my_engine_create_tags.rb /.../host/db/migrate/20100428232715_my_engine_create_tags.rb
+  cp /tmp/20100428232716_my_engine_create_taggings.rb /.../host/db/migrate/20100428232716_my_engine_create_taggings.rb
+
+As before, this doesn't actually run any engine migrations but instead copies new ones (with mild
+munging) to <tt>db/migrate</tt>.
+
+The engine's static assets (stylesheets, images and so on) can be updated with:
+ $ rake my_engine:assets
+  (in /Users/phil/Public/code/host)
+  rm -rf /Users/phil/Public/code/host/public/my_engine
+  ln -s /.../gems/my_engine-0.0.1/public /.../host/public/my_engine
+
+Even when using soft-links, updating the assets is important: you need the symlink pointing into
+the correct gem version.
+
+One can do both in a single shot with <tt>rake my_engine:update</tt>.  Or with
+<tt>rake engines:update</tt> to hit all engines at once.
+
+== Gory Details
+
+Rails' engine support has become robust with the release of rails 3.  There are still a few pain
+points which engineer tries to address.  It does so by making some decisions for you, the engine
+author.  In the spirit of openness, the introduced voodoo is not buried inside the engineer gem
+but copied into the engine app on installation.  It's your gem, feel free to tailor it to your
+needs.
+
+Some intrepid adventurers will ask for an explanation of the generated engine's internals; here is
+an overview.
+
+=== Database Migrations
+
+Engine database migrations are a tricky problem.  Luckily for me, some very clever people already
+hammered out a workable idea, which engineer implements.
+
+The migrations are packaged in the gem along with the rest of the engine.  When the host author
+updates the gem, she runs the <tt><engine_name>:db:migrate</tt> rake task (directly, or indirectly
+through <tt><engine_name>:update</tt>.)  This copies the engine migrations into the host
+application, changing a few things on the way.
+
+Specifically:
+1. The migration numbers are reassigned.
+2. The engine name is inserted into the new migration name.
+
+The numbers are reassigned so that the copied migrations preserve their relative order, and yet
+occur after all previous migrations in the host application.  This guarantees that the host
+application has a linear schema history, by making that history explicit.  Put another way, the
+final host migrations should reflect the evolution of the _host_ schema, not the _engine_ schema
+from which it was derived.
+
+The engine name is inserted to avoid name collisions.  It allows the engine to see what migrations
+have already been copied into the host app; it will not attempt to copy them again.  Changing the
+migration name implies changing the contained migration class name as well: the rake task will
+normally take care of it.
+
+Interested readers could also check out
+* The original discussion: https://rails.lighthouseapp.com/projects/8994/tickets/2058
+* James Adam's related blog post: http://interblah.net/plugin-migrations
+
+=== Schemas
+
+It is recommended practice to avoid running a long string of migrations when setting up a new
+database, since the migration process can become slow and brittle.  Analogously, engines should be
+able to (and can) create their schemas in the host database without running a long string of
+migrations.
+
+It is a very real use case for a host application author to add a new engine after the host schema
+has been created and deployed to production.  Deployment tools like cap and vlad know how to run
+pending migrations at the right time, but they don't understand (out of the box) how to run an
+engine-specific <tt>db:schema:load</tt>.  It would be really great if they didn't have to.
+
+Engineer engines satisfy these two requirements by importing the engine schema into the host
+application as a migration.  A naming convention is used to identify engine migrations that are
+implied by the schema: the schema migration will be named something like
++my_engine_schema_after_create_posts+.  This indicates that all engine migrations before (and
+including) +create_posts+ should be considered to be already run.  If there are no engine
+migrations to skip (because the engine author removed them) then the name +my_engine_schema+ is
+used instead.
+
+No effort is made to make this schema migration reversible.
+
+=== Seeding
+
+Similar to loading a schema, seeding initial database rows is another task that should only be run
+once per database.
+
+Engineer engines provide two ways to load the engine's <tt>db/seeds.rb</tt>.  The first is a rake
+task, which the host-level <tt>rake db:seed</tt> depends on.  This is meant for new databases
+being set up after the engine's schema has been incorporated into the host's.  All seed rows will
+be loaded together at the usual time, just as all the tables were created together.
+
+The other way seed data can be loaded is in a migration generated on engine installation.  This is
+appropriate for installing a new engine into an established application, such as in a production
+deploy.
+
+=== Static Assets and Asset Helpers
+
+Separation of assets is another issue facing engines.  While it is certainly useful to harness the
+host's layouts and styling, engines will inescapably need their own stylesheets, scripts, etc.
+
+Rails provides conventions about where those assets live and what they are named, and backs those
+conventions up with helpers that "just work."  The problem is (for example), the host and engine
+master stylesheets can't both live at <tt>public/stylesheets/application.css</tt>.  So we need two
+separate places to keep assets, and a way of hiding this separation when it is convenient.
+
+Many http servers serve static assets more efficiently than dynamic ones generated from frameworks
+like rails.  Any serious solution to the problem will need to respect this optimization.  So,
+assuming the web server wants to be dumb, the separate asset locations will be apparent in the
+URIs.  The browser only fetches the URIs the application gives it, so the application must know to
+render engine asset URIs for engine assets, and host asset URIs otherwise.  These URIs are created
+by asset tag helpers such as +image_tag+ and +stylesheet_link_tag+.
+
+An engine author could visit each tag and stick (for example) <tt>my_engine/</tt> in front of the
+asset names, but that stinks.  It also breaks the engine when run as a normal application.
+Instead, the asset helpers called by the engine must create engine asset URIs only when the engine
+is run as such.
+
+Enter +asset_path+.  This is an +action_controller+ configuration hook provided by rails to
+control how asset URIs are generated.  It can be set on a controller class, and it is inherited by
+subclasses.  By default, it provides rails' cache-busting ability (the <tt>?123line-noise456</tt>
+on the end of your stylesheet URIs.)  Engineer hijacks it to provide asset separation.
+
+Recall that engineer's install generator moves <tt>application_controller.rb</tt> into an
+engine-specific namespace: this is why.  On startup, a <tt>MyEngine::Engine</tt> initializer sets
+an +asset_path+ on <tt>MyEngine::ApplicationController</tt>.  Since this controller is no longer
+the global +ApplicationController+, we're ensured this +asset_path+ will affect not only all the
+engine controllers, but only them.  The initializers in <tt>MyEngine::Engine</tt> are only run
+when the application is started as an engine.  Thus when +my_engine+ is fired up as a normal
+application, the custom +asset_path+ is not used.
+
+Almost there.  +asset_path+ can take as value either a string template (such as
+<tt>"/my_engine%s"</tt>) or a lambda.  If the engine and host authors were not interested in
+sharing layouts and other views, <tt>"/my_engine%s"</tt> would be enough.  There, all asset tags
+rendered by any view from an engine controller will target the engine's assets.  This goes bad
+when an engine view wants to render with a host layout that includes a stylesheet: the stylesheet
+URI would point into the engine, not the host.
+
+A little more (and arguably too much) leg work can save us.  The flaw is that we want the
+customized URI not when requesting an engine _controller_, but when rendering an engine _view_.
+If you have one around, open up <tt>lib/my_engine/engine.rb</tt>.  There is another initializer in
+there that duck punches <tt>ActionView::Template#render</tt>.  When a template is rendered, its
++identifier+ is captured.  For templates loaded from files, this is a file system path descending
+from a <tt>config.paths.app.views</tt> of either the host or the engine.  Thus we can distinguish
+host templates from engine templates.  Engine assets are generated for engine views and non-file
+system views.
+
+== Running the Tests
+
+The (sparse) tests are written with cucumber (http://cukes.info) and can be run with just "rake".
+You may need to install jeweler first.
+
+== Thanks
+
+This tool would not exist if the road had not already been well-paved by many others.
+Specifically, James Adam's herculean effort in the rails 2.3 engines plugin has illuminated many
+issues and solutions.  Thanks also to the rails core team for incorporating many engine-centric
+ideas into the framework, vastly simplifying what this tool needs to do.  And also for just making
+an awesome framework.
+
+Finally, thanks to SEOmoz (http://seomoz.org) for letting me build this at my desk in the
+afternoons instead of on the couch in the middle of the night ^_^.
+
+== Copyright
+
+Copyright (c) 2009-2010 Philip Smith. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,62 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "engineer"
+    gem.summary = %Q{Turn rails 3 applications into engines}
+    gem.description = "Turn your rails 3 app into an embeddable engine gem, with answers for db "\
+      "migrations, static assets and more."
+    gem.email = "phil.h.smith@gmail.com"
+    gem.homepage = "http://github.com/phs/engineer"
+    gem.authors = ["Phil Smith"]
+    gem.files =  FileList["[A-Z]*", "{features,lib,spec}/**/*"]
+    gem.add_dependency "jeweler", ">= 1.4.0"
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "cucumber", ">= 0.6.4"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => [:spec, :cucumber]
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "engineer #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new do |t|
+  t.cucumber_opts = %w{--format pretty}
+end
+
+desc "Remove build products"
+task :clean do
+  rm_rf 'pkg'
+end
+
+# Some steps expect the gem to be built, so it can be added to rails projects created in tests.
+task :cucumber => [:clean, :build]

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/features/engine_rake_tasks.feature

@@ -0,0 +1,55 @@
+Feature: Rake Tasks added to Engines
+  As an engine author
+  I want to pack my app as a gem the same way I do with jeweler
+  Since I probably already know how to use jeweler
+  
+  Background:
+    Given I have a new rails app named my_engine, with the engineer gem
+    And I rails g engineer:install
+  
+  Scenario: Creating initial VERSION file
+    When I try to rake version:bump:patch
+    Then I should see output:
+      """
+      Expected VERSION or VERSION.yml to exist. See version:write to create an initial one.
+      """
+    
+    When I rake version:write
+    Then VERSION should contain:
+      """
+      0.0.0
+      """
+  
+  Scenario: Bumping versions
+    Given I rake version:write
+    When I rake version:bump:patch
+    Then I should see output:
+      """
+      Current version: 0.0.0
+      Updated version: 0.0.1
+      """
+  
+    When I rake version:bump:major
+    Then I should see output:
+      """
+      Current version: 0.0.1
+      Updated version: 1.0.0
+      """
+  
+  Scenario: Building a gem
+    Given I rake version:write
+    And I fill out my Rakefile gemspec
+    When I rake build
+    Then I should see a my_engine.gemspec file
+    And I should see a pkg/my_engine-0.0.0.gem file
+
+    And my_engine.gemspec should contain:
+      """
+            s.add_runtime_dependency(%q<rails>, ["${VERSION}"])
+            s.add_runtime_dependency(%q<sqlite3-ruby>, ["${VERSION}"])
+      """
+
+    And my_engine.gemspec should not contain:
+      """
+            s.add_runtime_dependency(%q<engineer>, ["${VERSION}"])
+      """

data/features/engineer_install_generator.feature

@@ -0,0 +1,47 @@
+Feature: Engineer Installation
+  As an engine author
+  I want to install engineer painlessly
+  So that I can turn my rails app into an embeddable engine
+  
+  Background:
+    Given I have a new rails app named my_engine, with the engineer gem
+  
+  Scenario: Install engineer, see my new rake tasks
+    When I rails g engineer:install
+    Then I should see output:
+      """
+             exist  lib
+            create  lib/my_engine/engine.rb
+            create  lib/my_engine.rb
+            create  lib/generators/my_engine/install/install_generator.rb
+            create  lib/generators/my_engine/install/templates/my_engine.rake
+            create  lib/generators/my_engine/install/USAGE
+            create  app/controllers/my_engine
+            create  app/controllers/my_engine/application_controller.rb
+            remove  app/controllers/application_controller.rb
+            append  Rakefile
+              gsub  config/routes.rb
+      """
+
+    And config/routes.rb should contain:
+      """
+      Rails.application.routes.draw
+      """
+
+    And app/controllers/my_engine/application_controller.rb should contain:
+      """
+      class MyEngine::ApplicationController
+      """
+
+    When I rake -T
+    Then I should see output:
+      """
+      rake build                                # Build gem
+      """
+    And I should see output:
+      """
+      rake version:bump:major                   # Bump the gemspec by a major version.
+      rake version:bump:minor                   # Bump the gemspec by a minor version.
+      rake version:bump:patch                   # Bump the gemspec by a patch version.
+      rake version:write                        # Writes out an explicit version.
+      """

data/features/host_install_generator.feature

@@ -0,0 +1,54 @@
+Feature: Engine Installation into a Host App
+  As an host application author
+  I want to install an engine painlessly
+  So that I can use it in my app
+
+  Background:
+    Given I have a finished engine application named my_engine
+    And I have a new rails app named host, with the my_engine gem
+
+  Scenario: Install my_engine
+    When I rails g --help
+    Then I should see output:
+      """
+        my_engine:install
+      """
+
+    When I rails g my_engine:install
+    Then I should see output:
+      """
+             exist  lib/tasks
+            create  lib/tasks/my_engine.rake
+              rake  my_engine:install
+      """
+
+    And I should see output:
+      """
+      rm -rf /${HOST_PATH}/host/public/my_engine
+      ln -s /${GEM_REPO}/gems/my_engine-0.0.0/public /${HOST_PATH}/host/public/my_engine
+      """
+
+    When I rake -T
+    Then I should see output:
+      """
+      rake my_engine:assets[copy]               # Link (or copy) my_engine's static assets
+      rake my_engine:db:migrate                 # Import my_engine's new db migrations
+      rake my_engine:db:schema                  # Import my_engine's schema as a db migration
+      rake my_engine:db:seed                    # Load my_engine's seed data
+      rake my_engine:update                     # Import my_engine's assets and new db migrations
+      """
+
+    And I should see output:
+      """
+      rake engines:assets[copy]                 # Link (or copy) static assets from all engines
+      rake engines:db:migrate                   # Import new migrations from all engines
+      rake engines:db:seed                      # Load seed data from all engines
+      rake engines:update                       # Import assets and new db migrations from all engines
+      """
+
+    When I rake my_engine:assets[true]
+    Then I should see output:
+      """
+      rm -rf /${HOST_PATH}/host/public/my_engine
+      cp -r /${GEM_REPO}/gems/my_engine-0.0.0/public /${HOST_PATH}/host/public/my_engine
+      """

data/features/support/env.rb

@@ -0,0 +1,153 @@
+# Inspiration shamelessly stolen from
+# http://gravityblast.com/2009/08/11/testing-rails-generators-with-cucumber/
+
+require "rubygems"
+gem "railties", ">= 3.0.0.beta2"
+
+require "fileutils"
+require "tempfile"
+
+class String
+  def strip_ansi
+    gsub /\e\[\d+m/, ''
+  end
+end
+
+PROJECT_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..', '..'))
+ENGINEER_GEM_FILE = Dir["#{PROJECT_ROOT}/pkg/engineer*gem"].first
+
+if ENV['VERBOSE'] == 'true'
+  include FileUtils::Verbose
+else
+  include FileUtils
+end
+
+module Helpers
+  def generate_rails_app(name = 'rails_app', gem_files = [])
+    @current_app = name
+
+    unless File.exists?(in_workspace "apps", name)
+      in_workspace "apps" do
+        run "rails #{name}"
+      end
+
+      in_workspace "apps", @current_app do
+        gem_files.each do |gem_file|
+          gem_name, version = File.basename(gem_file).match(/(.*)-(\d+\.\d+\.\d+)\.gem/)[1..2]
+          install_gem gem_file
+          File.open('Gemfile', 'a') do |gemfile|
+            gemfile << "gem '#{gem_name}', '#{version}'\n"
+          end
+        end
+
+        run "#{gem_home} bundle install"
+      end
+    end
+
+    cp_r in_workspace("apps", @current_app), in_current_app
+  end
+
+  def generate(generator, options = {})
+    in_current_app do
+      run "#{gem_home} bundle exec rails g #{generator}", options
+    end
+  end
+
+  def rake(rake_task, options = {})
+    in_current_app do
+      run "#{gem_home} bundle exec rake #{rake_task}", options
+    end
+  end
+
+  def fill_out_the_rakefile_gemspec
+    in_current_app do
+      rakefile = File.read('Rakefile')
+      rakefile.gsub!(
+        '%Q{TODO: one-line summary of your engine}',   '%Q{My awesome engine}')
+      rakefile.gsub!(
+        '%Q{TODO: longer description of your engine}', '%Q{My awesome, beautiful engine}')
+      rakefile.gsub!('gem.email = "TODO"',     'gem.email = "me@example.com"')
+      rakefile.gsub!('gem.homepage = "TODO"',  'gem.homepage = "http://example.com/"')
+      rakefile.gsub!('gem.authors = ["TODO"]', 'gem.authors = ["Me"]')
+      File.open('Rakefile', 'w') { |f| f << rakefile }
+    end
+  end
+
+  def strip_wildcards(content)
+    Regexp.quote(content).gsub /\\\$\\\{[A-Z_]+\\\}/, '.*' # escaped ${WHAT_EVER} becomes .*
+  end
+
+  def latest_output
+    @latest_output
+  end
+
+private
+
+  def install_gem(gem_file)
+    @installed_gems ||= {}
+    @installed_gems[gem_file] ||= begin
+      run "#{gem_home} gem install --no-rdoc --no-ri #{gem_file}"
+      true
+    end
+  end
+
+  def run(cmd, options = {})
+    log cmd
+    (`#{cmd} 2>&1`).tap do |output|
+      @latest_output = output
+      log output
+      fail unless $?.to_i == 0 or options[:may_fail]
+    end
+  end
+
+  def in_workspace(*path)
+    absolute_path = File.join(WORKSPACE, *path)
+
+    if block_given?
+      Dir.chdir(absolute_path) do
+        log "cd #{absolute_path}"
+        yield
+      end
+    else
+      absolute_path
+    end
+  end
+
+  def in_current_scenario(*path, &block)
+    in_workspace "current_scenario", *path, &block
+  end
+
+  def in_current_app(*path, &block)
+    in_current_scenario @current_app, *path, &block
+  end
+
+  def gem_home
+    @gem_home ||= begin
+      repo_path = in_workspace 'gemrepo'
+      mkdir_p repo_path
+      "GEM_HOME='#{repo_path}'"
+    end
+  end
+
+  def log(message)
+    puts message if ENV['VERBOSE'] == 'true'
+  end
+
+end
+
+# TODO join from Dir::tmpdir after https://rails.lighthouseapp.com/projects/8994/tickets/4442
+WORKSPACE = File.join("/tmp", "engineer-cucumber-#{$$}").tap do |tmpdir|
+  mkdir_p tmpdir
+  mkdir_p File.join(tmpdir, 'apps')
+  at_exit { rm_rf tmpdir }
+end
+
+Before do
+  mkdir_p in_current_scenario
+end
+
+After do
+  rm_rf in_current_scenario
+end
+
+World(Helpers)

data/features/support/steps.rb

@@ -0,0 +1,58 @@
+require File.expand_path(File.dirname(__FILE__) + '/env')
+
+Given %r{I have a new rails app named (.*), with the (.*) gems?} do |name, gems|
+  gem_files = gems.split(',').collect do |gem_name|
+    gem_name.strip!
+    if gem_name == 'engineer'
+      ENGINEER_GEM_FILE
+    else
+      Dir["#{in_current_scenario(gem_name)}/pkg/#{gem_name}-*.gem"].first
+    end
+  end
+
+  generate_rails_app name, gem_files
+end
+
+When "I rails g $generator" do |generator|
+  generate generator
+end
+
+When "I try to rails g $generator" do |generator|
+  generate generator, :may_fail => true
+end
+
+When "I rake $rake_task" do |rake_task|
+  rake rake_task
+end
+
+When "I try to rake $rake_task" do |rake_task|
+  rake rake_task, :may_fail => true
+end
+
+When "I fill out my Rakefile gemspec" do
+  fill_out_the_rakefile_gemspec
+end
+
+Then "I should see output:" do |command_output|
+  latest_output.strip_ansi.strip.should match strip_wildcards(command_output.strip)
+end
+
+Then "$file should contain:" do |file, content|
+  File.read(in_current_app file).should match strip_wildcards(content)
+end
+
+Then "$file should not contain:" do |file, content|
+  File.read(in_current_app file).should_not match strip_wildcards(content)
+end
+
+Then "I should see a $file file" do |file|
+  File.exists?(in_current_app file).should be_true
+end
+
+Given "I have a finished engine application named $engine" do |engine|
+  Given "I have a new rails app named #{engine}, with the engineer gem"
+    And "I rails g engineer:install"
+    And "I rake version:write"
+    And "I fill out my Rakefile gemspec"
+    And "I rake build"
+end

data/lib/engineer/tasks.rb

@@ -0,0 +1,4 @@
+class Engineer
+  class Tasks < ::Jeweler::Tasks
+  end
+end

data/lib/engineer.rb

@@ -0,0 +1,5 @@
+require 'jeweler'
+
+class Engineer < Jeweler
+  autoload :Tasks,          'engineer/tasks'
+end

data/lib/generators/engineer/install/USAGE

@@ -0,0 +1,10 @@
+Description:
+  Transform the application into a gem-based engine.
+
+  The major steps are:
+    * creating an Engine subclass under lib/
+    * moving ApplicationController into a submodule
+    * creating an installation generator for host apps
+    * adding jeweler-style gem tasks to the Rakefile
+
+  Please see http://github.com/phs/engineer for details

data/lib/generators/engineer/install/install_generator.rb

@@ -0,0 +1,101 @@
+class Engineer
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+
+      def self.source_root
+        @source_root ||= File.expand_path('../templates', __FILE__)
+      end
+
+      def create_engine_files
+        directory 'lib', 'lib'
+      end
+
+      def namespace_application_controller
+        unnested_path = Rails.application.paths.app.controllers.to_a.detect do |p|
+          File.exists? File.join(p, 'application_controller.rb')
+        end
+
+        return unless unnested_path
+
+        nested_path = File.join(unnested_path, app_name)
+        empty_directory nested_path
+
+        create_file File.join(nested_path, 'application_controller.rb') do
+          content = File.read File.join(unnested_path, 'application_controller.rb')
+          content.gsub! "class ApplicationController", "class #{app_module}::ApplicationController"
+          content
+        end
+
+        remove_file File.join(unnested_path, 'application_controller.rb')
+
+        controller_files = Rails.application.paths.app.controllers.to_a.collect do |p|
+          Dir[File.join(p, "**", "*_controller.rb")]
+        end.flatten
+
+        controller_files.reject { |f| f =~ /application_controller\.rb$/ }.each do |file|
+          gsub_file file, "< ApplicationController", "< #{app_module}::ApplicationController"
+        end
+      end
+
+      def append_gemspec_to_Rakefile
+        in_root do
+          unless IO.read('Rakefile') =~ /Engineer::Tasks.new/
+            append_file 'Rakefile' do
+<<-RAKE
+
+Engineer::Tasks.new do |gem|
+  gem.name = "#{app_name}"
+  gem.summary = %Q{TODO: one-line summary of your engine}
+  gem.description = %Q{TODO: longer description of your engine}
+  gem.email = "TODO"
+  gem.homepage = "TODO"
+  gem.authors = ["TODO"]
+  gem.require_path = 'lib'
+  gem.files =  FileList[
+    "[A-Z]*",
+    "{app,config,lib,public,spec,test,vendor}/**/*",
+    "db/**/*.rb"
+  ]
+
+  # Include Bundler dependencies
+  Bundler.definition.dependencies.each do |dependency|
+    next if dependency.name == "engineer"
+
+    if (dependency.groups & [:default, :production, :staging]).any?
+      gem.add_dependency dependency.name, *dependency.requirement.as_list
+    else
+      gem.add_development_dependency dependency.name, *dependency.requirement.as_list
+    end
+  end
+
+  # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+end
+RAKE
+            end
+          end
+        end
+      end
+
+      # TODO Remove after https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/4400
+      def tweak_route_declaration
+        gsub_file(File.join("config", "routes.rb"),
+          /#{Rails.application.class}.routes.draw/, "Rails.application.routes.draw")
+      end
+
+    protected
+
+      def app_name
+        app_module.underscore
+      end
+
+      def app_module
+        Rails.application.class.name.split('::').first
+      end
+
+      def engineer_version
+        Gem.loaded_specs["engineer"].version
+      end
+
+    end
+  end
+end

data/lib/generators/engineer/install/templates/lib/%app_name%/engine.rb.tt

@@ -0,0 +1,41 @@
+require "<%= app_name %><%#%>"
+require "rails"
+
+module <%= app_module %><%#%>
+  class Engine < Rails::Engine
+    ASSET_PREFIX = "<%= app_name %><%#%>"
+    ENGINEER_VERSION = "<%= engineer_version %><%#%>"
+
+    initializer "<%= app_name %><%#%>.action_view.identifier_collection" do
+      require 'action_view/template'
+      class ActionView::Template
+        def render_with_identifier_collection(view, locals, &block)
+          (Thread.current[:view_identifiers] ||= []).push identifier
+          render_without_identifier_collection(view, locals, &block)
+        ensure
+          Thread.current[:view_identifiers].pop
+        end
+
+        unless instance_methods.include? "render_without_identifier_collection"
+          alias_method_chain :render, :identifier_collection
+        end
+      end
+    end
+
+    def engine_view?(identifier)
+      @engine_views ||= Hash.new do |h, identifier|
+        h[identifier] = !Rails.application.paths.app.views.any? do |path|
+          identifier =~ /^#{Regexp.escape(path)}/
+        end
+      end
+      @engine_views[identifier]
+    end
+
+    initializer "<%= app_name %><%#%>.asset_path" do
+      <%= app_module %><%#%>::ApplicationController.config.asset_path = lambda do |source|
+        view_identifier = (Thread.current[:view_identifiers] ||= []).last
+        engine_view?(view_identifier) ? "/#{ASSET_PREFIX}#{source}" : source
+      end
+    end
+  end
+end

data/lib/generators/engineer/install/templates/lib/%app_name%.rb.tt

@@ -0,0 +1,3 @@
+module <%= app_module %>
+  require "<%= app_name %>/engine" if defined?(Rails)
+end

data/lib/generators/engineer/install/templates/lib/generators/%app_name%/install/USAGE.tt

@@ -0,0 +1,5 @@
+Description:
+    Install <%= app_name %>
+
+Example:
+    rails generate <%= app_name %>:install

data/lib/generators/engineer/install/templates/lib/generators/%app_name%/install/install_generator.rb.tt

@@ -0,0 +1,19 @@
+module <%= app_module %><%#%>
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+
+      def self.source_root
+        @source_root ||= File.expand_path('../templates', __FILE__)
+      end
+
+      def install_rake_tasks
+        directory '.', File.join("lib", "tasks")
+      end
+
+      def rake_engine_install
+        rake "<%= app_name %><%#%>:install"
+      end
+
+    end
+  end
+end

data/lib/generators/engineer/install/templates/lib/generators/%app_name%/install/templates/%app_name%.rake.tt

@@ -0,0 +1,167 @@
+namespace "<%= app_name %><%#%>" do
+
+  # Migrate after schema in case there is no engine schema: at least we'll get the migrations.
+  task :install => %w{assets db:schema db:migrate db:migrate:seed}
+
+  desc "Import <%= app_name %><%#%>'s assets and new db migrations"
+  task :update => %w{assets db:migrate}
+
+  namespace :db do #<%# TODO: not everyone uses active record. %>
+
+    def host_migration(new_migration_name, &block)
+      require 'rails/generators/active_record'
+      db_migrate = File.join Rails.root, *%w{db migrate}
+      mkdir_p db_migrate unless File.exists? db_migrate
+
+      # TODO Kill after https://rails.lighthouseapp.com/projects/8994-ruby-on-rails/tickets/4412
+      sleep 1 # wait for timestamp to change.
+
+      migration_number = ActiveRecord::Generators::Base.next_migration_number(db_migrate)
+      new_migration = File.join db_migrate, "#{migration_number}_#{new_migration_name}.rb"
+      tmp_migration = File.join Dir::tmpdir, "#{migration_number}_#{new_migration_name}.rb"
+
+      File.open(tmp_migration, "w") do |f|
+        f << block.call
+      end
+
+      cp tmp_migration, new_migration
+    end
+
+    def import_migration(original_file, new_migration_name, &block)
+      host_migration new_migration_name do
+        block.call File.read original_file
+      end
+    end
+
+    desc "Import <%= app_name %><%#%>'s new db migrations"
+    task :migrate do
+      require 'rails/generators/active_record'
+      db_migrate = File.join Rails.root, *%w{db migrate}
+
+      # Consider the set of engine migrations, in chronological order.
+      migrations = Dir[File.join <%= app_module %><%#%>::Engine.root, *%w{db migrate [0-9]*_*.rb}]
+      migrations.sort!
+
+      # See if the host already has a schema migration.
+      last_migration_in_schema = migrations.reverse.detect do |migration|
+        name = File.basename(migration).match(/\d+_(.*)\.rb/)[1]
+        Dir[File.join(db_migrate, "[0-9]*_<%= app_name %><%#%>_schema_after_#{name}.rb")].any?
+      end
+
+      # If so, do not import any migrations implied by the schema
+      # (recall slice! *removes* the indicated range, leaving the rest.)
+      migrations.slice! 0..migrations.index(last_migration_in_schema) if last_migration_in_schema
+
+      # Of the remainder
+      migrations.each do |old_migration|
+        old_name = File.basename(old_migration).match(/\d+_(.*)\.rb/)[1]
+        new_name = "<%= app_name %><%#%>_#{old_name}"
+
+        # Skip this single migration if we already have it
+        next if Dir[File.join(db_migrate, "[0-9]*_#{new_name}.rb")].any?
+
+        import_migration old_migration, new_name do |migration_source|
+          migration_source.gsub "class #{old_name.camelize}", "class #{new_name.camelize}"
+        end
+      end
+    end
+
+    desc "Import <%= app_name %><%#%>'s schema as a db migration"
+    task :schema do
+      schema = File.join <%= app_module %><%#%>::Engine.root, *%w{db schema.rb}
+      if File.exist? schema
+        migrations = Dir[File.join <%= app_module %><%#%>::Engine.root, *%w{db migrate [0-9]*_*.rb}]
+        latest_migration = migrations.sort.last
+
+        migration_name = if latest_migration
+          latest_migration_name = File.basename(latest_migration).match(/^\d+_(.+)\.rb$/)[1]
+          "<%= app_name %><%#%>_schema_after_#{latest_migration_name}"
+        else
+          "<%= app_name %><%#%>_schema"
+        end
+
+        import_migration schema, migration_name do |schema_source|
+          # Strip schema declaration
+          schema_source.gsub! /\A.*^ActiveRecord::Schema.define\(:version => \d+\) do/m, ''
+          schema_source.strip!.gsub!(/^end\Z/m, '').strip!
+
+          # Indent everything 2 and strip trailing white space
+          schema_source.gsub!(/^/, '  ').gsub!(/[\t ]+$/, '')
+
+          # Wrap with migration class declaration
+<<-EOF
+class #{migration_name.camelize} < ActiveRecord::Migration
+  def self.up
+  #{schema_source}
+  end
+end
+EOF
+        end
+      end
+    end
+
+    task "migrate:seed" do
+      migration_name = "<%= app_name %><%#%>_seed"
+      if File.exist? File.join(<%= app_module %><%#%>::Engine.root, 'db', 'seeds.rb')
+        host_migration migration_name do
+<<-EOF
+class #{migration_name.camelize} < ActiveRecord::Migration
+  def self.up
+    load File.join(<%= app_module %><%#%>::Engine.root, 'db', 'seeds.rb')
+  end
+end
+EOF
+        end
+      end
+    end
+
+    desc "Load <%= app_name %><%#%>'s seed data"
+    task :seed => :environment do
+      seed_file = File.join(<%= app_module %><%#%>::Engine.root, 'db', 'seeds.rb')
+      load(seed_file) if File.exist?(seed_file)
+    end
+
+  end
+
+  desc "Link (or copy) <%= app_name %><%#%>'s static assets"
+  task :assets, [:copy] => :environment do |t, args|
+    engine_asset_path = File.join(
+      Rails.application.paths.public.to_a.first,
+      <%= app_module %><%#%>::Engine::ASSET_PREFIX)
+
+    rm_rf engine_asset_path
+    host_asset_path = <%= app_module %><%#%>::Engine.paths.public.to_a.first
+
+    link = lambda do
+      begin
+        ln_s host_asset_path, engine_asset_path
+        true
+      rescue NotImplementedError
+        false
+      end
+    end
+
+    copy = lambda { cp_r host_asset_path, engine_asset_path }
+
+    not args[:copy] and link.call or copy.call
+  end
+
+end
+
+namespace :engines do
+
+  desc "Load seed data from all engines"
+  task "db:seed" => "<%= app_name %><%#%>:db:seed"
+
+  desc "Import new migrations from all engines"
+  task "db:migrate" => "<%= app_name %><%#%>:db:migrate"
+
+  desc "Link (or copy) static assets from all engines"
+  task :assets, [:copy] => "<%= app_name %><%#%>:assets"
+
+  desc "Import assets and new db migrations from all engines"
+  task :update => "<%= app_name %><%#%>:update"
+
+end
+
+task "db:seed" => "engines:db:seed"

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'rubygems'
+gem 'jeweler', '>= 1.4.0'
+
+require 'engineer'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification 
+name: engineer
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Phil Smith
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-28 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 4
+        - 0
+        version: 1.4.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: cucumber
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 6
+        - 4
+        version: 0.6.4
+  type: :development
+  version_requirements: *id003
+description: Turn your rails 3 app into an embeddable engine gem, with answers for db migrations, static assets and more.
+email: phil.h.smith@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- features/engine_rake_tasks.feature
+- features/engineer_install_generator.feature
+- features/host_install_generator.feature
+- features/support/env.rb
+- features/support/steps.rb
+- lib/engineer.rb
+- lib/engineer/tasks.rb
+- lib/generators/engineer/install/USAGE
+- lib/generators/engineer/install/install_generator.rb
+- lib/generators/engineer/install/templates/lib/%app_name%.rb.tt
+- lib/generators/engineer/install/templates/lib/%app_name%/engine.rb.tt
+- lib/generators/engineer/install/templates/lib/generators/%app_name%/install/USAGE.tt
+- lib/generators/engineer/install/templates/lib/generators/%app_name%/install/install_generator.rb.tt
+- lib/generators/engineer/install/templates/lib/generators/%app_name%/install/templates/%app_name%.rake.tt
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/phs/engineer
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Turn rails 3 applications into engines
+test_files: 
+- spec/spec_helper.rb