Squash Java Deobfuscation Library
This gem serves three purposes:
- to upload yGuard obfuscation data to Squash,
- to map class names to their file paths, and upload that data to Squash, and
- to notify Squash of new releases of Java software (internally or externally).
This gem installs a deobfuscate
binary that converts a renamelog.xml file into
a format usable for Squash, locates the files in which classes are defined, and
then uploads that data to the Squash host. It also installs a squash_release
binary that notifies Squash of the release.
Documentation
Comprehensive documentation is written in YARD- and Markdown-formatted comments
throughout the source. To view this documentation as an HTML site, run
rake doc
.
For an overview of the various components of Squash, see the website documentation at https://github.com/SquareSquash/web.
Compatibility
This library is compatible with Ruby 1.8.6 and later, including Ruby Enterprise Edition.
Requirements
This gem requires the json
gem (http://rubygems.org/gems/json). You can use
any JSON gem that conforms to the typical standard
(require 'json'; object.to_json
).
Usage
Uploading Obfuscation and Class Path Data
This gem installs a command-line binary named deobfuscate
. It is called in the
following format:
deobfuscate [options] <API key> <environment> <build number> <renamelog file>
Example: deobfuscate --no-ssl-verification a9232f94-6c2d-45ae-8f9e-9add5bd7ff35 production 103 /path/to/renamelog.xml
This binary is intended to be used as part of your release process. It will
first parse the renamelog file and generate an internal representation of your
program's namespace, along with all obfuscated aliases. Then it will attempt to
map class names to the files in which the classes are defined. In order for this
to work, your classes should be organized in folder structures according to
their package names. For example, the source of the class com.foo.bar.Baz
should be found in a "com/foo/bar/Baz.java" file path somewhere in your project.
By default this program assumes it's being run from the project root, but you
can also specify the root with the --project-dir
switch. For documentation on
deobfuscate
's command-line options, run deobfuscate --help.
Release Notification
This gem installs a command-line binary named squash_release
. It is called in
the following format:
squash_release [options] <Squash host> <API key> <environment> <build number>
Example: squash_release http://your.squash.host a9232f94-6c2d-45ae-8f9e-9add5bd7ff35 production 103
This binary is intended to be used as part of your release process, similar to
deobfuscate
(see above). Like deobfuscate
, sensible defaults are provided
for all command line switches.
For documentation on squash_release
's command-line options, run
squash_release --help
.
Data Transmission
Deobfuscation and release data is transmitted to Squash using JSON-over-HTTPS. A
default API endpoint is pre-configured, though you can always set your own (see
deobfuscate --help
or squash_release --help
).
By default, Net::HTTP
is used to transmit errors to the API server. If you
would prefer to use your own HTTP library, see the squash_uploader
gem.
Use as a Library
In addition to using the rename map with Squash, you can also use the gem as a library, to perform deobfuscation for your own purposes (even unrelated to Squash). See the {Squash::Java::Namespace} class documentation for more information.
You will need to add this gem to your Gemfile to use it as a library:
gem 'squash_java', :require => 'squash/java'