<commit_before>h1. Doubleshot

*JRuby is amazing.*

Unfortunately there's no simple standard way to create a Ruby Gem that contains both Java and Ruby sources, with both JAR and Gem dependencies.

Before Doubleshot you'd probably use "Bundler":https://github.com/carlhuda/bundler to manage your Gem dependencies, "JBundler":https://github.com/mkristian/jbundler to manage your JAR dependencies and "Buildr":https://github.com/apache/buildr (which is built on top of Rake) to compile and package your project. That's _really_ cumbersome. Especially since Buildr wasn't built for this, (it's focus is _Java_ projects, as a substitute for Maven) and there really is very little documentation on how to accomplish your goals.

On top of that, you're now forced to run Rake and load these massive libraries even just to execute a single @TestCase@. And you'll have to run it every time. If you're a fan of TDD, you can realistically spend a substantial portion of your day just waiting for the JVM to load Maven, Bundler and Rake. Over. And Over. And Over.

It's *painful* is what it is.

You have a JRuby project with both Java and Ruby source files. You need to:

* Compile your Java
* Download JAR dependencies from a "Maven repository":http://mvnrepository.com/
* Download Gem dependencies from a "Rubygems server":https://github.com/sam/geminaboxplus
* Java Classes and Dependencies should be added to the @$CLASSPATH@ at runtime
* Write your tests in a single language (Ruby) using "Minitest":https://github.com/seattlerb/minitest
* Execute your Ruby normally, without the need for wrappers like Rake or @bundle exec@
* Automatically compile and reload Java sources on update, then execute the appropriate tests
* Reload your testing sandbox after updating Ruby sources without side-effects from previous versions code
* Package your mixed-language project and it's JAR dependencies into a Gem you can release
* Package a project and all it's dependencies up as a JAR so all you need on your server is Java

Here's what tools Doubleshot replaces in your workflow:

* Bundler
* JBundler
* GemPackageTask
* RakeTestTask
* Maven Dependencies
* Maven Assemblies
* Build tools like Ant or Buildr

h2. What's in a Name?

A shot each of JRuby and Java. Doubleshot.

h1. Usage

h2. Installation

bc. gem install doubleshot

h2. Project Layout

The typical project using Doubleshot as it's build-tool will have the following layout:

bc.. lib/
    world.rb         # Ruby sources go in the standard location.
    java/
        Hello.java   # Java sources appear under the lib/java folder.
test/
    helper.rb
    hello_spec.rb    # specs match up to lib/**/*.rb or lib/java/**/*.java
    world_spec.rb
hello_world.gemspec  # Standard Ruby gemspec, where gem dependencies are declared.
Doubleshot           # Your Doubleshot file replaces JBundler's Jarfile, and pulls
                     # in your gemspec.

p. Your tests should be executable and look something like this:

bc.. #!/usr/local/env jruby

require_relative "helper.rb"

java_import org.sam.doubleshot.examples.Hello

describe Hello do
  it "must rock you" do
    Hello.rock(:you).must_equal true
  end
end

p. ...and @helper.rb@ would look something like this:

bc.. require "doubleshot/build"
require "minitest/autorun"

h2. Testing Two Ways

h3. Direct Execution

p. Now you can execute your spec file directly and Doubleshot will:

# Ensure that the dependencies defined in the @Doubleshot@ file are met by resolving their versions, downloading them, and adding them to your environment.
# Compile any code found in @lib/java@ that's not already compiled.

Then Minitest will run your test and exit when it's done.

h3. Sandbox Execution

Doubleshot also provides a @doubleshot@ bin file that basically amounts to @require("doubleshot/sandbox")@. Running @doubleshot@ in your project's home directory will setup monitors for @lib/@ and @test/@ and wait for changes, applying the rules below to it's execution:

* When source under @lib/java/@ changes, it will be recompiled, reloaded, and matching tests searched for to execute
* When Ruby source under @lib/@ changes, your Ruby VM will be reloaded, and matching tests executed
* If any tests change, the sandbox will be reloaded (since tests are written in Ruby), and the test file executed
* If a @SIGINT@ (@^C@) is received, all tests will be loaded and executed
* If a second @SIGINT@ is received before execution of the full test-suite is finished, the monitor will exit cleanly

This is the typical use-case for day to day development of new projects/features when using Doubleshot to manage your build process.

h2. Packaging

Given a project named _Example_, then @example.gemspec@ would include your Gem dependencies (including "doubleshot") and your @Doubleshot@ file would include both your Gem and JAR dependencies. This way your project is backwards compatible with Rubygems and Bundler. When packaging your project, your JAR dependencies will be "vendored" into the gem you've built.

Within your project (ie: @lib/example.rb@) you'll @require "doubleshot/setup"@. This will ensure any dependencies for your Gem are satisfied at runtime. If a dependency is already loaded, (an upstream project called @require "bundler/setup"@ for example) then Doubleshot will skip it.

If you're running inside of a @doubleshot/build@ then requiring @doublehsot/setup@ will have no effect.

To build a gem, run the @doubleshot build@ command on the command line. Doubleshot will ensure all dependencies are satisfied, compile your code, vendor any JAR dependencies, run your tests, and finally create a gem for you based on your @example.gemspec@ file. We really don't think you should be releasing code with broken tests so the build will fail if the tests don't pass (or bad tests skipped). If you _really_ want to skip this step though you can run @NOTEST=1 doubleshot build@.

h1. FAQ

h2. Where is @doubleshot show@?

Bundler includes a @bundle show some_gem@ command that shows you the path where a dependency was unpacked after running @bundle install@. I've only ever used that in two cases:

- View the source of some library to try to trace a bug := Write a test to trace your bug. View the source online or clone it and view it locally. It's a minor inconvenience sure, but it's a lot less prone to abuse.
- Hack in a quick "hot-fix" for a production issue := You shouldn't be making changes outside of source-control. That's an obvious development anti-pattern.

It's our opinion that you don't _need_ this functionality, and it opens the window to abuse, so we're not implementing it.
<commit_msg>Summarized the monitored-testing strategy.<commit_after>h1. Doubleshot

*JRuby is amazing.*

Unfortunately there's no simple standard way to create a Ruby Gem that contains both Java and Ruby sources, with both JAR and Gem dependencies.

Before Doubleshot you'd probably use "Bundler":https://github.com/carlhuda/bundler to manage your Gem dependencies, "JBundler":https://github.com/mkristian/jbundler to manage your JAR dependencies and "Buildr":https://github.com/apache/buildr (which is built on top of Rake) to compile and package your project. That's _really_ cumbersome. Especially since Buildr wasn't built for this, (it's focus is _Java_ projects, as a substitute for Maven) and there really is very little documentation on how to accomplish your goals.

On top of that, you're now forced to run Rake and load these massive libraries even just to execute a single @TestCase@. And you'll have to run it every time. If you're a fan of TDD, you can realistically spend a substantial portion of your day just waiting for the JVM to load Maven, Bundler and Rake. Over. And Over. And Over.

It's *painful* is what it is.

You have a JRuby project with both Java and Ruby source files. You need to:

* Compile your Java
* Download JAR dependencies from a "Maven repository":http://mvnrepository.com/
* Download Gem dependencies from a "Rubygems server":https://github.com/sam/geminaboxplus
* Java Classes and Dependencies should be added to the @$CLASSPATH@ at runtime
* Write your tests in a single language (Ruby) using "Minitest":https://github.com/seattlerb/minitest
* Execute your Ruby normally, without the need for wrappers like Rake or @bundle exec@
* Automatically compile and reload Java sources on update, then execute the appropriate tests
* Reload your testing sandbox after updating Ruby sources without side-effects from previous versions code
* Package your mixed-language project and it's JAR dependencies into a Gem you can release
* Package a project and all it's dependencies up as a JAR so all you need on your server is Java

Here's what tools Doubleshot replaces in your workflow:

* Bundler
* JBundler
* GemPackageTask
* RakeTestTask
* Maven Dependencies
* Maven Assemblies
* Build tools like Ant or Buildr

h2. What's in a Name?

A shot each of JRuby and Java. Doubleshot.

h1. Usage

h2. Installation

bc. gem install doubleshot

h2. Project Layout

The typical project using Doubleshot as it's build-tool will have the following layout:

bc.. lib/
    world.rb         # Ruby sources go in the standard location.
    java/
        Hello.java   # Java sources appear under the lib/java folder.
test/
    helper.rb
    hello_spec.rb    # specs match up to lib/**/*.rb or lib/java/**/*.java
    world_spec.rb
hello_world.gemspec  # Standard Ruby gemspec, where gem dependencies are declared.
Doubleshot           # Your Doubleshot file replaces JBundler's Jarfile, and pulls
                     # in your gemspec.

p. Your tests should be executable and look something like this:

bc.. #!/usr/local/env jruby

require_relative "helper.rb"

java_import org.sam.doubleshot.examples.Hello

describe Hello do
  it "must rock you" do
    Hello.rock(:you).must_equal true
  end
end

p. ...and @helper.rb@ would look something like this:

bc.. require "doubleshot/build"
require "minitest/autorun"

h2. Testing Two Ways

h3. Direct Execution

p. Now you can execute your spec file directly and Doubleshot will:

# Ensure that the dependencies defined in the @Doubleshot@ file are met by resolving their versions, downloading them, and adding them to your environment.
# Compile any code found in @lib/java@ that's not already compiled.

Then Minitest will run your test and exit when it's done.

h3. Sandbox Execution

Doubleshot also provides a @doubleshot@ bin file that basically amounts to @require("doubleshot/sandbox")@. Running @doubleshot@ in your project's home directory will setup monitors for @lib/@ and @test/@ and wait for changes, applying the rules below to it's execution:

* When source under @lib/java/@ changes, it will be recompiled, reloaded, and matching tests searched for to execute
* When Ruby source under @lib/@ changes, your Ruby VM will be reloaded, and matching tests executed
* If any tests change, the sandbox will be reloaded (since tests are written in Ruby), and the test file executed
* If a @SIGINT@ (@^C@) is received, all tests will be loaded and executed
* If a second @SIGINT@ is received before execution of the full test-suite is finished, the monitor will exit cleanly

This is the typical use-case for day to day development of new projects/features when using Doubleshot to manage your build process. It allows you to write and test new code, without ever having to restart your Java VM, saving you ten seconds or so for every run, encouraging continuous testing so you can spend more time writing code, and less time waiting for processes to load.

h2. Packaging

Given a project named _Example_, then @example.gemspec@ would include your Gem dependencies (including "doubleshot") and your @Doubleshot@ file would include both your Gem and JAR dependencies. This way your project is backwards compatible with Rubygems and Bundler. When packaging your project, your JAR dependencies will be "vendored" into the gem you've built.

Within your project (ie: @lib/example.rb@) you'll @require "doubleshot/setup"@. This will ensure any dependencies for your Gem are satisfied at runtime. If a dependency is already loaded, (an upstream project called @require "bundler/setup"@ for example) then Doubleshot will skip it.

If you're running inside of a @doubleshot/build@ then requiring @doublehsot/setup@ will have no effect.

To build a gem, run the @doubleshot build@ command on the command line. Doubleshot will ensure all dependencies are satisfied, compile your code, vendor any JAR dependencies, run your tests, and finally create a gem for you based on your @example.gemspec@ file. We really don't think you should be releasing code with broken tests so the build will fail if the tests don't pass (or bad tests skipped). If you _really_ want to skip this step though you can run @NOTEST=1 doubleshot build@.

h1. FAQ

h2. Where is @doubleshot show@?

Bundler includes a @bundle show some_gem@ command that shows you the path where a dependency was unpacked after running @bundle install@. I've only ever used that in two cases:

- View the source of some library to try to trace a bug := Write a test to trace your bug. View the source online or clone it and view it locally. It's a minor inconvenience sure, but it's a lot less prone to abuse.
- Hack in a quick "hot-fix" for a production issue := You shouldn't be making changes outside of source-control. That's an obvious development anti-pattern.

It's our opinion that you don't _need_ this functionality, and it opens the window to abuse, so we're not implementing it.

{'fraction_non_alphanumeric': 0.06046029749130467, 'fraction_numerical': 0.0017760674905646415, 'mean_word_length': 4.197692307692308, 'pattern_counts': {'":': 12, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '54359', 'n_tokens_mistral': 3744, 'n_tokens_neox': 3559, 'n_words': 1978}