Wormhole Jar Rewriter

A time-traveling bytecode rewriter which adds future APIs to android.jar

License

License

Categories

Categories

ORM Data
GroupId

GroupId

com.jakewharton.wormhole
ArtifactId

ArtifactId

wormhole-jar-rewriter
Last Version

Last Version

0.3.1
Release Date

Release Date

Type

Type

jar
Description

Description

Wormhole Jar Rewriter
A time-traveling bytecode rewriter which adds future APIs to android.jar
Project URL

Project URL

https://github.com/JakeWharton/wormhole/
Source Code Management

Source Code Management

https://github.com/JakeWharton/wormhole/

Download wormhole-jar-rewriter

How to add to project

<!-- https://jarcasting.com/artifacts/com.jakewharton.wormhole/wormhole-jar-rewriter/ -->
<dependency>
    <groupId>com.jakewharton.wormhole</groupId>
    <artifactId>wormhole-jar-rewriter</artifactId>
    <version>0.3.1</version>
</dependency>
// https://jarcasting.com/artifacts/com.jakewharton.wormhole/wormhole-jar-rewriter/
implementation 'com.jakewharton.wormhole:wormhole-jar-rewriter:0.3.1'
// https://jarcasting.com/artifacts/com.jakewharton.wormhole/wormhole-jar-rewriter/
implementation ("com.jakewharton.wormhole:wormhole-jar-rewriter:0.3.1")
'com.jakewharton.wormhole:wormhole-jar-rewriter:jar:0.3.1'
<dependency org="com.jakewharton.wormhole" name="wormhole-jar-rewriter" rev="0.3.1">
  <artifact name="wormhole-jar-rewriter" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.jakewharton.wormhole', module='wormhole-jar-rewriter', version='0.3.1')
)
libraryDependencies += "com.jakewharton.wormhole" % "wormhole-jar-rewriter" % "0.3.1"
[com.jakewharton.wormhole/wormhole-jar-rewriter "0.3.1"]

Dependencies

compile (1)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib-jdk8 jar 1.3.61

runtime (1)

Group / Artifact Type Version
org.ow2.asm : asm jar 7.3.1

test (4)

Group / Artifact Type Version
org.ow2.asm : asm-util jar 7.3.1
junit : junit jar 4.13
com.google.truth : truth jar 1.0.1
com.google.jimfs : jimfs jar 1.1

Project Modules

There are no modules declared in this project.

Wormhole

A time-traveling bytecode rewriter which adds future APIs to android.jar which can be desugared to all API levels by D8 and R8.

In your root build.gradle:

buildscript {
  dependencies {
    classpath 'com.jakewharton.wormhole:wormhole-gradle:0.3.1'
  }
  repositories {
    mavenCentral()
  }
}

In any Android subproject's build.gradle:

apply plugin: 'com.jakewharton.wormhole'

android {
  compileSdkVersion wormhole(29)
}

or build.gradle.kts:

import com.jakewharton.wormhole.gradle.wormhole

android {
  compileSdkVersion(wormhole(29))
}

In your code you should now be able to call methods which don't (yet) exist in the android.jar:

// Available in API 30.
List<String> names = List.of("Jake");
// Java 10 API not available in any API level yet.
List<String> copy = List.copyOf(names);

FAQ

Why?

Adding new Java APIs to android.jar is harder than it should be and slower than it should be. It's easy, in contrast, to add desugarings of future Java APIs to D8/R8.

In Android R there are new methods from Java 9 such as List.of. Thanks to D8 and R8, these are not exclusive to API 30, but instead instantly work down to API 1.

There are a set of desugarings in D8 and R8 for APIs which are not yet in android.jar. Instead of having to wait to use them, this project makes them available immediately.

Should I use this in an app?

Sure.

Should I use this in a library?

Is the library in the same repo as your app? It's safe to use.

Is the library standalone and shipped as a binary? It is not safe to use. You can't know what version of AGP/R8 your consumers are using to ensure new methods will be desugared.

Does it work with all versions of AGP(Android Gradle Plugin)?

No. It works with AGP v4.0 and above.

License

Copyright 2020 Jake Wharton

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Versions

Version
0.3.1
0.3.0
0.2.0
0.1.0