# JRuby in Debian

## Building the package

To build this package, it's highly recommended to use a clean build environment
such as that provided by sbuild. The build process dumps a lot of artifacts and
temporary files in the source tree that are difficult to track and cleanup
properly.

The first step after obtaining the source and setting up a build environment is
getting the orig-source tarballs:

    ./debian/rules get-orig-source

This will create the orig tarballs for jruby itself and a tarball set of
rubygems, via the `debian/gem-download.sh` script: these gems are incorporated
into lib/ruby/stdlib and built into the binary package.

The Debian source tree should be ready to build.

### A note on bundled Ruby libraries

JRuby as a project does not track the latest versions of C Ruby. As new C Ruby
versions are released, JRuby inevitably falls behind. For example, JRuby 9.3.x
officially declares Ruby 2.6 compatibility, but this version of Ruby has long
been removed from Debian stable and replaced by newer versions.

In order to ensure JRuby works reliably in Debian, we therefore bundle a handful
of versioned gems obtained from rubygems.org into an orig-source tarball, in
addition to the Ruby libraries already bundled directly in the upstream source
tree.

The required gems are found in `debian/gem-list.txt`.

## Build process

Upstream uses polyglot-ruby, a maven plugin, to handle prepraring and copying
the default rubygems into lib/ruby/stdlib, but that plugin isn't packaged in
Debian so we execute those steps in the `execute_before_dh_auto_configure`
target.

In addition, these default rubygems bundle a handful of jars that are already
packaged in Debian, such as bouncycastle, so instead of using those copies we
replace them with our own debian-versioned jars for lib*-java packages.

## Artifacts

The build process builds a jruby-core-*.jar artifact, consisting of the JRuby
code in addition to shaded dependencies, also known as a "fat" jar or uberjar.
This is the code executed when `/usr/bin/jruby` is invoked.

This is not the usual method of building Java packages in Debian and it's
perhaps possible to fix this, however this would need further patches to the
POM files and additional build process tweaks, see #789485 for a discussion.

Other jar artifacts are built and shipped in the binary, such as jruby-stdlib,
and jruby-complete, but it's not clear if those are required or used by anyone.
It may be worth it to investigate this issue as those jars likely duplicate a
lot of code.

Upstream provides some information about the various artifacts on this page:
https://github.com/jruby/jruby/wiki/JRuby-Build----Some-Inside-Info

## Tests

JRuby comes with an large array of unit and integration testsuites.
Unfortunately because our build and packaging processes are vastly different
from upstream, some test failures do occur in some of the testsuites.

Helpful information about debugging tests is provided by upstream at:
https://github.com/jruby/jruby/blob/master/BUILDING.md
