warbler 2.1.0 → 2.1.2

data/lib/warbler/bundler_helper.rb

@@ -7,14 +7,7 @@
 module Warbler
   module BundlerHelper
     def to_spec(spec)
-      # JRuby <= 1.7.20 does not handle respond_to? with method_missing right
-      # thus a `spec.respond_to?(:to_spec) ? spec.to_spec : spec` won't do :
-      if ::Bundler.const_defined?(:StubSpecification) # since Bundler 1.10.1
-        spec = spec.to_spec if spec.is_a?(::Bundler::StubSpecification)
-      else
-        spec = spec.to_spec if spec.respond_to?(:to_spec)
-      end
-      spec
+      spec.respond_to?(:to_spec) ? spec.to_spec : spec
     end
     module_function :to_spec
   end

data/lib/warbler/config.rb

@@ -15,8 +15,8 @@ module Warbler
     include RakeHelper
 
     TOP_DIRS = %w(app db config lib log script vendor)
-    FILE = "config/warble.rb"
-    BUILD_GEMS = %w(warbler rake rcov)
+    CONFIG_DIR = "config"
+    FILE = "#{CONFIG_DIR}/warble.rb"
 
     include Traits
 
@@ -29,11 +29,8 @@ module Warbler
 
     # Traits: an array of trait classes corresponding to
     # characteristics of the project that are either auto-detected or
-    # configured.
-    attr_accessor :traits
-
-    # Deprecated: No longer has any effect.
-    attr_accessor :staging_dir
+    # forced enabled during `Config.new(forced_traits: [...]) do |config|`
+    attr_reader :traits
 
     # Directory where the war file will be written. Can be used to direct
     # Warbler to place your war file directly in your application server's
@@ -63,8 +60,10 @@ module Warbler
     # Whether to include dependent gems (default true)
     attr_accessor :gem_dependencies
 
-    # Array of regular expressions matching relative paths in gems to
-    # be excluded from the war. Default contains no exclusions.
+    # Array of regular expressions matching paths *inside* packed gems to be
+    # excluded from the archive. Paths are matched relative to each gem's root
+    # (for git-sourced gems: the repository checkout root). Default contains no
+    # exclusions.
     attr_accessor :gem_excludes
 
     # Whether to exclude **/*.log files (default is true)
@@ -185,8 +184,9 @@ module Warbler
     attr_reader :warbler_templates
     attr_reader :warbler_scripts
 
-    def initialize(warbler_home = WARBLER_HOME)
-      super()
+    # @param forced_traits [Array<Class>, nil] optional array of Warbler::Trait types to force rather than auto-detecting them
+    def initialize(warbler_home = WARBLER_HOME, forced_traits: nil)
+      super(forced_traits)
 
       @warbler_home      = warbler_home
       @warbler_templates = "#{WARBLER_HOME}/lib/warbler/templates"

data/lib/warbler/gems.rb

@@ -51,9 +51,8 @@ module Warbler
 
     # Add a single gem to WEB-INF/gems
     def find_single_gem_files(gem_dependencies, gem_pattern, version = nil)
-      gem_spec_class = Gem::Specification
       case gem_pattern
-      when gem_spec_class
+      when Gem::Specification
         return BundlerHelper.to_spec(gem_pattern)
       when Gem::Dependency
         gem = gem_pattern
@@ -61,12 +60,9 @@ module Warbler
         gem = Gem::Dependency.new(gem_pattern, Gem::Requirement.create(version))
       end
       # skip development dependencies
-      return nil if gem.respond_to?(:type) and gem.type != :runtime
+      return nil if gem.type != :runtime
 
-      # Deal with deprecated Gem.source_index and #search
-      matched = gem.respond_to?(:to_spec) ? [ gem.to_spec ] : Gem.source_index.search(gem)
-      fail "gem '#{gem}' not installed" if matched.empty?
-      spec = matched.last
+      spec = gem.to_spec
       return spec unless gem_dependencies
       [spec] + spec.dependencies.map { |dependent_gem| find_single_gem_files(gem_dependencies, dependent_gem) }
     end

data/lib/warbler/jar.rb

@@ -70,8 +70,6 @@ module Warbler
       end
       @compiled = true
     end
-    # @deprecated only due compatibility
-    alias_method :run_javac, :run_jrubyc
 
     def sh_jrubyc(cmd)
       sh(cmd) do |ok, res|
@@ -178,6 +176,7 @@ module Warbler
 
     # Invoke a hook to allow the project traits to add or modify the archive contents.
     def apply_traits(config)
+      puts "Applying traits #{config.traits}" unless silent?
       config.update_archive(self)
     end
 
@@ -220,7 +219,7 @@ module Warbler
           # OK if the gem does not exists as its un-packed on the "shared" path
           # ... at least gem spec.spec_file should exists although not crucial
           if JRUBY_VERSION != JRubyJars::VERSION
-            warn "skipping #{spec.name} default gem (assuming its part of jruby-jars #{JRubyJars::VERSION})" unless silent?
+            warn "skipping #{spec.name} default gem (assuming its part of jruby-jars #{JRubyJars::VERSION})"
           end
         else
           warn "skipping #{spec.name} gem (#{full_gem_path.to_s} does not exist)"
@@ -335,14 +334,6 @@ module Warbler
 
     # Java-boosted jar creation for JRuby; replaces #create_jar and
     # #entry_in_jar with Java version
-    require 'warbler_jar' if defined?(JRUBY_VERSION) && JRUBY_VERSION >= "1.5"
-  end
-
-  # Warbler::War is Deprecated. Please use Warbler::Jar.
-  class War < Jar
-    def initialize(*)
-      super
-      warn "Warbler::War is deprecated. Please replace all occurrences with Warbler::Jar."
-    end
+    require 'warbler_jar' if defined?(JRUBY_VERSION)
   end
 end

data/lib/warbler/task.rb

@@ -151,12 +151,15 @@ module Warbler
         if File.exist?(Warbler::Config::FILE) && ENV["FORCE"].nil?
           puts "There's another bird sitting on my favorite branch"
           puts "(file '#{Warbler::Config::FILE}' already exists. Pass argument FORCE=1 to override)"
-        elsif !File.directory?("config")
-          puts "I'm confused; my favorite branch is missing"
-          puts "(directory 'config' is missing)"
-        else
-          cp "#{Warbler::WARBLER_HOME}/warble.rb", Warbler::Config::FILE
+          next
+        end
+
+        if !File.directory?(Warbler::Config::CONFIG_DIR)
+          puts "config dir is missing, creating it"
+          mkdir_p Warbler::Config::CONFIG_DIR
         end
+
+        cp "#{Warbler::WARBLER_HOME}/warble.rb", Warbler::Config::FILE
       end
     end
 

data/lib/warbler/templates/bundler.erb

@@ -1,4 +1 @@
 ENV['BUNDLE_WITHOUT'] = '<%= config.bundle_without.join(':') %>'
-<% if config.bundler[:frozen] -%>
-ENV['BUNDLE_FROZEN'] = '1'
-<% end -%>

data/lib/warbler/templates/jar.erb

@@ -4,10 +4,12 @@ ENV['GEM_HOME'] <%= config.override_gem_home ? '=' : '||=' %> File.expand_path(F
 ENV['GEM_HOME'] <%= config.override_gem_home ? '=' : '||=' %> File.expand_path(File.join('..', '..', '<%= config.relative_gem_path %>'), __FILE__)
 <% end -%>
 <% if config.override_gem_home -%>
-ENV['GEM_PATH'] = nil # RGs sets Gem.paths.path = Gem.default_path + [ GEM_HOME ]
+<%# GEM_HOME (the packed gems) is always on Gem.path; adding only the runtime's own default %>
+<%# gem dir (Ruby's "bundled gems") excludes host gem paths (e.g. Gem.user_dir aka ~/.gem) %>
+ENV['GEM_PATH'] = Gem.default_dir
 <% end -%>
 <% if config.bundler && config.bundler[:gemfile_path] -%>
 ENV['BUNDLE_GEMFILE'] = File.expand_path(File.join('..', '..', '<%= config.bundler[:gemfile_path] %>'), __FILE__)
 <% end -%>
 <%# Ensure any cached paths are cleared; otherwise behaviour can be indeterminate if the paths have already been read %>
-# Gem.clear_paths
+Gem.clear_paths

data/lib/warbler/templates/war.erb

@@ -6,7 +6,9 @@ if $servlet_context.nil?
 else
   ENV['GEM_HOME'] <%= config.override_gem_home ? '=' : '||=' %> $servlet_context.getRealPath('<%= config.gem_path %>')
 <% if config.override_gem_home -%>
-  ENV['GEM_PATH'] = nil
+  <%# GEM_HOME (the packed gems) is always on Gem.path; adding only the runtime's own default %>
+  <%# gem dir (Ruby's "bundled gems") excludes host gem paths (e.g. Gem.user_dir aka ~/.gem) %>
+  ENV['GEM_PATH'] = Gem.default_dir
 <% end -%>
 <% if config.bundler && config.bundler[:gemfile_path] -%>
   ENV['BUNDLE_GEMFILE'] ||= $servlet_context.getRealPath('/<%= config.bundler[:gemfile_path] %>')

data/lib/warbler/traits/bundler.rb

@@ -14,6 +14,23 @@ module Warbler
       include PathmapHelper
       include BundlerHelper
 
+      # Bundler settings enforced in the packed application via a generated
+      # *.bundle/config*, the highest-precedence documented configuration level:
+      BUNDLE_CONFIG_DEFAULTS = {
+        # BUNDLE_VERSION: disable bundler's "auto-switch" to Gemfile.lock's BUNDLED WITH bundler version
+        #   (bundler restarts the process to do so, which cannot work inside a servlet container or self-contained executable jar)
+        'BUNDLE_VERSION' => 'system',
+        # BUNDLE_FROZEN: fail fast with a descriptive error on Gemfile vs Gemfile.lock drift instead of attempting
+        #   a runtime re-resolution
+        'BUNDLE_FROZEN' => 'true',
+        # BUNDLE_PATH__SYSTEM (path.system): pin bundler to the "system" gems - which are the packed gems, via
+        #   GEM_HOME/GEM_PATH from *init.rb* - immune to a BUNDLE_PATH/BUNDLE_DEPLOYMENT leaking in from the host's
+        #   environment or ~/.bundle/config
+        'BUNDLE_PATH__SYSTEM' => 'true',
+        # BUNDLE_AUTO_INSTALL: never install gems at boot time, even if the host's environment or global config enables it
+        'BUNDLE_AUTO_INSTALL' => 'false'
+      }.freeze
+
       def self.detect?
         File.exist?(ENV['BUNDLE_GEMFILE'] || 'Gemfile')
       end
@@ -36,6 +53,8 @@ module Warbler
         config.gem_dependencies = false # Bundler takes care of these
         config.bundler = {} if config.bundler == true
 
+        warn_on_bundler_version_mismatch
+
         bundler_specs.each do |spec|
           spec = to_spec(spec)
 
@@ -45,11 +64,12 @@ module Warbler
             config.bundler[:git_specs] << spec
           when ::Bundler::Source::Path
             unless bundler_source_is_warbled_gem_itself?(spec.source)
-              if spec.source.path && spec.source.path.relative?
-                # include (assuming) relative *[APP_ROOT]/gem/path*
-                # NOTE: might be tuned to only add gemspec.files ...
+              if spec.source.path&.relative?
+                # pack the gem at its relative *[APP_ROOT]/gem/path* location - at runtime bundler resolves the path
+                # source relative to the packed Gemfile.
+                # Deliberately NOT also added to config.gems: bundler never materializes path gems from the gem
+                # repository; doing so would cause duplication.
                 config.includes += FileList[File.join(spec.source.path, '**/*')]
-                config.gems << spec # probably not really needed
               else
                 warn("Bundler `path' components are not fully supported.\n" +
                      "The `#{spec.full_name}' component was not bundled.\n" +
@@ -57,13 +77,12 @@ module Warbler
               end
             end
           else
-            config.gems << spec
+            config.gems << spec unless spec.respond_to?(:default_gem?) && spec.default_gem?
           end
         end
         config.bundler[:gemfile]  = ::Bundler.default_gemfile
         config.bundler[:gemfile_path] = apply_pathmaps(config, relative_from_pwd(::Bundler.default_gemfile), :application)
         config.bundler[:lockfile] = ::Bundler.default_lockfile
-        config.bundler[:frozen] = ::Bundler.settings[:frozen]
         path = ::Bundler.settings[:path]
         config.excludes += [path, "#{path}/**/*"] if path
         config.init_contents << "#{config.warbler_templates}/bundler.erb"
@@ -73,42 +92,41 @@ module Warbler
         add_bundler_files(jar) if config.bundler
       end
 
-      # Add Bundler Gemfiles and git repositories to the archive.
+      # Add Bundler Gemfiles, .bundle/config and git repositories to the archive.
       def add_bundler_files(jar)
         gemfile  = relative_from_pwd(config.bundler[:gemfile])
         lockfile = relative_from_pwd(config.bundler[:lockfile])
+        bundle_config = File.join('.bundle', 'config')
+
         jar.files[apply_pathmaps(config, gemfile, :application)] = config.bundler[:gemfile].to_s
-        if File.exist?(lockfile)
-          jar.files[apply_pathmaps(config, lockfile, :application)] = config.bundler[:lockfile].to_s
-        end
-        if config.bundler[:git_specs]
-          pathmap = "#{config.relative_gem_path}/bundler/gems/%p"
-          pathmap.sub!(%r{^/+}, '')
-          config.pathmaps.git = [pathmap]
-          config.bundler[:git_specs].each do |spec|
-            full_gem_path = Pathname.new(spec.full_gem_path)
-
-            gem_relative_path = full_gem_path.relative_path_from(::Bundler.install_path)
-            filenames = []
-            gem_relative_path.each_filename { |f| filenames << f }
-
-            exclude_gems = true
-            unless filenames.empty?
-              full_gem_path = Pathname.new(::Bundler.install_path) + filenames.first
-              exclude_gems = false
-            end
+        jar.files[apply_pathmaps(config, lockfile, :application)] = config.bundler[:lockfile].to_s if File.exist?(lockfile)
+        # NOTE: in-memory content must be an IO - jar creation treats plain Strings as source file paths
+        jar.files[apply_pathmaps(config, bundle_config, :application)] = StringIO.new(bundle_config_contents)
 
-            if spec.groups.include?(:warbler_excluded)
-              pattern = "#{full_gem_path.to_s}/**/#{spec.name}.gemspec" # #42: gemspec only to avert Bundler error
-            else
-              pattern = "#{full_gem_path.to_s}/**/*"
-            end
+        add_bundler_git_specs(config.bundler[:git_specs], jar) if config.bundler[:git_specs]
+      end
 
-            FileList[pattern].each do |src|
-              f = Pathname.new(src).relative_path_from(full_gem_path).to_s
-              next if exclude_gems && config.gem_excludes && config.gem_excludes.any? {|rx| f =~ rx }
-              jar.files[apply_pathmaps(config, File.join(full_gem_path.basename, f), :git)] = src
-            end
+      private
+
+      def add_bundler_git_specs(git_specs, jar)
+        config.pathmaps.git = ["#{config.relative_gem_path}/bundler/gems/%p".sub(%r{^/+}, '')]
+
+        # a git source checkout may contain multiple gems (spec.full_gem_path being a sub-directory) - bundler expects
+        # the complete repository checkout under bundler/gems/<repo>-<ref>, so pack from its root (once per repository,
+        # even when several specs share the checkout)
+        checkout_paths = git_specs.map do |spec|
+          full_gem_path = Pathname.new(spec.full_gem_path)
+          filenames = full_gem_path.relative_path_from(::Bundler.install_path).each_filename.to_a
+          filenames.empty? ? full_gem_path : Pathname.new(::Bundler.install_path) + filenames.first
+        end.uniq
+
+        checkout_paths.each do |checkout_path|
+          FileList["#{checkout_path.to_s}/**/*"].each do |src|
+            f = Pathname.new(src).relative_path_from(checkout_path).to_s
+            # NOTE: for git sources the excludes match relative to the packed repository checkout root (the gem root,
+            # except multi-gem repos)
+            next if config.gem_excludes && config.gem_excludes.any? { |rx| f =~ rx }
+            jar.files[apply_pathmaps(config, File.join(checkout_path.basename, f), :git)] = src
           end
         end
       end
@@ -121,17 +139,32 @@ module Warbler
         end
       end
 
-      private
+      def warn_on_bundler_version_mismatch
+        lockfile = ::Bundler.default_lockfile
+        return unless lockfile && File.exist?(lockfile)
+        locked = ::Bundler::LockfileParser.new(File.read(lockfile)).bundler_version rescue nil
+        if locked && locked.to_s != ::Bundler::VERSION
+          warn("Gemfile.lock BUNDLED WITH (#{locked}) does not match the bundler running warbler (#{::Bundler::VERSION}).\n" +
+               "The packed application will boot with the default bundler of the packed JRuby (jruby-jars),\n" +
+               "consider re-generating Gemfile.lock with a matching bundler version.")
+        end
+      end
+
+      # Contents for the packed *.bundle/config*: only warbler's deployment settings, deliberately independent of the
+      # application's build-time bundler configuration.
+      def bundle_config_contents
+        require 'yaml'
+        settings = BUNDLE_CONFIG_DEFAULTS.dup
+        # frozen mode errors without a lockfile - do not force it upon applications packed without a Gemfile.lock
+        settings.delete('BUNDLE_FROZEN') if config.bundler[:frozen] == false || !File.exist?(config.bundler[:lockfile].to_s)
+        settings.to_yaml
+      end
 
       def bundler_specs
         bundle_without = config.bundle_without.map { |s| s.to_sym }
         definition = ::Bundler.definition
-        all = definition.specs.to_a
         requested_groups = definition.groups - bundle_without
-        requested = requested_groups.empty? ? [] : definition.specs_for(requested_groups).to_a
-        excluded_git_specs = (all - requested).select { |spec| ::Bundler::Source::Git === spec.source }
-        excluded_git_specs.each { |spec| spec.groups << :warbler_excluded }
-        requested + excluded_git_specs
+        requested_groups.empty? ? [] : definition.specs_for(requested_groups).to_a
       end
 
       def bundler_source_is_warbled_gem_itself?(source)

data/lib/warbler/traits/gemspec.rb

@@ -18,6 +18,10 @@ module Warbler
         !Dir['*.gemspec'].empty?
       end
 
+      def self.conflicts
+        [ Traits::NoGemspec ]
+      end
+
       def before_configure; require 'yaml'
         @spec_file = Dir['*.gemspec'].first
         @spec = File.open(@spec_file) { |f| Gem::Specification.from_yaml(f) } rescue Gem::Specification.load(@spec_file)

data/lib/warbler/traits/jar.rb

@@ -17,7 +17,11 @@ module Warbler
       include Trait
 
       def self.detect?
-        !War.detect?
+        !detect_any_conflicts?
+      end
+
+      def self.conflicts
+        [ Traits::War ]
       end
 
       def before_configure
@@ -28,10 +32,6 @@ module Warbler
         config.init_contents << "#{config.warbler_templates}/jar.erb"
       end
 
-      def after_configure
-        config.init_contents << StringIO.new("require 'rubygems' unless defined?(Gem)\n")
-      end
-
       def update_archive(jar)
         unless config.manifest_file
           manifest = Warbler::Jar::DEFAULT_MANIFEST.chomp + "Main-Class: JarMain\n"

data/lib/warbler/traits/jbundler.rb

@@ -23,6 +23,7 @@ module Warbler
 
       def before_configure
         config.jbundler = true
+        warn "JBundler support is deprecated due to the EOL of JBundler. See https://github.com/jruby/warbler/issues/481 for discussion on replacement with jar-dependencies."
       end
 
       def after_configure
@@ -35,7 +36,7 @@ module Warbler
         if File.exist?( classpath )
           require File.expand_path( classpath )
         else
-          raise 'jbundler support needs jruby to create a local config: jruby -S jbundle install'
+          raise 'JBundler support needs JRuby to create a local config: jruby -S jbundle install'
         end
         # use only the jars from jbundler and jruby
         config.java_libs += jruby_jars

data/lib/warbler/traits/nogemspec.rb

@@ -16,7 +16,11 @@ module Warbler
       include ExecutableHelper
 
       def self.detect?
-        Jar.detect? && !Gemspec.detect?
+        Jar.detect? && !detect_any_conflicts?
+      end
+
+      def self.conflicts
+        [ Traits::Gemspec ]
       end
 
       def before_configure

data/lib/warbler/traits/rack.rb

@@ -12,7 +12,11 @@ module Warbler
       include Trait
 
       def self.detect?
-        !Rails.detect? && (File.exist?("config.ru") || !Dir['*/config.ru'].empty?)
+        (File.exist?("config.ru") || !Dir['*/config.ru'].empty?) && !detect_any_conflicts?
+      end
+
+      def self.conflicts
+        [ Traits::Rails ]
       end
 
       def self.requirements

data/lib/warbler/traits/rails.rb

@@ -15,6 +15,10 @@ module Warbler
         File.exist?('config/environment.rb')
       end
 
+      def self.conflicts
+        [ Traits::Rack ]
+      end
+
       def self.requirements
         [ Traits::War ]
       end

data/lib/warbler/traits/war.rb

@@ -21,6 +21,10 @@ module Warbler
         Traits::Rails.detect? || Traits::Rack.detect?
       end
 
+      def self.conflicts
+        [ Traits::Jar ]
+      end
+
       def before_configure
         config.gem_path      = DEFAULT_GEM_PATH
         config.pathmaps      = default_pathmaps

data/lib/warbler/traits.rb

@@ -5,6 +5,7 @@
 # See the file LICENSE.txt for details.
 #++
 
+require 'set'
 require 'stringio'
 require 'tsort'
 
@@ -15,10 +16,13 @@ module Warbler
   # the kind of project and how it should be packed into the jar or
   # war file.
   module Traits
-    attr_accessor :traits
-
-    def initialize
-      @traits = auto_detect_traits
+    # @param forced_traits [Array<Class>, nil] array of Warbler::Trait types to force rather than auto-detecting them
+    def initialize(forced_traits)
+      @traits = if forced_traits.nil? || forced_traits.empty?
+                  auto_detect_traits
+                else
+                  validate_traits(forced_traits)
+                end
     end
 
     def auto_detect_traits
@@ -45,6 +49,18 @@ module Warbler
       @trait_objects = nil
       @traits.collect! {|t| t.name }
     end
+
+    private
+    def validate_traits(requested_traits)
+      conflicts = Set.new
+      requested_traits.each do |trait|
+        trait.conflicts.each do |conflict|
+          conflicts += [trait, conflict] if requested_traits.include?(conflict)
+        end
+      end
+      raise "Some forced traits declare conflicts with each other: #{conflicts.to_a}" unless conflicts.empty?
+      TraitsDependencyArray.new(requested_traits).tsort
+    end
   end
 
   # Each trait class includes this module to receive shared functionality.
@@ -53,6 +69,14 @@ module Warbler
       def requirements
         []
       end
+
+      def conflicts
+        []
+      end
+
+      def detect_any_conflicts?
+        conflicts.any? { |c| c.detect? }
+      end
     end
 
     def self.included(base)
@@ -108,7 +132,7 @@ module Warbler
 
     alias tsort_each_node each
     def tsort_each_child(node, &block)
-      node.requirements.each(&block)
+      node.requirements.select { |r| include?(r) }.each(&block)
     end
   end
 

data/lib/warbler/version.rb

@@ -6,5 +6,5 @@
 #++
 
 module Warbler
-  VERSION = "2.1.0"
+  VERSION = "2.1.2"
 end

data/lib/warbler/web_server.rb

@@ -106,7 +106,6 @@ CONFIG
       jar.files["WEB-INF/webserver.properties"] ||= StringIO.new(<<-PROPS)
 mainclass = org.eclipse.jetty.runner.Runner
 args = args0,args1,args2,args3,args4,args5,args6
-props = jetty.home
 args0 = --host
 args1 = {{host}}
 args2 = --port
@@ -114,7 +113,10 @@ args3 = {{port}}
 args4 = --config
 args5 = {{config}}
 args6 = {{warfile}}
+props = jetty.home,org.eclipse.jetty.util.log.class,org.eclipse.jetty.util.log.stderr.ESCAPE
 jetty.home = {{webroot}}
+org.eclipse.jetty.util.log.class = org.eclipse.jetty.util.log.StdErrLog
+org.eclipse.jetty.util.log.stderr.ESCAPE = false
 PROPS
     end
   end

data/warble.rb

@@ -1,10 +1,27 @@
-# Disable Rake-environment-task framework detection by uncommenting/setting to false
+# Warbler is designed to auto-detect "traits" of your application based on the presence of various files.
+# In some cases this is ambiguous, or there is a desire to disable certain traits from being detected
+# and a list of traits can be supplied to override this.
+#
+# This is an advanced option, and must be a complete list of traits. Using this capability disables
+# some of Warbler's validation and conflict detection that causes traits to be automatically enabled and
+# disabled as required.
+# - `Warbler::Traits::Jar`       - package as a normal executable java archive (jar) application
+# - `Warbler::Traits::War`       - package as an executable web archive (war) application
+# - `Warbler::Traits::Bundler`   - package with the gems implied by a bundle Gemfile/Gemfile.lock
+# - `Warbler::Traits::Gemspec`   - package with the gems implied by a gemspec
+# - `Warbler::Traits::NoGemspec` - package only with the gems implied by that in a local `lib` folder
+# - `Warbler::Traits::JBundler`  - (deprecated, experimental) package with the jars implied by a `Jarfile`
+# - `Warbler::Traits::Rails`     - package with the necessary startup logic to boot a Rails application
+# - `Warbler::Traits::Rack`      - package with the necessary startup logic to boot a standalone Rack (non-Rails) application
+# forced_traits = [Warbler::Traits::Jar]
+
+# Disable Rake-environment-task framework detection for Rails applications by uncommenting/setting to false
 # Warbler.framework_detection = false
 
-# Warbler web application assembly configuration file
-Warbler::Config.new do |config|
+# Configure a new Warbler application assembly
+Warbler::Config.new(forced_traits: defined?(forced_traits) ? forced_traits : nil) do |config|
   # Features: additional options controlling how the jar is built.
-  # Currently the following features are supported:
+  # Currently, the following features are supported:
   # - *gemjar*: package the gem repository in a jar file in WEB-INF/lib
   # - *executable*: embed a web server and make the war executable
   # - *runnable*: allows to run bin scripts e.g. `java -jar my.war -S rake -T`
@@ -84,7 +101,7 @@ Warbler::Config.new do |config|
   # File extension for the archive. Defaults to either 'jar' or 'war'.
   # config.jar_extension = "jar"
 
-  # Destionation for the created archive. Defaults to project's root directory.
+  # Destination for the created archive. Defaults to project's root directory.
   # config.autodeploy_dir = "dist/"
 
   # Name of the MANIFEST.MF template for the war file. Defaults to a simple
@@ -101,11 +118,11 @@ Warbler::Config.new do |config|
   # config.compile_gems = false
 
   # When set it specify the bytecode version for compiled class files
-  # config.bytecode_version = "1.6"
+  # config.bytecode_version = "1.8"
 
-  # When set to true, Warbler will override the value of ENV['GEM_HOME'] even it
-  # has already been set. When set to false it will use any existing value of
-  # GEM_HOME if it is set.
+  # When set to true, Warbler will override the value of ENV['GEM_HOME'] even it has already been set.
+  # When set to false it will use any existing value of GEM_HOME if it is set. It's usually a bad idea to disable this;
+  # your built application will not be self-contained/isolated from the wider RubyGems environment of the machine.
   # config.override_gem_home = true
 
   # Specify executable
@@ -171,7 +188,7 @@ Warbler::Config.new do |config|
   #   is simply embedded in web.xml.
   # The script is evaluated in a Rack::Builder to load the application.
   # Examples:
-  # config.webxml.rackup.path = 'WEB-INF/hello.ru'
+  # config.webxml.rackup.path = '/WEB-INF/hello.ru'
   # config.webxml.rackup = %{require './lib/demo'; run Rack::Adapter::Camping.new(Demo)}
   # config.webxml.rackup = require 'cgi' && CGI::escapeHTML(File.read("config.ru"))