Skip to content

Commit

Permalink
[Truffle] improve j+tr Readme
Browse files Browse the repository at this point in the history
@pitr-ch
pitr-ch committed Sep 17, 2015
1 parent 4aa79ce commit 60b4134
Showing 2 changed files with 121 additions and 40 deletions.
116 changes: 94 additions & 22 deletions tool/truffle/jruby_truffle_runner/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,29 @@
# JRuby+Truffle Runner

`jruby+truffle_runner` gem is a small command line utility designed to run and test Ruby gems and applications
on JRuby+Truffle Ruby runtime. It uses other Ruby implementation to prepare environment and to execute files, tests
on JRuby+Truffle. It is a temporary tool to make working with JRuby+Truffle easy until it fully supports
`rubygems` and `bundler`
`jruby+truffle_runner` gem is a small command line utility designed to run and
test Ruby gems and applications on JRuby+Truffle Ruby runtime. It uses other
Ruby implementation to prepare environment and to execute files, tests
on JRuby+Truffle. It is a temporary tool to make working with JRuby+Truffle
easy until it fully supports `rubygems` and `bundler`

## Installation

It assumes that you have another Ruby available, if you have JRuby's git
repository clone it can be compiled and used to run this tool. Rbenv is quite
good tool to install and manage different Rubies. To add your compiled JRuby
just add symlink from rbenv's `versions` directory pointing to JRuby's local
repository,
e.g. `ln -s ~/labs/jruby /usr/local/Cellar/rbenv/0.4.0/versions/jruby-local`.

There are 3 options.

1. Install the gem from rubygems.org (Not yet published).
Install the gem `gem install jruby+truffle_runner`
2. Use `jt` tool from JRuby's repository.
Run `jt install-tool` to install the gem from the cloned repository.
3. Create alias for the gem's executable. E.g. add
`alias jruby+truffle="~/path-to-jruby/tool/truffle/jruby_truffle_runner/bin/jruby+truffle" to your `.zshrc`.
3. Create alias for the gem's executable. E.g. add
`alias jruby+truffle="~/path-to-jruby/tool/truffle/jruby_truffle_runner/bin/jruby+truffle"`
to your `.bashrc`.

Then run `jruby+truffle --help` to see available subcommands.

@@ -25,29 +34,92 @@ There is a `setup` subcommand to create environment for JRuby+Truffle.
- Go to directory of a gem/application you would like to test.
- Run `jruby+truffle setup`

It copies default configuration (part of the gem) if one is available for a given gem (looks for a `gemspec` in current
directory). It installs all required gems (based on `Gemfile`) to local bundle (default path: `.jruby+truffle_bundle`),
and executes other steps defined in configuration file (`.jruby+truffle.yaml`) or as command line options
(see `jruby+truffle setup --help` to learn what additional setup steps are available, or see one of the bundled
configuration files found in `gem_configurations` directory).
It copies default configuration (part of the gem) if one is available for a
given gem (it looks for a `gemspec` in current directory). It installs all
required gems (based on `Gemfile`) to local bundle (default path:
`.jruby+truffle_bundle`), and executes other steps defined in the configuration
file (`.jruby+truffle.yaml`) or as command line options (see `jruby+truffle
setup --help` to learn what additional setup steps are available, or see one of
the bundled configuration files found in `gem_configurations` directory). After
it finishes, the `run` subcommand can be used.

## Running

After the environment is set the gem can be used to execute code, files, or gem's executables on JRuby+Truffle
in prepared environment. Examples follows (options after `--` are interpreted by Ruby, options before `--` are options
After the environment is set the gem can be used to execute code, files, or
gem's executables on JRuby+Truffle in prepared environment. Examples follows
(options after `--` are interpreted by Ruby, options before `--` are options
for this tool):

- `jruby+truffle run -- file.rb` - executes file.rb
- `jruby+truffle run -- -e '1+1'` - evaluates 1+1 expresion
- `jruby+truffle run -- -I test test/a_test_file_test.rb` - runs test_file
- `jruby+truffle run -S rspec -- spec/a_spec_file_spec.rb` - runs a spec file using executable of rspec gem
- `jruby+truffle run --require mocks -- file.rb` - executes file.rb, but requires mocks first.
(mocks can be made to load always by putting the option to configuration file instead)
- `jruby+truffle run -- file.rb` - executes file.rb
- `jruby+truffle run -- -e '1+1'` - evaluates 1+1 expression
- `jruby+truffle run -- -I test test/a_test_file_test.rb` - runs a test-file
- `jruby+truffle run -S rspec -- spec/a_spec_file_spec.rb` - runs a spec file
using executable of rspec gem
- `jruby+truffle run --require mocks -- file.rb` - executes file.rb, but
requires mocks first. (mocks can be made to load always by putting the
option to configuration file (`.jruby+truffle.yaml`) instead)

See `jruby+truffle run --help` to see all available options.

## Clean up

To remove all files added during setup phase run `jruby+truffle clean`, it'll only keep `.jruby+truffle.yaml`
configuration file for future re-setup.

To remove all files added during setup phase run `jruby+truffle clean`, it'll
only keep `.jruby+truffle.yaml` configuration file for future re-setup.

## Local configuration

Options which are required always or are part of the setup step can
pre-configured in `.jruby+truffle.yaml` file to avoid repeating on command
line. The configuration file has a 2 level deep tree structure. First level is
a name of the command (or `:global`), second level is the name of the option
which is same as its long variant with `-` replaced by `_`. Its values are
deep-merged with default values, then command-line options are applied. This
tool contains default configurations for some gems in `gem_configurations`
directory, they are copied when there is no configuration present. As example
activesupport's configuration file follows:


```yaml
---
:global:
# default ../jruby/bin/ruby won't work since activesupport is one more dir deeper
:jruby_truffle_path: '../../jruby/bin/jruby'
:graal_path: '../../graalvm-jdk1.8.0/bin/java'
:setup:
:file:
shims.rb: |
require 'minitest'
# mock load_plugins as it loads rubygems
def Minitest.load_plugins
end
bundler.rb: "module Bundler; def self.setup; end; end"
# mock method_source gem
method_source.rb: nil
# do not let bundler to install db gem group
:without:
- db
:run:
:require:
- shims
```
## Example step-by-step
```sh
cd workspace
git clone git@github.com:jruby/jruby.git
cd jruby
tool/jt.rb build # compile JRuby
cd ..

# assuming rbenv is installed, add your local compiled JRuby to rbenv
ln -s ~/labs/jruby /usr/local/Cellar/rbenv/0.4.0/versions/jruby-local

git clone git@github.com:ruby-concurrency/concurrent-ruby.git
cd concurrent-ruby
git checkout v0.9.1 # latest release
rbenv shell jruby-local # use your compiled JRuby
truffle setup
truffle run -S rspec -- spec --format progress # run all tests
# you should only see few errors
```
45 changes: 27 additions & 18 deletions tool/truffle/jruby_truffle_runner/lib/jruby+truffle_runner.rb
View file
Original file line number Diff line number Diff line change
@@ -53,19 +53,23 @@ class JRubyTruffleRunner
without: ['--without GROUP', 'Do not install listed gem group by bundler', add_to_array, []]
},
run: {
help: ['-h', '--help', 'Show this message', assign_new_value, false],
test: ['-t', '--test', 'Do not use Truffle use plain JRuby', assign_new_value, false],
graal: ['-g', '--graal', 'Run on graal', assign_new_value, false],
build: ['-b', '--build', 'Run `jt build` in JRuby', assign_new_value, false],
rebuild: ['--rebuild', 'Run `jt rebuild` in JRuby', assign_new_value, false],
debug: ['-d', '--debug', 'JVM remote debugging', assign_new_value, false],
require: ['-r', '--require FILE', 'Files to require, same as Ruby\'s -r', add_to_array, []],
load_path: ['-I', '--load-path LOAD_PATH', 'Paths to add to load path, same as Ruby\'s -I', add_to_array, []],
executable: ['-S', '--executable NAME', 'finds and runs an executable of a gem', assign_new_value, nil],
jexception: ['--jexception', 'print Java exceptions', assign_new_value, false]
help: ['-h', '--help', 'Show this message', assign_new_value, false],
test: ['-t', '--test', 'Do not use Truffle use plain JRuby', assign_new_value, false],
graal: ['-g', '--graal', 'Run on graal', assign_new_value, false],
build: ['-b', '--build', 'Run `jt build` in JRuby', assign_new_value, false],
rebuild: ['--rebuild', 'Run `jt rebuild` in JRuby', assign_new_value, false],
debug: ['-d', '--debug', 'JVM remote debugging', assign_new_value, false],
require: ['-r', '--require FILE', 'Files to require, same as Ruby\'s -r', add_to_array, []],
require_pattern: ['--require-pattern DIR_GLOB_PATTERN', 'Files matching the pattern will be required', add_to_array, []],
load_path: ['-I', '--load-path LOAD_PATH', 'Paths to add to load path, same as Ruby\'s -I', add_to_array, []],
executable: ['-S', '--executable NAME', 'finds and runs an executable of a gem', assign_new_value, nil],
jexception: ['--jexception', 'print Java exceptions', assign_new_value, false]
},
clean: {
help: ['-h', '--help', 'Show this message', assign_new_value, false]
},
readme: {
help: ['-h', '--help', 'Show this message', assign_new_value, false]
}
}
end
@@ -78,12 +82,8 @@ class JRubyTruffleRunner
Allows to execute gem/app on JRuby+Truffle until it's more complete. Environment
has to be set up first with setup subcommand then run subcommand can be used.
Options can be set on commandline or in local directory in #{LOCAL_CONFIG_FILE} file.
Tha data in yaml file follow same structure as OPTION_DEFINITIONS what, its values
are deep-merged with default values, then command-line options are applied.
This tool contains default configurations for gems in gem_configurations directory.
They are copied when there is no configuration present.
Run #{EXECUTABLE} readme to see README.
Run #{EXECUTABLE} subcommand --help to see its help.
TXT

@@ -129,16 +129,17 @@ def initialize(argv = ARGV)

if subcommand.nil?
print_options
help
help :global
end
help :global if @options[:global][:help]

subcommand = subcommand.to_sym

subcommand_option_parser = @option_parsers[subcommand] || raise("unknown subcommand: #{subcommand}")
argv_after_subcommand = subcommand_option_parser.order argv_after_global

print_options
help subcommand if @options[subcommand][:help]
help subcommand if @options[subcommand][:help] && subcommand != :readme

send "subcommand_#{subcommand}", argv_after_subcommand
end
@@ -295,6 +296,9 @@ def subcommand_run(rest)
end

core_load_path = "#{jruby_path}/truffle/src/main/ruby"
@options[:run][:require_pattern].each do |pattern|
Dir.glob(pattern) { |v| @options[:run][:require] << File.expand_path(v) }
end

cmd_options = [
*(['-X+T', "-Xtruffle.core.load_path=#{core_load_path}"] unless @options[:run][:test]),
@@ -323,6 +327,11 @@ def subcommand_clean(rest)
FileUtils.rm_rf @options[:global][:truffle_bundle_path]
end

def subcommand_readme(rest)
readme_path = File.join File.dirname(__FILE__), '..', 'README.md'
puts File.read(readme_path)
end

def print_cmd(cmd, print_always)
unless verbose? || print_always
return cmd

0 comments on commit 60b4134

Please sign in to comment.