Skip to content

Java extensions for JRuby using polyglot maven

Jump to bottom
Martin Prout edited this page Oct 10, 2021 · 33 revisions

Maven has become the de-facto standard for managing jar dependencies on java projects and thanks to polyglot maven it can now do the same for jruby projects with java extensions. Over at jruby-examples we have created a simple project that outlines the necessary steps. You can get the latest release of maven (apache-maven-3.8.3) here, you need at least version-3.3.1 for polyglot maven.

In your project directory create a .mvn folder and create extensions.xml in that folder (this lets maven know that it should expect a pom.rb file, for polyglot-ruby rather than a pom.xml for regular maven). Before you do this you should probably clone and build our example project (navigate to extensions/basic/jruby-ext and rake to compile and test).

<?xml version="1.0" encoding="UTF-8"?>
<extensions>
  <extension>
    <groupId>io.takari.polyglot</groupId>
    <artifactId>polyglot-ruby</artifactId>
    <version>0.4.6</version>
  </extension>
</extensions>

Here is the complete pom.rb which as you see is just ruby (we generate the pom.xml for completeness but it does not get used in the build)

project 'jruby-ext' do

  model_version '4.0.0'
  id 'com.purbon:jruby-ext:1.3.0'
  packaging 'jar'
  
  description 'example JRuby extension'
  
  developer 'purbon' do
    name 'Pere Urbón'
    email 'pere.urbon@gmail.com'
    roles 'developer'
  end
  
  issue_management 'https://github.com/jruby/jruby-examples/issues', 'Github'
  
  source_control(
    url: 'https://github.com/jruby/jruby-examples',
    connection: 'scm:git:git://github.com/jruby/jruby-examples.git',
    developer_connection: 'git@github.com:jruby/jruby-examples.git'
  )
  
  properties(
    'maven.compiler.source' => '1.8',
    'maven.compiler.target' => '1.8',
    'source.directory' => 'src/main/java', # poxy Eclipse folders
    'project.build.sourceEncoding' => 'utf-8',
    'polyglot.dump.pom' => 'pom.xml',
    'jruby.api' => 'http://jruby.org/apidocs/',
  )
  ## NB: Since jruby-9.3.0.0 jruby-base is favored (over jruby) avoids unnecessary dependency conflicts
  jar 'org.jruby:jruby-base:9.3.0.0'
  
  plugin_management do
    plugin :resources, '2.6'
    plugin :dependency, '2.8'
    plugin(
      :compiler, '3.5.1',
      source: '${maven.compiler.source}',
      target: '${maven.compiler.target}'
    )
    plugin(
      :javadoc, '2.10.4',
      detect_offline_links: 'false',
      links: ['${jruby.api}']
    )
    plugin(
      :jar, '3.0.2',      
      archive: {
        manifestFile: 'MANIFEST.MF' # camel case reqd
      }    
    )
  end
  
  build do
    default_goal 'package'
    source_directory '${source.directory}'
    final_name 'jruby-ext'
  end
end

This build contain a couple of advanced features (including a MANIFEST.MF file that we generate in our Rakefile, and javadoc, including the jruby-api, without which it would be useless).

To generate the javadoc:

mvn javadoc:javadoc

The beauty of the maven build system is that it readily manages other jar dependencies, especially if they are available from maven central. See for example JRubyArt that depends on video jars as well as jruby. Until we fill out our documentation you may be interested in this guide by James Coglan to building jruby-extensions (A real world example that creates an alternative to a gem with MRI C extension).

Clone this wiki locally