DOCSEARCHbyAlgolia
Submit Docs

Jar Jar Links Documentation

repository·master·Indexed 20 days ago

https://github.com/shevek/jarjar

A utility for repackaging Java libraries to embed them into distributions, preventing dependency conflicts (Jar Hell) by renaming classes and updating references via bytecode transformation. It provides an Ant task, Gradle integration, and a CLI for processing JAR files, finding dependencies, and dumping string literals.

Tokens
1.9K
Snippets
7
Records
8
Agent score
23%

What's inside Jar Jar Links

  1. How Jar Jar Links works

    master

    Jar Jar Links is a utility for repackaging Java libraries to embed them into your own distribution. This solves two main problems:

    1. Single-file distribution: You can ship a single JAR file containing all necessary dependencies.
    2. Dependency conflicts (Jar Hell): You can avoid version conflicts by renaming the classes of an embedded library so they do not collide with other versions of the same library present in the classpath.

    It works by using bytecode transformation (via ASM) to rename classes, update all internal references to those classes, transform string literals, and move associated resource files.

  2. Use Jar Jar Links with Ant

    master

    Jar Jar Links provides an Ant task named jarjar that extends the standard Ant jar task. You can use it by defining the task via taskdef and then using the <jarjar> element in your build file.

    To avoid dependency conflicts, use the <zipfileset> element to include the dependency JAR and the <rule> element to define class renaming patterns.

    Pattern Syntax:

    • **: Matches any valid package substring.
    • *: Matches a single package component (excludes dots).
    • @1, @2, etc.: References to the matched substrings from left to right.
    • @0: Reference to the entire matched class name.

    Example: Renaming org.jaxen classes to org.example.jaxen.

    <target name="jar" depends="compile">
    <taskdef name="jarjar" classname="com.tonicsystems.jarjar.JarJarTask"
        classpath="lib/jarjar.jar"/>
    <jarjar jarfile="dist/example.jar">
        <fileset dir="build/main"/>
        <zipfileset src="lib/jaxen.jar"/>
        <rule pattern="org.jaxen.**" result="org.example.@1"/>
    </jarjar>
</target>

  3. Use Jar Jar Links with Gradle

    master

    Jar Jar Links can be used within a Gradle dependencies block using the jarjar.repackage notation. This allows you to declare a dependency that is automatically repackaged.

    Available methods within the block:

    • from: Specifies the dependency to repackage (e.g., com.google.guava:guava:18.0).
    • classDelete: Removes specific classes using wildcard patterns.
    • classRename: Renames classes using a pattern and a result template.
    dependencies {
    // Use jarjar.repackage in place of a dependency notation.
    compile jarjar.repackage {
        from 'com.google.guava:guava:18.0'

        classDelete "com.google.common.base.**"

        classRename "com.google.**" "org.private.google.@1"
    }
}

  4. Configure Jar Jar Rules file

    master

    A rules file is a text file where each line contains exactly one rule. It is used with the process command to define how a JAR should be transformed.

    Rule Types:

    • rule <pattern> <result>: Renames classes matching <pattern> to <result>. All references to these classes are updated. If multiple rules match, only the first applies.
      • <pattern>: Class name with * (single component) or ** (any substring) wildcards.
      • <result>: Target class name. Supports @0 (full name) and @1, @2, etc. (wildcard captures).
    • zap <pattern>: Removes any matched classes from the resulting JAR. zap rules are processed before rule rules.
    • keep <pattern>: Marks matched classes as "roots". If any keep rules exist, all classes not reachable from these roots via dependency analysis are discarded. This is the final step in the process.
    rule org.jaxen.** org.example.@1
zap com.unused.package.**
keep com.myapp.Main

  5. Use the Jar Jar Links CLI

    master

    You can run Jar Jar Links directly from the command line using java -jar jarjar.jar.

    Commands:

    • help: Prints the help message.
    • strings <cp>: Dumps all string literals in the provided classpath <cp>. Includes line numbers if debug info is present.
    • find <level> <cp1> [<cp2>]: Prints dependencies.
      • <level>: Either class (prints dependencies between individual classes) or jar (prints jar-to-jar dependencies).
      • <cp1>: The primary classpath.
      • <cp2>: (Optional) The secondary classpath to check dependencies against. If omitted, <cp1> is used for both.
    • process <rulesFile> <inJar> <outJar>: Transforms <inJar> based on the rules in <rulesFile> and writes the result to <outJar>. Note that <outJar> will be deleted if it already exists.
    # Print help
java -jar jarjar.jar help

# Dump strings in classpath
java -jar jarjar.jar strings <cp>

# Find dependencies
java -jar jarjar.jar find class <cp1> [<cp2>]

# Process a jar with a rules file
java -jar jarjar.jar process <rulesFile> <inJar> <outJar>

  6. Use jarjar in 'find' mode to locate dependencies

    master

    The find mode identifies dependencies between two sets of files. It uses a DependencyHandler to output findings to System.out.

    Usage

    • Use --from to specify the source classpath.
    • Provide the target JAR files or directories as positional arguments.
    • If --from is not provided, the target files are used as both the source and target.
    • Use --level to control the granularity of the dependency search (e.g., CLASS).

    Example

    jarjar --mode find --from /path/to/source_libs --level CLASS target.jar
    jarjar --mode find --from /path/to/source_libs --level CLASS target.jar

  8. Use the jarjar CLI to process JAR files

    master

    The jarjar command-line tool allows you to repackage Java JAR files based on a set of rules. The primary mode is process, which transforms input JARs (or directories) into a new output JAR using a rules file.

    Modes

    • process (default): Transforms JAR files using a rules file.
    • find: Finds dependencies between sets of files.
    • strings: Dumps strings from the provided classpath.

    CLI Options

    OptionArgumentDescription
    --modestrings, find, processThe mode to run. Defaults to process.
    --levelDependencyHandler.LevelThe level for the dependency handler. Defaults to CLASS.
    --fromFile(s)Classpath used for strings and find modes.
    --rulesFileThe rules file used during process mode.
    --outputFileThe output JAR file produced during process mode.
    --helpN/APrints help information.
    (positional)File(s)The input JAR files or directories to process.

    Example: Processing a JAR

    To repackage a JAR using a rules file and saving it to a new location:

    jarjar --mode process --rules my_rules.txt --output output.jar input.jar
    jarjar --mode process --rules my_rules.txt --output output.jar input.jar