rjack-tarpit

= rjack-tarpit

• http://rjack.gravitext.com/tarpit
• http://rjack.gravitext.com
• https://github.com/dekellum/rjack

== Description

TarPit provides the glue for an unholy union of build tools. TarPit includes general automation for any rubygems project. It originally used and remains heavily influenced by Hoe[http://seattlerb.rubyforge.org/hoe/] (e.g. Manifest.txt.) However, it fully supports use of Bundler[http://gembundler.com/]. The gemspec benefits from sensible automation but remains in a .gemspec per Bundler's requirements.

For java platform projects, TarPit offers Maven integration via the rjack-maven[http://rjack.gravitext.com/maven] gem. Maven package/install is run as needed, and jars are linked to the gem lib directory for inclusion, with semi-automatic Manifest.txt production. No need to bloat your git repo by checking in every version of every jar for all time. The standard Maven layout and configuration (i.e. src, target, pom.xml, assembly.xml) is otherwise retained for complete java tool set compatibility. Use Maven only for what is it good at: java compilation with dependencies. Use Rake for everything else.

=== Features

• In Rake/JVM process Maven execution via rjack-maven (speed)
• Default, in Rake process Minitest[http://docs.seattlerb.org/minitest/] launcher (speed)
• Manifest.txt for gem file contents, derived from Manifest.static plus jars in Java projects
• ReadmeParser for default specification url, summary, description values
• Specification name defaults from .gemspec
• LineMatchTaskDefiner defines check_(history|init)_(version|date) tasks where appropriate to avoid missing history or version updates on release

=== Java strategies

Java projects require different strategies for integrating Maven, specified via +s.maven_strategy=+ and summarized below:

+:no_assembly+ :: pom.xml builds a single jar, default same name and same version as gem project (SpecHelper.default_jar) or specified via +s.jars=+.

+:jars_from_assembly+ :: assembly.xml defines the jars at Maven package time. Changes to this set of jars must be incorporated by explicitly running the rake manifest task.

Default :: No java, or use assembly for multiple jars but specify +s.jars=+ when they can be computed, for example from common version number or other gem data. This avoids the need for the rake manifest step of +:jars_from_assembly+.

Assemblies are built and located with the pom version number. This defaults to gem project version, but can be fixed (i.e. s.assembly_version='1.0') to avoid a separate version to bump, where the project will not export the pom, for example when the project is re-packaging upstream jars as a gem.

== Synopsis

Sample gemspec for a gem including a single jar, built from java source with maven (see also included test/jproject):

gem 'rjack-tarpit', '~> 2.1' require 'rjack-tarpit/spec'

RJack::TarPit.specify do |s| require 'jproject/base'

s.version = JProject::VERSION

s.add_developer 'David Kellum', '[e-mail]'

s.maven_strategy = :no_assembly

s.depend 'rjack-slf4j',   '~> 1.6.4'
s.depend 'minitest',      '~> 2.3',     :dev

end

And the associated Rakefile (assuming use of Bundler):

require 'rubygems' require 'bundler/setup' require 'rjack-tarpit'

RJack::TarPit.new( "jproject" ).define_tasks

And a Bundler Gemfile:

source :rubygems gemspec

Java projects should provide a Manifest.static. Jars or other generated files will be added to this to produce Manifest.txt for use as the gemspec's files.

== Dependencies

See the gem dependencies. The rjack-maven gem is only a dependency on the java platform.

JRuby 1.6.x is only partially supported as of tarpit version 2.1.0, since it has become impossible to declare an openssl dependency which works correctly across JRuby 1.6.x and 1.7 in all target environments.

== License

Copyright (c) 2009-2017 David Kellum

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.