Rawr is a JRuby tool for converting a JRuby program into a more-or-less self-contained executable package.
There is not really all that much to it. There are four parts: Installing Rawr; adding rawrification to your project; turning your project into an executable jar file; turning your project into a redistributable bundle of some kind, for OSX or Windows.
There are two ways to get Rawr. One is to get the source from Github repo:
git clone git@github.com:rawr/rawr.git
You will need a few gems installed to build the Rawr gem.
hoe (3.3.0)
bones (3.8.0)
rspec (1.3.0)
You will also need to be using JRuby. You could probably build the gem using regular Ruby but Rawr is a JRuby thing so it’s better just just be in the habit of doing any Rawr stuff running JRuby.
If you can use rvm, use it, it makes it easy to switch around your current version of ruby.
On Windows (or if you are using multiple self-installed versions of Ruby) you may need to prefix all rake and gem commands with jruby -S. However you manage things, the key is to make sure you have the required gems installed for use by JRuby when needed.
So, with the rawr source acquired from Github, run rake gem.
That should make agem file for you in pkg/.
Install this gem for JRuby.
The other way to get rawr is to install a pre-built gem. Rawr gems are hosted on neurogami.com. Use this gem command:
gem i rawr --source http://gems.neurogami.com
Make whatever adjustments you need to provide proper permission and that the gem is installed for JRuby.
Once you have the gem installed, the next step is to add magic Rawr power to some JRuby project.
We’ll make a sinple project to show the steps.
First, cd to someplace suitable for throwaway programs (I created ~/tmp for stuff this).
Make a directory Foo, then cd into it.
Make sure you are using JRuby now for any Ruby commands. For example, rvm use jruby-1.7.0 or whatever gets you to the latest JRuby.
Run rawr install
You should see something like this:
james@james11:~/tmp/rawr-tests/Foo$ rawr install
Running in jruby 1.7.0 (1.9.3p203) [linux-amd64]
Create rawr files using {:wordy=>false,
:class=>"org.monkeybars.rawr.Main",
:directory=>"src",
:build_config_file=>"build_configuration.rb",
:local_jruby_jar=>nil,
:no_config=>"false",
:show_version=>false,
:no_download=>"false",
:no_jar=>"false",
:command=>["install"]}
write config file
Creating Rawr configuration file build_configuration.rb
option project_name: Foo
option output_dir: package
option executable_type: gui
option main_ruby_file: main
option main_java_file: org.monkeybars.rawr.Main
option source_dirs: ["src"]
option source_exclude_filter: []
option mirah_source_root: src
option compile_ruby_files: false
option java_lib_files: []
option java_lib_dirs: ["lib/java"]
option files_to_copy: []
option target_jvm_version: 1.6
option jvm_arguments:
option java_library_path:
option extra_user_jars: {}
option mac_do_not_generate_plist:
option mac_plist_working_directory: $APP_PACKAGE
option mac_icon_path:
option windows_icon_path:
Creating Java class /home/james/tmp/rawr-tests/Foo/src/org/monkeybars/rawr/Main.java
Creating Rakefile ...
Downloading jruby-complete.jar. This may take a moment...
All done!
james@james11:~/tmp/rawr-tests/Foo$
It’s wordy, but what Rawr does here is generate some basic project files it will later need, including a copy of jruby-complete.jar which, by default, it grabs from the jruby.org server.
rawr install will behave slightly differently under different circumstances. To see this, re-run rawr install. You should see something like this:
james@james11:~/tmp/rawr-tests/Foo$ rawr install
Running in jruby 1.7.0 (1.9.3p203) [linux-amd64]
Create rawr files using {:wordy=>false,
:class=>"org.monkeybars.rawr.Main",
:directory=>"src",
:build_config_file=>"build_configuration.rb",
:local_jruby_jar=>nil,
:no_config=>"false",
:show_version=>false,
:no_download=>"false",
:no_jar=>"false",
:command=>["install"]}
write config file
Configuration file 'build_configuration.rb' exists, skipping
Java class '/home/james/tmp/rawr-tests/Foo/src/org/monkeybars/rawr/Main.java' exists, skipping
Rakefile already contains Rawr tasks
Downloading jruby-complete.jar. This may take a moment...
All done!
james@james11:~/tmp/rawr-tests/Foo$
rawr checks your project folder to see what you already have and tries to do something sensible.
For example, it sees that you already have a file named build_configuration.rb so it does not create a new one. It also sees that you have a file named Rakefile and that it contains rawr commands.
Edit Rakefile and remove the line require 'rawr' (it should be the only line in the file).
Add some other content to the file (such as a comment).
Once again, run rawr install
You should now see this:
james@james11:~/tmp/rawr-tests/Foo$ rawr install
Running in jruby 1.7.0 (1.9.3p203) [linux-amd64]
Create rawr files using {:wordy=>false,
:class=>"org.monkeybars.rawr.Main",
:directory=>"src",
:build_config_file=>"build_configuration.rb",
:local_jruby_jar=>nil,
:no_config=>"false",
:show_version=>false,
:no_download=>"false",
:no_jar=>"false",
:command=>[“install”]}write config file
Configuration file ‘build_configuration.rb’ exists, skipping
Java class ‘/home/james/tmp/rawr-tests/Foo/src/org/monkeybars/rawr/Main.java’ exists, skipping
Rawr has found an exisiting Rakefile.
Please select one of these options:
1: Keep the current Rakefile, and add the rawr content to the top.
2: Replace the current Rakefile with a new Rakefile. You will lose everything in the current Rakefile!
3: Quit, leave the current Rakefile alone, and add nothing new.Your choice (1, 2, or 3):
Type 1 and hit “Enter”; you should see this:
Rawr will now prepend new Rawr task content to your current Rakefile ... Downloading jruby-complete.jar. This may take a moment... All done!
If you now open up Rakefile you should see require 'rawr' at the tip followed by whatever you typed in yourself.
The other options are pretty self-explanatory.
Note that no matter what, rawr downloads a copy of jruby-complete. This is a mixed blessing. Or a bug that has feature-value. If you ever want to update the copy of jruby-complete.jar in a rawr-enhanced project you can just re-run rawr install. It will go get the latest jruby-complete.jar.
You can, however, control some of this behavior by creating a .rawr config file in your home directory.
There was a time when I was creating new JRuby projects several times an hour. Downloading the same jar file from jruby.org server seemed goofy. I added the option to control some of the installation process so that I could tell rawr to go grab jruby-complete from a local folder. This is also handy if you decide that the latest version of jruby-complete.jar isn’t working for you; you can define a local copy and only update it when you are ready.
Once you’ve added Rawr super magical powers to your project you can use some rake tasks to turn you application into an executable jar, or a redistributable package.
To see what you have available, run rake -T
You should see something like this:
james@james11:~/tmp/rawr-tests/Foo$ rake -T rake rawr:base_jar # Create a base jar file rake rawr:build_extra_jars # Build all additional user jars rake rawr:bundle:app # Bundles the jar from rawr:jar into a native Mac OS X application (.app) rake rawr:bundle:exe # Bundles the jar from rawr:jar into a native Windows application (.exe) rake rawr:clean # Removes generated content rake rawr:compile # Compiles all the Java source, Mirah source, and Ruby source files in the source_dirs entry in the build_configuration.rb file. rake rawr:compile_duby_classes # Compiles the Duby source files specified in the source_dirs entry rake rawr:compile_java_classes # Compiles the Java source files specified in the source_dirs entry rake rawr:compile_mirah_classes # Compiles the Mirah source files specified in the source_dirs entry rake rawr:compile_ruby_classes # Compiles the Ruby source files specified in the source_dirs entry rake rawr:get:current-jruby # Fetch the most recent build of jruby-complete.jar. Might be an RC rake rawr:get:current-stable-jruby # Fetch the most recent stable jruby-complete.jar rake rawr:jar # Uses compiled output and creates an executable jar file.
You may see other tasks as well depending on what you have in your Rakefile.
The names of these rawr are mostly self-explanatory. You can compile different kinds of source code into .class files, with the default (rawr:compile) acting on all suitable candidates. (Note that the duby options are relics; Duby mutated into Mirah, more or less, so ignore all duby-related tasks.)
There is something of a hierarchy to these tasks, though in most cases you will most likely simply create a project jar, create a project bundle (i.e. make a redistributable package for installation), or clean up previous build attempts.
If you take a peek at build_configuration.rb you’ll see numerous configuration options, most being commented-out because they are the same as rawr default values. You need only uncomment something if you want to do something other than the default.
For example, rawr assumes your main Ruby file is main.rb and lives in your project’s src/ folder. (By “main” what is meant is that this is the file that would be executed first if this were a command-line app.) You can change c.source_dirs to be something other than ["src"], and change c.main_ruby_file to be something other than "main".
I would suggest, however, that you try to stick to the rawr conventions if possible. If nothing else, you can have a file src/main.rb that does little more than initial your app and call some other Ruby code with your actual app logic. Pretty every rawr example is going to be using src/main.rb and since it’s the rawr default you won’t have to think to change it in your own projects.
Rawr will generate a jar from all of your source files. The resulting jar will (by default) have the same name as your application. rake rawr:base_jar will create this jar.
You can also tell rawr to create additional jar files using specific directories. Perhaps you want a separate jar for image resources. rake rawr:base_jar will not create those jars.
On the other hand, if you call rake rawr:jar you will get all the jars you asked for.
Depending on your needs that may be it for you. Once you have you application converted into to jars you can treat it as any other Java executable jar:
java -jar package/jar/Foo.jar
Note that for this to work you need to have all of your application’s dependencies available. If you move (in this case) Foo.jar someplace you have to also bring along jruby-complete.jar and any other jars or resources used by your application.
Going further, many (maybe most) people use Rawr in order to create something they can distribute easily. For this you have the assorted bundle tasks.
rake rawr:bundle:app # Bundles the jar from rawr:jar into a native Mac OS X application (.app)
rake rawr:bundle:exe # Bundles the jar from rawr:jar into a native Windows application (.exe)
The task descriptions pretty much cover it. Note that (and this may seem obvious) if you distribute either the .app or .exe file a JRE (Java run-time environment) is still needed. Remember, despite the file extension, these are still Java programs (albeit ones created from Ruby files) under the hood.