warbler 2.0.5 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fc866f8b7cede59880be0ac7014d368a7db6d756
-  data.tar.gz: 5f6de19055a066bb60939c8b1aebea840f3a29f5
+SHA256:
+  metadata.gz: b68e1cba9a7e9e892eb9f5950fe177c07a7bba4f349813e7bb9b18e82ad9bbcc
+  data.tar.gz: b0ed237291f26d1a79204499007d1527a97899214672474ef7cacd0aeb8591c4
 SHA512:
-  metadata.gz: dc98bb747bc17fde50404ccc478012cc7cc6504e21f91c6cd0aafe5cf636888a11749294314e75f24e4b8b5bba8cf64cb10f6cfcd7416509fabba29c2eb8b370
-  data.tar.gz: f2aea739629165e65f214f0d7430601e1c5763a3ca6fe6d2058a3647e41d7fe97d7dbe0125b153afbd01a384f683390d4fa1adc246c5c56684ac10726fd9da25
+  metadata.gz: 577dc3b4f393e6f4891e42806efdd64ab3ce8d3d222ff6b8ba6994a5f9376461ebcde493433d8875468cfacd8b63ec9fd058d26d8e6672e54458aa4120420e47
+  data.tar.gz: d6a263d75de2a1f2f179751face07f9b922002a7bcaa7b0534289a2188067e52ac8131fd814014421008912cb183d3afb120a6d51566072c3c737a4ed90b05b4

data/{History.txt → CHANGELOG.md}

@@ -1,35 +1,64 @@
-== 2.0.5
+## 2.1.1
+
+- #624, #635, #623: fix: ensure compatibility with JRuby 10.1
+- #583: fix: Create config dir if it's missing for simpler usage
+- #588: fix: NullPointerException during shutdown with executable war files
+- #589: fix: Jetty wars don't have console logging enabled by default
+- #617: fix: correct ability to configure/override/force specific traits via Config.new(forced_traits: [...])
+- #591: chore: clean up obsolete & deprecated code from 2.0.x and old Bundler versions
+- #592: chore: relax rubyzip requirement to allow rubyzip 2.x
+- #593: chore: relax jruby-rack requirement to allow compatibility with upcoming 1.3.x
+- #634: chore: deprecate JBundler trait for removal
+
+## 2.1.0
+
+Requires JRuby >= 9.4 due to needing Ruby 3.0+ compatibility.
+
+- #439: Include gem_build_complete_path in jar for RubyGems 2.5+ extension support
+- #440: Don't overwrite user-specified `webserver.properties` file
+- #513, #521: Fix issues with openstruct used for `config.webxml` values on JRuby 9.3+
+- #527: Fix war file path as argument for Jetty runner on Jetty 9.4.32+
+- #538: Put public folders inside public for executable war
+- #552, #553: Use URI.open instead of open
+- #557: Replace File.exists? with File.exist? for Ruby 3.2.0+ compatibility
+- #559, 575: Fixes to update Warbler to modern libs and JRuby, removing old Bundler 1.x hacks
+- #562: Fix problems with spaces in path names under windows
+- #571: Use newer keyword argument rubyzip 3.0 API (drops support for JRuby 9.3)
+- #575: Fix Gem path issues on JRuby 9.4.x
+- #574: Bump default Jetty version for executables to 9.4.58.v20250814
+
+## 2.0.5
 
 - #427: Check Java properties when looking up RAILS_ENV
 - #424: Rails Webpacker support
 - #397: Avoid warnings under JRuby 9K
 
-== 2.0.4
+## 2.0.4
 
 - fix: an instance variable name typo (@servlet_context_listeners)
 - #383: add bundler monkey patch
 
-== 2.0.3
+## 2.0.3
 
 - Remove test_files from gemspec to save 700k
 
-== 2.0.2
+## 2.0.2
 
 - #380: exclude spec/integration/rakelib and dot-files being packed into .gem
 - #379: 2.0.1 regression due forcing GEM_PATH = GEM_HOME
 
-== 2.0.1
+## 2.0.1
 
 - #367: avoid duplicate .jar copies in WEB-INF/lib
 - #364: support for compiling .rb files using jrubyc with options
 - #362: limit rubyzip version to not match too far
 - #363: [backport] support for running with (recent) rubyzip 1.2.0
 
-== 2.0.0
+## 2.0.0
 
 - Initial release with 9k support
 
-== 1.4.9
+## 1.4.9
 
 - Fixed a bug in detecting default PORT for executable WAR
 - #332: Warbler not picking up new Bundler convention of 'exe' directory for executables
@@ -37,11 +66,11 @@
 - Added the ability to set custom port for Jetty launcher with
   warbler.port or PORT env var
 
-== 1.4.7
+## 1.4.7
 
 - #319: Adds capacity to use the jruby-jars gem version for JRuby 9k.
 
-== 1.4.6
+## 1.4.6
 - #318: polish *scripts/rails* - require_relative should no longer be used
 - #315: Removed custom Jetty launcher in favor of jetty-runner
 - #316: Sprockets manifest name change
@@ -49,7 +78,7 @@
 - #311: Don't clear the environment if a java executable is found
 - #268: Compile's clearing of ENV vars makes it impossible to use custom compile vars
 
-== 1.4.5
+## 1.4.5
 - #282: Wrong default GEM_HOME in generated META-INF/init.rb
 - #305: warbler.rb: Document jar_extension, autodeploy_dir options
 - #304: enable ENV['RACK_ENV'] to honor command line environment variable
@@ -57,7 +86,7 @@
 - #291: Include most current gem version in README
 - #280: config.webserver = 'jetty' (by default)
 
-== 1.4.4
+## 1.4.4
 - #271: LoadError while excute rake command with runnable .war archive
 - #273: filtering support with `config.move_jars_to_webinf_lib`
 - #270: don't swallow compiler errors with backticks
@@ -68,7 +97,7 @@
 - #275: for jruby-1.7.13 we do not want to force load bouncy-castle jars
 - #276: unnecessary rubyzip dependency on "< 1.1"
 
-== 1.4.3
+## 1.4.3
 - Fixed a bug w/ symlinks that was introduced around jruby-1.7.10
 - #258: Bytecode version option for compiled class files
 - #259: Update README.rdoc to not require warbler in Gemfile
@@ -76,7 +105,7 @@
 - #167: Excluding rb and class files when using compiled flag
 - #254: Fixes #167 by excluding config.excludes from compiled files
 
-== 1.4.2
+## 1.4.2
 - #241: jars from jruby.jar itself do not get copied over to WEB-INF/lib
 - #199: javascript_include_tag and stylesheet_link_tag not generating digestions
 - #247: better support for Rails 4 asset pipeline
@@ -84,7 +113,7 @@
 - #243: Added the move_jars_to_webinf_lib method back in...
 - #249: Warbler 1.4.1 fails to compile on Windows
 
-== 1.4.1
+## 1.4.1
 - Support for JBundler
 - #165: Problem with bundler git gems
 - #239: Supresses a warning when using bundler
@@ -92,7 +121,7 @@
 - #220: For Rack-only apps, WEB-INF should be added to $LOAD_PATH
 - #218: Invoke jrubyc using system to ensure that STDERR from jrubyc is shown
 
-== 1.4.0
+## 1.4.0
 
 - Support for Rails 4.x
 - Improved runnable so `rails` command works w/o script dir
@@ -111,14 +140,14 @@
 - #204: Reset RubyGems gemspec cache between tests
 - #203: Test ordering issue when running with RubyGems 2.1.9
 
-== 1.3.8
+## 1.3.8
 
 - Numerous fixes related to -S option and local environment.
 - #162: Close the URLClassLoader before deleting tempJARs
 - #161: Comment out config.dirs to match default
 - #158: Warbler looking in the wrong directory for bundler gem
 
-== 1.3.7
+## 1.3.7
 
 - #154: Use #load in .rb shims
 - #153: Runnable war error
@@ -136,18 +165,18 @@
 - #105: Pick executables deterministically and warn when doing so
 - #104: Default executable is system-dependent
 
-== 1.3.6
+## 1.3.6
 
 - #100: fix winstone URL
 
-== 1.3.5
+## 1.3.5
 
 - Add config.webserver to give choices for which lightweight Java
   webserver is used in an executable war.
 - Add jenkins-ci.winstone and jetty as embeddable servers
 - #76, #81: fix rubyzip "can't modify frozen string" issue
 
-== 1.3.4
+## 1.3.4
 
 - #77, #78: Handle the case when multiple gems exists in a git path
   (Patrick Cheng)
@@ -157,7 +186,7 @@
   threadsafe (Joe Kutner)
 - #37, #64: Fix issues with Bundler and recent Rubygems/Rails
 
-== 1.3.3
+## 1.3.3
 
 - Note: 1.3.3 was YANKED due to #62
 - Move all jars to WEB-INF/lib, and leave an empty jar in the original
@@ -167,18 +196,18 @@
 - GH #42: Tricks to allow Bundler to find git repo gems even when they
   are excluded form production
 
-== 1.3.2
+## 1.3.2
 
 - Compatibility with rake 0.9.x, avoid deprecation warnings and deal
   with new FileList exclusion behavior
 - Exclude config.bundle_without groups properly
 
-== 1.3.1
+## 1.3.1
 
 - Pin rake version to ~> 0.8.7 for now. Rake 0.9.0 compatibility will
   follow in a future release.
 
-== 1.3.0
+## 1.3.0
 
 - Warbler can now package regular Ruby projects as executable jar
   files. See the README.rdoc file for details.
@@ -192,7 +221,7 @@
 - GH#8: Clean up compiled .class files after building war
 - GH#15: Simplify detection of thread-safe Rails
 
-== 1.2.1
+## 1.2.1
 
 - Add --directoryListings=false to Winstone launch by default. In some
   cases (sinatra) Winstone's directory listing masks application
@@ -202,7 +231,7 @@
   environment initialization before the web framework is loaded. See
   config.init_contents in Warbler::Config for details.
 
-== 1.2.0
+## 1.2.0
 
 - Drop compatibility with earlier versions of Bundler -- Bundler has
   changed a lot in a short period of time, so I'm expecting the number
@@ -223,7 +252,7 @@
 - Exclude 'tmp/war' directory so that people upgrading from 0.9 won't
   accidentally include it in their war file.
 
-== 1.1.0
+## 1.1.0
 
 - Add concept of "features" -- small Rake tasks that run before the
   creation of the war file and make manipulations to the war file
@@ -243,24 +272,24 @@
   default. Instead, config.ru is included in the war file.
 - Bump jruby-rack version requirement to 0.9.8.
 
-== 1.0.3
+## 1.0.3
 
 - Tracking recent Bundler changes - handle locked Gemfiles differently
   than unlocked ones
 - Handle file-based symlinks, and warn about inoperational directory
   symlinks under non-JRuby versions of Ruby.
 
-== 1.0.2
+## 1.0.2
 
 - Add 'warble pluginize' task back. This task now just creates a
   vendor/plugins/warbler/tasks/warbler.rake file. There's no need to
   "vendor" all of Warbler into your application anymore.
 
-== 1.0.1
+## 1.0.1
 
 - Fix careless bug where Warbler doesn't work with JRuby 1.4
 
-== 1.0
+## 1.0
 
 - Warbler hits 1.0! There are enough structural changes in Warbler
   that I feel it's time to roll the major version over to 1.0.
@@ -276,7 +305,7 @@
 - WARBLER-7: Add config.webinf_files option with more support for
   custom web.xml files
 
-== 0.9.14
+## 0.9.14
 
 - So, jruby-rack is bundled for one more release. 1.0 will not contain
   any jar files, I promise!
@@ -287,7 +316,7 @@
   (this happened with the Authlogic gem on Edge Rails)
   (thanks Laszlo Bacsi)
 
-== 0.9.13
+## 0.9.13
 
 - RailsConf 2009 edition.
 - Only bundled JRuby and JRuby-Rack upgrades. Bug fixes will have to come in 0.9.14.
@@ -295,7 +324,7 @@
 - Upgrade to JRuby 1.3.0RC1 and JRuby-Rack 0.9.4. The latter allows
   Rails 2.3 to work with Warbler.
 
-== 0.9.12
+## 0.9.12
 
 - Allow framework auto-detection to be disabled. Set
   `Warbler.framework_detection = false' at the top of config/warble.rb
@@ -313,7 +342,7 @@
 - Ignore gem development dependencies
 - Upgrade to JRuby 1.1.6 and JRuby-Rack 0.9.3
 
-== 0.9.11
+## 0.9.11
 
 - Auto-detect Rails and Merb and configure appropriately
   - For Rails, set rails booter, determine max runtimes based on Rails.configuration.threadsafe!,
@@ -331,7 +360,7 @@
 - Upgrade to JRuby 1.1.4 and JRuby-Rack 0.9.2
 - add [] as a way to specify non-identifier keys, example: config.webxml['!@#$%^'] = 'haha'
 
-== 0.9.10
+## 0.9.10
 
 - Upgraded to JRuby-Rack 0.9.1. Fixes JRUBY-2620, JRUBY-2594, JRUBY-2507.
 - Now verified to work with Camping and Sinatra. See
@@ -342,7 +371,7 @@
 - Fix #<Warbler::WebxmlOpenStruct ...> appearing in web.xml and document workarounds.
 - Add config.autodeploy_dir that, when specified, will create the war there.
 
-== 0.9.9
+## 0.9.9
 
 - Now shipping with JRuby-Rack 0.9!
 - Upgrade to JRuby 1.1.1
@@ -354,36 +383,36 @@
 -- config.webxml.pool.* have been replaced by config.webxml.jruby.(min|max).runtimes
 -- config.webxml.standalone and config.webxml.jruby_home no longer have any effect.
 
-== 0.9.5
+## 0.9.5
 
 - Fix bug in plugin warbler.rake task file that would favor loading warbler from gems before the version
   installed as a plugin
 - Upgrade to JRuby 1.1 final and Goldspike 1.6.1
 
-== 0.9.4
+## 0.9.4
 
 - Update bundled JRuby to 1.1RC3 and Goldspike to 1.6.
 - Fix inclusion of gems with platform-specific bits (e.g., Hpricot)
 
-== 0.9.3
+## 0.9.3
 
 - Update bundled JRuby to 1.1RC2, and Goldspike to 1.5.
 - The bundled JRuby and Goldspike now require JDK 5 or greater. If you wish to use JDK 1.4, use Warbler 0.9.2.
 
-== 0.9.2
+## 0.9.2
 
 - Update bundled JRuby to version 1.0.3 and Goldspike 1.4.
 - Add config.java_classes to allow you to copy loose Java classes into WEB-INF/classes.
 - Make jar command a single command string so that jar creation doesn't fail (works around bug in JRuby 1.0.2)
 - Use File.join to form staging directory, should produce the proper jar-command path in Windows
 
-== 0.9.1
+## 0.9.1
 
 - Add rake >= 0.7.3 as a dependency in the gem specification.
 - Add debug tasks: war:debug, war:debug:gems, war:debug:public, war:debug:app, war:debug:includes,
   war:debug:excludes, war:debug:java_libs gives you a breakdown of what Warbler expects to package.
 
-== 0.9
+## 0.9
 
 - Birthday! Warbler is a gem to make a .war file out of a Rails project. The intent is to provide a
   minimal, flexible, ruby-like way to bundle up all of your application files for deployment to a

data/Gemfile

@@ -2,15 +2,11 @@ source "https://rubygems.org/"
 
 gemspec
 
-group :development do
-  gem "jruby-openssl", :platform => :jruby
-  gem "rcov", ">= 0.9.8", :platform => :mri_18
-  gem "childprocess", :platform => :mri
-end
-
-gem 'rubyzip', ENV['RUBYZIP_VERSION'] if ENV['RUBYZIP_VERSION']
-gem 'rake', ENV['RAKE_VERSION'], :require => nil if ENV['RAKE_VERSION']
-
 group :development, :test do
-  gem 'rdoc', ['>= 3.10', '< 4.3'], :require => nil
+  gem 'rdoc', '~> 7.0', :require => nil
+
+  if defined?(JRUBY_VERSION)
+    # force jruby-jars to use current JRuby version for testing
+    gem 'jruby-jars', '~> ' + JRUBY_VERSION.split('.')[0..2].join('.')
+  end
 end

data/LICENSE.txt

@@ -1,9 +1,8 @@
-= Warbler
+MIT License
 
-Warbler is provided under the terms of the MIT license.
-
-Warbler (c) 2010-2013 Engine Yard, Inc.
-Warbler (c) 2007-2009 Sun Microsystems, Inc.
+Copyright (c) 2013-2018 The JRuby Team
+Copyright (c) 2010-2013 Engine Yard, Inc.
+Copyright (c) 2007-2009 Sun Microsystems, Inc.
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation files

data/Mavenfile

@@ -1,13 +1,17 @@
 #-*- mode: ruby -*-
+warn "ruby-maven is running fixed JRuby version #{JRUBY_VERSION}"
 
 # tell the gem setup for maven where the java sources are
 # and how to name the jar file (default path for the jar: ./lib )
 gemspec( :jar => 'warbler_jar.jar',
          :source => 'ext' )
 
-properties( 'jruby.plugins.version' => '1.1.5',
-            'jruby.version' => '9.1.6.0',
-            'jetty.version' => '9.2.10.v20150310' )
+properties(
+  'project.build.sourceEncoding' => 'UTF-8',
+  'mavengem.wagon.version' => '2.0.3',
+  'jruby.plugins.version' => '3.0.6',
+  'jetty.version' => '9.4.58.v20250814',
+)
 
 # dependencies needed for compilation
 scope :provided do
@@ -15,18 +19,31 @@ scope :provided do
   jar 'org.eclipse.jetty:jetty-webapp', '${jetty.version}'
 end
 
-plugin :compiler, '3.1', :source => '1.5', :target => '1.5'
+plugin :clean, '3.5.0'
+plugin :compiler, '3.15.0', :release => '8'
+plugin :resources, '3.5.0'
+plugin :jar, '3.5.0' do
+  execute_goals(:phase => 'none') # Avoid a duplicate execution with that defined by the :gemspec directive
+end
+plugin :install, '3.1.4'
+
+gem 'bundler', '${bundler.version}'
+gem 'jruby-jars', '${jruby.version}'
 
-plugin :invoker, '1.8' do
+plugin :invoker, '3.10.1' do
   execute_goals( :install, :run,
                  :id => 'integration-test',
-                 :properties => { 'warbler.version' => '${project.version}',
-                                  'jruby.version' => '${jruby.version}',
-                                  'jetty.version' => '${jetty.version}',
-                                  'bundler.version' => '1.12.5',
-                                  'jruby.plugins.version' => '${jruby.plugins.version}' },
-
+                 :properties => {
+                   'warbler.version' => '${project.version}',
+                   'jruby.version' => '${jruby.version}',
+                   'jetty.version' => '${jetty.version}',
+                   'bundler.version' => '${bundler.version}',
+                   'jruby.plugins.version' => '${jruby.plugins.version}',
+                   'style.color' => 'always',
+                 },
                  :goals => ['verify'],
                  :projectsDirectory => 'integration',
+                 :pomIncludes => [ '*/pom.xml' ],
+                 :pomExcludes => [],
                  :streamLogs => true )
 end

data/README.rdoc

@@ -1,4 +1,5 @@
-= Warbler {<img src="https://badge.fury.io/rb/warbler.svg" alt="Gem Version" />}[http://badge.fury.io/rb/warbler] {<img src="https://travis-ci.org/jruby/warbler.png" />}[https://travis-ci.org/jruby/warbler]
+= Warbler
+{rdoc-image:https://img.shields.io/gem/v/warbler}[https://rubygems.org/gems/warbler] {rdoc-image:https://github.com/jruby/warbler/actions/workflows/ci.yml/badge.svg}[https://github.com/jruby/warbler/actions/workflows/ci.yml]
 
 Warbler is a gem to make a Java jar or war file out of any Ruby, Rails or Rack
 application. Warbler provides a minimal, flexible, Ruby-like way to bundle up
@@ -7,9 +8,18 @@ all of your application files for deployment to a Java environment.
 Warbler provides a sane set of out-of-the box defaults that should allow most
 Ruby applications to assemble and Just Work.
 
-Version 2.x of Warbler supports versions of JRuby from 9.0.0.0 and up.
+== Compatibility
 
-Version 1.4.x of Warbler supports versions of JRuby up to 1.7.x. The {1.x-dev branch}[https://github.com/jruby/warbler/tree/1.x-dev] is the working code for this.
+    Warbler  Status        JRuby     Java  JRuby-Rack    Rails    Notes
+    -------  ----------  ----------  ----  ----------  ---------  ----------------------------------------------
+    2.1      Maintained  9.4 → 10.1  8+    1.2 → 1.3   5.0 → 8.0  Rails 8.1 may be OK with pure Ruby webservers.
+    2.0      EOL         9.2 → 9.3   6+    1.1 → 1.2       → 6.1
+    1.4      EOL         1.1 → 1.7   5+        ?           ?
+
+For running wars with specific Java web servers, consult jruby-rack compatibility (
+{master}[https://github.com/jruby/jruby-rack/tree/master],
+{1.2-stable}[https://github.com/jruby/jruby-rack/tree/1.2-stable],
+{1.1-stable}[https://github.com/jruby/jruby-rack/tree/1.1-stable] ).
 
 == Getting Started
 
@@ -93,7 +103,7 @@ feature and creates a basic war with the sources included, make sure you run :
 or, if it's important that the war always be compiled, use the option above to
 put the feature in your <tt>config/warble.rb</tt>.
 
-== War or Jar?
+== .war or .jar?
 
 War-based projects are for Rails, Merb, or Rack-based web applications.
 They usually contain a +config/environment.rb+ file, a +config/init.rb+ file,
@@ -108,7 +118,7 @@ in the <tt>lib</tt> directory. Warbler packages the application so that
 
 == Jar Files
 
-=== Gem Specification (gemspec) Files
+=== Gem Specification Files
 
 If your project has a <tt>.gemspec</tt> file in the top directory, it will be
 used to configure the project's dependencies, launcher script, require paths,
@@ -136,10 +146,14 @@ Warbler supports Bundler for gems and git repositories, but not for plain path
 components. Warbler will warn when a +:path+ component is found in the +Gemfile+
 and will refuse to include it in the archive.
 
-=== JBundler (experimental)
+=== JBundler (deprecated, experimental)
+
+Applications that use JBundler[http://github.com/jruby/jbundler], detected via presence of a +Jarfile+, will have
+the jars packaged up into the archive. The JBundler gem is **not** needed for runtime since all jars are already part of the classloader.
 
-Applications that use JBundler[http://github.com/mkristian/jbundler], detected
-via presence of a +Jarfile+, will have the jars packaged up into the archive. the JBundler gem is **not** needed for runtime since all jars are already part of the classloader.
+JBundler is EOL; and this capability is thus deprecated for removal in a future release, and is not recommended for use.
+The recommended replacement is bundler with +jar-dependencies+ (bundled with modern JRuby); but requires some work for
+compatibility. See https://github.com/jruby/warbler/issues/481 for more details and contribute if you'd like this feature to be retained and supported.
 
 == War Files
 
@@ -155,7 +169,7 @@ The following items are set up for you:
 * Multi-thread-safe execution (as introduced in Rails 2.2) is detected and
   runtime pooling is disabled.
 
-=== Other Rack-based applications
+=== Other Rack Applications
 
 If you have a +config.ru+ file in the top directory or one of the immediate
 subdirectories of your application, it will be included and used as the rackup
@@ -166,7 +180,7 @@ to manage your gems. <tt>ENV['RACK_ENV']</tt> will be set to +production+.
 See {the examples in the jruby-rack project}[http://github.com/jruby/jruby-rack/tree/master/examples/]
 of how to configure Warbler to package Camping and Sinatra apps.
 
-=== Configuration auto-detect notes
+=== Configuration Notes
 
 * Warbler will load the +environment+ Rake task in a Rails application to try
   to detect some configuration. If you don't have database access in the
@@ -178,19 +192,18 @@ of how to configure Warbler to package Camping and Sinatra apps.
   <tt>Gem.loaded_specs</tt> is available, but the application needs to be
   loaded first before its contents are reliable.
 
-== Custom configuration
+== Custom Configuration
 
 If the default settings are not appropriate for your application, you can
 customize Warbler's behavior. To customize files, libraries, and gems included
-in the .war file, you'll need a config/warble.rb file. There a two ways of
-doing this. With the gem, simply run
+in the .war file, you'll need a +config/warble.rb+ file. To generate one:
 
     warble config
 
-Finally, edit the +config/warble.rb+ to your taste. The generated file is
+Edit the +config/warble.rb+ to your taste. The generated file is
 fully-documented with the available options and default values.
 
-=== War layout
+=== Archive Layout
 
 The default configuration puts application files (+app+, +config+, +lib+,
 +log+, +vendor+, +tmp+) under the .war file's +WEB-INF+ directory, and files in
@@ -198,7 +211,7 @@ The default configuration puts application files (+app+, +config+, +lib+,
 automatically be placed in +WEB-INF/lib+ for placement on the web app's
 class-path.
 
-=== Web.xml
+=== web.xml
 
 Java web applications are configured mainly through this file, and Warbler
 creates a suitable default file for you for use. However, if you need to
@@ -219,7 +232,7 @@ customize it in any way, you have two options.
 
 For more information on configuration, see Warbler::Config.
 
-== Rakefile integration
+== Rakefile Integration
 
 If you'd like to control Warbler from your own project's +Rakefile+,
 simply add the following code somewhere in the +Rakefile+ :
@@ -243,22 +256,60 @@ task to give you more insight into what's going on.
 If you think you found a bug, please file one at
 https://github.com/jruby/warbler/issues.
 
+=== Common issues with executable wars
+
+If your app isn't working or starting up correctly: 
+
+-  <b>Missing Logging:</b>
+   If your boot process is failing silently (or with a logging warning), try configuring the logger
+   manually:
+  
+    java "-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog" -jar my_app.war
+
+-  <b>CompatVersion errors:</b>
+   If you are getting <tt>java.lang.NoClassDefFoundError: org/jruby/CompatVersion</tt> errors at start-up
+   you are probably running Warbler with a jruby-rack version which does not yet support JRuby 10+ - it 
+   swallows the true error making debugging impossible. Ensure you're on jruby-rack `1.2.7+`.
+
+-  <b>Bundler `restart_with` errors:</b>
+   If you are getting <tt>org.jruby.rack.RackInitializationException: No such file or directory - java -cp...</tt>,
+   that probably means bundler is trying to switch versions dynamically during start-up because your
+   `Gemfile.lock` implies a different locked version of bundler to that packaged with JRuby by default.
+
+   JRuby/Bundler running embedded inside a jar like this does not support switching bundler versions dynamically.
+
+   This may happen due to
+   - system gems for jruby installation upgradingg bundler to a newer version than packaged by default
+   - running <tt>bundle update --bundler</tt>
+   - using `BUNDLE_VERSION` to override bundle version which generating/editing your `Gemfile.lock`
+
+   Options to address this
+   - use <tt>bundle config set version system</tt> / <tt>bundle config set disable_shared_gems</tt> to avoid bundler picking system versions
+   - ensure your `Gemfile.lock`'s <tt>BUNDLED WITH</tt> version matches the default bundler packaged with your `jruby-jars` version. 
+     You can check inside the relevant `jruby-stdlib` jar or inside a clean installation dir from your Ruby version manager of choice. 
+   - remove <tt>BUNDLED WITH</tt> entirely from `Gemfile.lock`. Sometimes bundler will add this back again; so not recommended in the longer term
+
+-  <b>Rack version compatibility</b>
+    An exception happened during JRuby-Rack startup
+    no such file to load -- rack/chunked
+   You are trying to use Rack 3.x with a jruby-rack version that does not yet support Rack 3. Try upgrading to a compatible
+   jruby-rack version, or lock rack at a compatibile version with <tt>gem 'rack', '~> 2.2.0'</tt>. Note that Rack `2.2` requires Rails < `8.1`.
+   
 == Source
 
 You can get the Warbler source using Git, in any of the following ways:
 
-   git clone git://git.caldersphere.net/warbler.git
    git clone git://github.com/jruby/warbler.git
 
 You can also download a tarball of Warbler source at
-https://github.com/jruby/warbler/tarball/master.
+https://github.com/jruby/warbler/archive/master.zip.
 
 == Development
 
 You can develop Warbler with any implementation of Ruby. To write Warbler code
-and run specs, you need to have Bundler installed and run <tt>bundle</tt> once.
+and run specs, you need to have Bundler installed and run <tt>bundle install</tt> once.
 
-After that, simply run <tt>rake</tt>.
+After that, simply run +rake+.
 
 === Integration Tests
 
@@ -266,19 +317,14 @@ There are a few integration tests in the `integration` directory that build WAR
 with Warbler, and run some basic smoke tests against them.  You can run these like so:
 
     cd integration
-    export MAVEN_OPTS="-XX:MaxPermSize=128m"
     mvn verify
 
-The increased PermGen space is for the Rails4 test. And You'll need to have Maven 3.1.1 installed, of course:
-http://maven.apache.org/ Be aware the homebrew installs 3.0.5, which doesn't work (and I don't really know why).
-
+You'll need to have Maven >= 3.1.1 installed, of course: http://maven.apache.org/
 
 == License
 
 Warbler is provided under the terms of the MIT license.
 
-Warbler (c) 2013-2015 The JRuby project
-
+Warbler (c) 2013-2018 The JRuby Team
 Warbler (c) 2010-2012 Engine Yard, Inc.
-
 Warbler (c) 2007-2009 Sun Microsystems, Inc.