{"id":13533298,"url":"https://github.com/jruby/warbler","last_synced_at":"2025-04-09T00:16:45.803Z","repository":{"id":384759,"uuid":"2019","full_name":"jruby/warbler","owner":"jruby","description":"Warbler chirpily constructs .war files of your Ruby applications.","archived":false,"fork":false,"pushed_at":"2024-10-08T15:43:43.000Z","size":49876,"stargazers_count":882,"open_issues_count":104,"forks_count":204,"subscribers_count":33,"default_branch":"master","last_synced_at":"2024-10-29T14:15:46.450Z","etag":null,"topics":["jruby","packaging","ruby-on-rails","servlet","tomcat","war"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jruby.png","metadata":{"files":{"readme":"README.rdoc","changelog":"History.txt","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2008-03-01T18:46:46.000Z","updated_at":"2024-10-08T15:43:48.000Z","dependencies_parsed_at":"2023-11-10T16:27:16.348Z","dependency_job_id":"c50d16ab-de23-48e2-9ecc-da39ece753cd","html_url":"https://github.com/jruby/warbler","commit_stats":{"total_commits":949,"total_committers":86,"mean_commits":"11.034883720930232","dds":0.6217070600632244,"last_synced_commit":"3756c6cbbe2ecdccfeb6ac1658a0e3f657244e1b"},"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jruby%2Fwarbler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jruby%2Fwarbler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jruby%2Fwarbler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jruby%2Fwarbler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jruby","download_url":"https://codeload.github.com/jruby/warbler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247947781,"owners_count":21023067,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jruby","packaging","ruby-on-rails","servlet","tomcat","war"],"created_at":"2024-08-01T07:01:18.483Z","updated_at":"2025-04-09T00:16:45.780Z","avatar_url":"https://github.com/jruby.png","language":"Ruby","readme":"= Warbler {rdoc-image:https://badge.fury.io/rb/warbler.svg}[http://badge.fury.io/rb/warbler] {rdoc-image:https://github.com/jruby/warbler/actions/workflows/ci.yml/badge.svg}[https://github.com/jruby/warbler/actions/workflows/ci.yml]\n\nWarbler is a gem to make a Java jar or war file out of any Ruby, Rails or Rack\napplication. Warbler provides a minimal, flexible, Ruby-like way to bundle up\nall of your application files for deployment to a Java environment.\n\nWarbler provides a sane set of out-of-the box defaults that should allow most\nRuby applications to assemble and Just Work.\n\nVersion 2.x of Warbler supports versions of JRuby from 9.2.0.0 and up.\n\nVersion 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.\n\n== Getting Started\n\n1. Install the gem: \u003ctt\u003egem install warbler\u003c/tt\u003e.\n\n2. Run warbler in the top directory of your application: \u003ctt\u003ewarble\u003c/tt\u003e.\n\n3. Choose one:\n\n* For a web project, deploy your +myapp.war+ file to your favorite Java application server.\n\n* For a standalone applications, just run it: \u003ctt\u003ejava -jar myapp.jar\u003c/tt\u003e.\n\n== Usage\n\nWarbler's +warble+ command is just a small wrapper around Rake with internally\ndefined tasks.\n\n    $ warble -T\n    warble compiled    # Feature: precompile all Ruby files\n    warble config      # Generate a configuration file to customize your archive\n    warble executable  # Feature: make an executable archive (runnable + an emb...\n    warble gemjar      # Feature: package gem repository inside a jar\n    warble pluginize   # Install Warbler tasks in your Rails application\n    warble runnable    # Feature: make a runnable archive (e.g. java -jar rails...\n    warble version     # Display version of Warbler\n    warble war         # Create the project war file\n    warble war:clean   # Remove the project war file\n    warble war:debug   # Dump diagnostic information\n\n\nType \u003ctt\u003ewarble\u003c/tt\u003e to create the jar or war file.\n\n== Features\n\nWarbler \"features\" are small Rake tasks that run before the creation of the war\nfile and make manipulations to the archive structure. For instance, the\n+executable+ feature makes your war file capable of running on its own,\nwithout a servlet container (using an embedded web server) :\n\n    warble executable war\n\nYou can either add features to the warbler command line:\n\n    warble FEATURE war\n\nor configure them in \u003ctt\u003econfig/warble.rb\u003c/tt\u003e to always be used.\n\n   config.features = %w(FEATURE)\n\nCurrently, the following features are available :\n\n* +gemjar+: This bundles all gems into a single gem file to reduce the\n  number of files in the .war. This is mostly useful for Google\n  AppEngine where the number of files per application has a limit.\n  (Note: not applicable for jar-based applications.)\n* +runnable+: This makes a (standard Java) runnable .war archive thus you can\n  execute binary bundled (gem) commands e.g. \"rake\". You should use the -S\n  switch to specify the binary followed by any arguments in takes e.g.\n  \u003ctt\u003ejava -jar myrailsapp.war -S rake db:migrate\u003c/tt\u003e.\n* +executable+: This bundles an embedded web server into the .war so that it\n  can either be deployed into a traditional java web server or run as a\n  standalone application using \u003ctt\u003ejava -jar myapp.war\u003c/tt\u003e.\n  (Note: jar-based applications are executable by default.)\n* +compiled+: This uses +jrubyc+ to precompile all .rb files in your application\n  to .class files and includes those in the .war instead of the Ruby sources.\n  NOTE: The war file will still contain .rb files, but they will be short stubs\n  containing the following code : \u003ctt\u003eload __FILE__.sub(/\\.rb$/, '.class')\u003c/tt\u003e\n\nFeatures may form the basis for a third-party plugin system (in the future)\nif there is demand.\n\nNOTE: Feature tasks must be included in the same command invocation and\ninserted before the +war+ task in order to take effect. For example,\n\u003ctt\u003ewarble compiled; warble war\u003c/tt\u003e does not compile and obfuscate +.rb+\nsources because the second invocation of +warble+ does not run the +compiled+\nfeature and creates a basic war with the sources included, make sure you run :\n\n    warble compiled war\n\nor, if it's important that the war always be compiled, use the option above to\nput the feature in your \u003ctt\u003econfig/warble.rb\u003c/tt\u003e.\n\n== .war or .jar?\n\nWar-based projects are for Rails, Merb, or Rack-based web applications.\nThey usually contain a +config/environment.rb+ file, a +config/init.rb+ file,\nor a +config.ru+ file.\nThe presence of these files are used to determine if the project is a web\napplication, and thus a Java EE compatible war file is built for the project.\n\nJar-based projects are for standalone Ruby applications. Usually a Ruby\napplication has a launcher script in the +bin+ directory and Ruby code\nin the \u003ctt\u003elib\u003c/tt\u003e directory. Warbler packages the application so that\n\u003ctt\u003ejava -jar myapp.jar\u003c/tt\u003e runs the launcher script.\n\n== Jar Files\n\n=== Gem Specification Files\n\nIf your project has a \u003ctt\u003e.gemspec\u003c/tt\u003e file in the top directory, it will be\nused to configure the project's dependencies, launcher script, require paths,\nand the files to be included in the archive. For best results make sure your\ngemspec specifies all of the following attributes:\n\n* +executables+\n* +require_paths+\n* runtime dependencies added with +add_dependency+\n\nIf your project do not have a \u003ctt\u003e.gemspec\u003c/tt\u003e, Warbler will attempt to guess\nthe launcher from the contents of the \u003ctt\u003ebin\u003c/tt\u003e directory and use the\n\u003ctt\u003elib\u003c/tt\u003e directory as the lone require path. All files in the project\nwill be included in the archive.\n\n=== Bundler\n\nApplications that use Bundler[http://gembundler.com/], detected via presence of\na +Gemfile+, will have the gems packaged up into the archive along with the\nGemfile. The Bundler groups named \":development\", \":test\" and \":assets\" will be\nexcluded by default, unless you specify with \u003ctt\u003econfig.bundle_without\u003c/tt\u003e in\n+config/warble.rb+.\n\nWarbler supports Bundler for gems and git repositories, but not for plain path\ncomponents. Warbler will warn when a +:path+ component is found in the +Gemfile+\nand will refuse to include it in the archive.\n\n=== JBundler (experimental)\n\nApplications that use JBundler[http://github.com/mkristian/jbundler], detected\nvia 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.\n\n== War Files\n\n=== Rails applications\n\nRails applications are detected automatically and configured appropriately.\nThe following items are set up for you:\n\n* Your application runs in the +production+ environment by default.\n  Change it in +config/warble.rb+ (see below).\n* The Rails gem is packaged if you haven't vendored Rails (Rails \u003c= 2.x).\n* Other gems configured in Rails.configuration.gems are packaged (2.1 - 2.3)\n* Multi-thread-safe execution (as introduced in Rails 2.2) is detected and\n  runtime pooling is disabled.\n\n=== Other Rack Applications\n\nIf you have a +config.ru+ file in the top directory or one of the immediate\nsubdirectories of your application, it will be included and used as the rackup\nscript for your Rack-based application. You will probably need to specify\nframework and application gems in +config/warble.rb+ unless you're using Bundler\nto manage your gems. \u003ctt\u003eENV['RACK_ENV']\u003c/tt\u003e will be set to +production+.\n\nSee {the examples in the jruby-rack project}[http://github.com/jruby/jruby-rack/tree/master/examples/]\nof how to configure Warbler to package Camping and Sinatra apps.\n\n=== Configuration Notes\n\n* Warbler will load the +environment+ Rake task in a Rails application to try\n  to detect some configuration. If you don't have database access in the\n  environment where you package your application, you may wish to set\n  \u003ctt\u003eWarbler.framework_detection = false\u003c/tt\u003e at the top of +config.rb+.\n  In this case you may need to specify additional details such as booter, gems\n  and other settings that would normally be gleaned from the app configuration.\n* Is it possible to more generally detect what gems an application uses?\n  \u003ctt\u003eGem.loaded_specs\u003c/tt\u003e is available, but the application needs to be\n  loaded first before its contents are reliable.\n\n== Custom Configuration\n\nIf the default settings are not appropriate for your application, you can\ncustomize Warbler's behavior. To customize files, libraries, and gems included\nin the .war file, you'll need a config/warble.rb file. There a two ways of\ndoing this. With the gem, simply run\n\n    warble config\n\nFinally, edit the +config/warble.rb+ to your taste. The generated file is\nfully-documented with the available options and default values.\n\n=== Archive Layout\n\nThe default configuration puts application files (+app+, +config+, +lib+,\n+log+, +vendor+, +tmp+) under the .war file's +WEB-INF+ directory, and files in\n+public+ in the root of the .war file. Any Java .jar files stored in lib will\nautomatically be placed in +WEB-INF/lib+ for placement on the web app's\nclass-path.\n\n=== web.xml\n\nJava web applications are configured mainly through this file, and Warbler\ncreates a suitable default file for you for use. However, if you need to\ncustomize it in any way, you have two options.\n\n1. If you just want a static web.xml file whose contents you manually\n   control, you may unzip the one generated for you in\n   \u003ctt\u003eyourapp.war:WEB-INF/web.xml\u003c/tt\u003e to \u003ctt\u003econfig/web.xml\u003c/tt\u003e and\n   modify as needed. It will be copied into subsequent copies of the\n   war file for you.\n2. If you want to inject some dynamic information into the file, copy\n   the \u003ctt\u003eWARBLER_HOME/web.xml.erb\u003c/tt\u003e to\n   \u003ctt\u003econfig/web.xml.erb\u003c/tt\u003e. Its contents will be evaluated for you\n   and put in the webapp. Note that you can also pass arbitrary\n   properties to the ERb template by setting\n   \u003ctt\u003econfig.webxml.customkey\u003c/tt\u003e values in your\n   \u003ctt\u003econfig/warble.rb\u003c/tt\u003e file.\n\nFor more information on configuration, see Warbler::Config.\n\n== Rakefile Integration\n\nIf you'd like to control Warbler from your own project's +Rakefile+,\nsimply add the following code somewhere in the +Rakefile+ :\n\n    require 'warbler'\n    Warbler::Task.new\n\nIf you're using Bundler, you'll want to add Warbler to your +Gemfile+ :\n\n    group :development do\n      gem \"warbler\", :require =\u003e false\n    end\n\nNow you should be able to invoke \u003ctt\u003erake war\u003c/tt\u003e to create your war file.\n\n== Troubleshooting\n\nIf Warbler isn't packaging the files you were expecting, use the +war:debug+\ntask to give you more insight into what's going on.\n\nIf you think you found a bug, please file one at\nhttps://github.com/jruby/warbler/issues.\n\n== Source\n\nYou can get the Warbler source using Git, in any of the following ways:\n\n   git clone git://github.com/jruby/warbler.git\n\nYou can also download a tarball of Warbler source at\nhttps://github.com/jruby/warbler/archive/master.zip.\n\n== Development\n\nYou can develop Warbler with any implementation of Ruby. To write Warbler code\nand run specs, you need to have Bundler installed and run \u003ctt\u003ebundle\u003c/tt\u003e once.\n\nAfter that, simply run \u003ctt\u003erake\u003c/tt\u003e.\n\n=== Integration Tests\n\nThere are a few integration tests in the `integration` directory that build WAR file\nwith Warbler, and run some basic smoke tests against them.  You can run these like so:\n\n    cd integration\n    mvn verify\n\nYou'll need to have Maven \u003e= 3.1.1 installed, of course: http://maven.apache.org/\n\n== License\n\nWarbler is provided under the terms of the MIT license.\n\nWarbler (c) 2013-2018 The JRuby Team\n\nWarbler (c) 2010-2012 Engine Yard, Inc.\n\nWarbler (c) 2007-2009 Sun Microsystems, Inc.\n","funding_links":[],"categories":["Awesome Ruby CLIs","Ruby"],"sub_categories":["Release"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjruby%2Fwarbler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjruby%2Fwarbler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjruby%2Fwarbler/lists"}