1# Refaster templates for Tink 2 3In this directory, we store [Refaster](https://errorprone.info/%64ocs/refaster) 4templates for usage with Tink. These help users modernize the code and move to 5preferred APIs. They can be used with 6[Error Prone](https://errorprone.info/index), to automatically generated 7patches for your codebase. The templates can be found in 8`java/com/google/tink1_templates/`. 9 10In order to use them on your project, we refer to the [Refaster 11documentation](https://errorprone.info/%64ocs/refaster). 12 13We sometimes test these templates using the script below. This script 14applies the templates to the code in `java/com/google/tinkuser/*.java` 15and compares the result to the code in 16`java/com/google/tinkuser/*.java_expected` 17 18NOTE: We run the following tests manually, not as part of our continuous 19integration tests. 20 21 22```bash 23## Note: This script expects to be run from the working directory it is in. 24## (I.e., first go into the directory this README.md is in, then copy paste). 25 26## STEP 0: Switch to a directory so the remainder of the script can be run 27## without modifying the working directory. 28code_path=$(pwd) 29cd $(mktemp -d) 30 31## STEP 1: We get the 3 jar files: 32## tink-{version}-jar, error_prone_refaster-{version}.jar, and error_prone_core-{version}.jar 33## (For good measure, we verify the 3 sha256sums.) 34mkdir jars 35pushd jars 36maven_base="repo1.maven.org/maven2/com/google" 37 38# We download Tink from Head because Tink 1.9 does not have all key templates 39# This URL is found by going to https://oss.sonatype.org/ and browsing. 40readonly tink_jar="tink-HEAD-20230824.091635-3982.jar" 41readonly tink_url="https://oss.sonatype.org/service/local/repositories/snapshots/content/com/google/crypto/tink/tink/HEAD-SNAPSHOT/tink-HEAD-20230824.091635-3982.jar" 42readonly tink_sha256="ffc313081523d5acf2383a36e21cc6d5e122c3173ae81d12b4d63da00258d871" 43 44readonly errorprone_version="2.18.0" 45readonly refaster_jar="error_prone_refaster-${errorprone_version}.jar" 46readonly refaster_sha256="0cde0a3db5c2f748fae4633ccd8c66a9ba9c5a0f7a380c9104b99372fd0c4959" 47readonly errorprone_jar="error_prone_core-${errorprone_version}-with-dependencies.jar" 48readonly errorprone_sha256="2b3f2d21e7754bece946cf8f7b0e2b2f805c46f58b4839eb302c3d2498a3a55e" 49 50wget "${tink_url}" 51echo "${tink_sha256} ${tink_jar}" | sha256sum -c 52 53wget "https://${maven_base}/errorprone/error_prone_refaster/${errorprone_version}/${refaster_jar}" 54echo "${refaster_sha256} ${refaster_jar}" | sha256sum -c 55 56wget "https://${maven_base}/errorprone/error_prone_core/${errorprone_version}/${errorprone_jar}" 57echo "${errorprone_sha256} ${errorprone_jar}" | sha256sum -c 58 59popd 60 61## STEP 2: Use the current file in tink1to2 to create a "tinkrule.refaster": 62## First we delete the results of previous copy operations. 63rm -rf refaster/ ; cp -r "${code_path}" . 64 65javac -cp "jars/${tink_jar}:jars/${refaster_jar}" \ 66 "-Xplugin:RefasterRuleCompiler --out ${PWD}/tinkrule.refaster" \ 67 refaster/java/com/google/tink1_templates/AllChanges.java 68 69## STEP 3: Use error prone to create a patch: 70javac -cp "jars/${tink_jar}:jars/${errorprone_jar}" \ 71 -XDcompilePolicy=byfile \ 72 -processorpath "jars/${errorprone_jar}" \ 73 "-Xplugin:ErrorProne -XepPatchChecks:refaster:${PWD}/tinkrule.refaster -XepPatchLocation:${PWD}" \ 74 refaster/java/com/google/tinkuser/TinkUser.java 75 76patch refaster/java/com/google/tinkuser/TinkUser.java error-prone.patch 77 78diff refaster/java/com/google/tinkuser/TinkUser.java \ 79 refaster/java/com/google/tinkuser/TinkUser.java_expected 80``` 81