From 9e9887fcc9a104012c4d12438e4f63c5a91820f1 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 21 Oct 2019 13:37:40 +0200 Subject: [PATCH 01/38] Add maven plugin and version artifacts. --- .travis.yml | 2 +- build.gradle | 24 ++++++++++++++++++------ 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/.travis.yml b/.travis.yml index dc21891a..80e3d7b8 100644 --- a/.travis.yml +++ b/.travis.yml @@ -27,6 +27,6 @@ deploy: skip_cleanup: true api_key: secure: YxeU5GzokMXdEJqE0xpQGoOxBmJyhJA6O3y8Fl1uTGxvLCupIyTNv7AcBptCnK3YE7SHolFY9hmv9xSXVOJz+k6YqhP6k/7NAJ8TlKRatface5VDJ1zB463rGiaYdyYhJYz0jjO1j3aTHCapSGJuaBONvEQYuKh8yuR6i/GHKM1xo1hsrmU0GvSMFcMZmFN1r24JYBHFRupvEBeyo47qFNnP69XLN85lRRNy1YBVVWKPsUp/4KgU977gyxIjK1j0LlSXk/IfMh9aCQ6hly6kUa6azkKsEg6LGlc0UgHOdG6NIgsJlLT99f/YJczq2qxLPwZTT1P60A9Dp16CrVechNtiF9UulIJCXaiL9DENYB9HxmCwa+s4GtaGi/5xOcupnGgPhRYXiTM9N8J8Q5GpAKGc0yLh7dGNURi9YviJmo6uZ9YuYXB1mm+oieLi6vVoadLbGPpziX8H+j4fHKkru2QU4V73NegqAmzyOK9GdkzCT9Nqv2O55le80q16ubBrfYoyLdzOKmNo+6fY0w+pUTioZVXNovnz9vpuUR45ZBOD/3fn0kcd5YrFglpknyiJ0nLlA7TET4rDtmRqMULd23mXaNrNJf2WuCIh2AI9z3zoSeKjIFJ9YjOQzfSijM+amvVvfGNSphwGtlJhgcPOMZWSgIYuMLGLdqqnE9loQUc= - file: build/distributions/yguard-${TRAVIS_TAG}.zip + file: build/distributions/yguard-bundle-${TRAVIS_TAG}.zip on: tags: true diff --git a/build.gradle b/build.gradle index 6f31a2f7..a9741318 100644 --- a/build.gradle +++ b/build.gradle @@ -2,13 +2,16 @@ plugins { // Apply the java and library plugin to add support for Java id 'java' id 'java-library-distribution' + // Apply the maven plugin to add support for publications + id 'maven-publish' - // Apply yWorks coding style with editorconfig + // Apply yWorks coding style with editorconfig id 'org.ec4j.editorconfig' version '0.0.3' } allprojects { apply plugin: 'org.ec4j.editorconfig' + version = String.format("%s.%s", VERSION_MAJOR, VERSION_MINOR) } repositories { @@ -44,22 +47,20 @@ jar { } } -def VERSION = String.format("%s.%s", project.findProperty('VERSION_MAJOR'), project.findProperty('VERSION_MINOR')) - distributions { bundle { - baseName = String.format("yguard-%s", VERSION) + baseName = "yguard-bundle" contents { from file("$projectDir/LICENSE") into("lib") { - from configurations.dependents.filter { it.name in DEPENDANT_JARS.plus('ObfuscationAnnotation.jar') } + from configurations.dependents.filter { it.name in DEPENDANT_JARS.plus(String.format("ObfuscationAnnotation-%s.jar", version)) } from jar } into("docs") { from "$projectDir/docs" filter { line -> line - .replaceAll('@VERSION@', VERSION) + .replaceAll('@VERSION@', version) .replaceAll('@VERSION_MAJOR@', project.findProperty('VERSION_MAJOR')) } } @@ -73,3 +74,14 @@ editorconfig { } check.dependsOn editorconfigCheck + +publishing { + publications { + maven(MavenPublication) { + groupId = 'com.yworks' + artifactId = 'yguard' + + from project.components.java + } + } +} From 2832d3234c338ae75b2f26a631ba385b27c63f7d Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 21 Oct 2019 15:08:22 +0200 Subject: [PATCH 02/38] Add ant application example. --- .gitignore | 6 ++ examples/application/build.xml | 67 +++++++++++++++++++ .../src/com/yworks/example/HelloWorld.java | 8 +++ 3 files changed, 81 insertions(+) create mode 100644 examples/application/build.xml create mode 100644 examples/application/src/com/yworks/example/HelloWorld.java diff --git a/.gitignore b/.gitignore index c564ce64..81b6ac52 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,9 @@ yshrinklog.xml lib/ node_modules/ + +# Ignore example files +examples/*/build +examples/*/lib +examples/*/*log.xml + diff --git a/examples/application/build.xml b/examples/application/build.xml new file mode 100644 index 00000000..19f26db2 --- /dev/null +++ b/examples/application/build.xml @@ -0,0 +1,67 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/application/src/com/yworks/example/HelloWorld.java b/examples/application/src/com/yworks/example/HelloWorld.java new file mode 100644 index 00000000..ab2602fe --- /dev/null +++ b/examples/application/src/com/yworks/example/HelloWorld.java @@ -0,0 +1,8 @@ +package com.yworks.example; + +public class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello World"); + } +} + From 733f86856fa25e870bd18a21dffb523539130408 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 21 Oct 2019 15:53:05 +0200 Subject: [PATCH 03/38] Move HelloWorld to correct folder structure for Maven/Gradle. --- .../src/{ => main/java}/com/yworks/example/HelloWorld.java | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename examples/application/src/{ => main/java}/com/yworks/example/HelloWorld.java (100%) diff --git a/examples/application/src/com/yworks/example/HelloWorld.java b/examples/application/src/main/java/com/yworks/example/HelloWorld.java similarity index 100% rename from examples/application/src/com/yworks/example/HelloWorld.java rename to examples/application/src/main/java/com/yworks/example/HelloWorld.java From 6e888e507725a6e5af97f8c25ff449ffbdaca728 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 21 Oct 2019 16:49:12 +0200 Subject: [PATCH 04/38] Add maven sample. --- .gitignore | 2 +- examples/application/pom.xml | 91 ++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 examples/application/pom.xml diff --git a/.gitignore b/.gitignore index 81b6ac52..e717632b 100644 --- a/.gitignore +++ b/.gitignore @@ -48,6 +48,6 @@ node_modules/ # Ignore example files examples/*/build +examples/*/target examples/*/lib examples/*/*log.xml - diff --git a/examples/application/pom.xml b/examples/application/pom.xml new file mode 100644 index 00000000..07a1afac --- /dev/null +++ b/examples/application/pom.xml @@ -0,0 +1,91 @@ + + 4.0.0 + com.yworks.example + HelloWorld + jar + 1.0-SNAPSHOT + HelloWorld + http://maven.apache.org + + 1.7 + 1.7 + com.yworks.example.HelloWorld + 2.9.x + ../../ + + + + + maven-antrun-plugin + 1.8 + + + package + copy-libs + + + + + + + + + + + + + + run + + + + + + maven-antrun-plugin + 1.8 + + + package + + run + + obfuscate + + + + + + + + + + + + + + + + + + + + + + + + + org.apache.maven.plugins + maven-jar-plugin + 2.4 + + + + com.yworks.example.HelloWorld + + + + + + + From 2c250e14d83234492dd4096a38bc9fa312212888 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 21 Oct 2019 16:49:58 +0200 Subject: [PATCH 05/38] Move obfuscate.gradle to examples. --- gradle/obfuscate.gradle => examples/application/build.gradle | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename gradle/obfuscate.gradle => examples/application/build.gradle (100%) diff --git a/gradle/obfuscate.gradle b/examples/application/build.gradle similarity index 100% rename from gradle/obfuscate.gradle rename to examples/application/build.gradle From 3a5cef2604e206d615c9ac2cc1c0c5742f61429d Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 21 Oct 2019 17:14:25 +0200 Subject: [PATCH 06/38] Add Gradle example. --- examples/application/build.gradle | 78 +++++++++++++------------- examples/application/gradle.properties | 1 + examples/application/pom.xml | 1 - examples/application/settings.gradle | 1 + 4 files changed, 41 insertions(+), 40 deletions(-) create mode 100644 examples/application/gradle.properties create mode 100644 examples/application/settings.gradle diff --git a/examples/application/build.gradle b/examples/application/build.gradle index 13f4aed2..2224f480 100644 --- a/examples/application/build.gradle +++ b/examples/application/build.gradle @@ -1,50 +1,50 @@ -task obfuscate { - dependsOn jar +plugins { + // Apply the java and library plugin to add support for Java + id 'application' +} + +application { + mainClassName = 'com.yworks.example.HelloWorld' +} + +jar { + manifest { + attributes( + 'Main-Class': application.mainClassName + ) + } +} + +task copylibs(type: Copy) { + def zipFile = file("../../build/distributions/yguard-${VERSION}.zip") + def outputDir = file("${buildDir}/lib") + + from zipTree(zipFile) + into outputDir +} + +task yguard { + dependsOn jar, copylibs group 'yGuard' description 'Obfuscates and shrinks the java archive.' doLast { - def classPath = configurations.runtimeClasspath.getAsPath() - def archivePath = jar.getArchiveFile().get().getAsFile().getPath(); - ant.taskdef( - name: 'obfuscate', - classname: 'com.yworks.yguard.ObfuscatorTask', - classpath: String.format("%s:%s", classPath, archivePath) + name: 'yguard', + classname: 'com.yworks.yguard.YGuardTask', + classpath: "${buildDir}/lib/yguard-${VERSION}/lib/yguard.jar" ) - ant.obfuscate( - shrink: true, - useExposeAsEntrypoints: true, - conservemanifest: false, - replaceclassnamestrings: true - ) { - property(name: "naming-scheme", value: "small") - property(name: "language-conformity", value: "compatible") - inoutpair(in: archivePath, out: archivePath.replace(".jar", "_obfuscated.jar")) - expose { - 'class'(classes: "private", fields: "private", methods: "private") { - patternset { - include(name: "com.yworks.yguard.obf.") - include(name: "com.yworks.yguard.Conversion") - include(name: "com.yworks.yguard.ObfuscationListener") - include(name: "com.yworks.yguard.ParseException") - } - } - 'class'(classes: "none", methods: "public", fields: "none") { - patternset { - include(name: "com.yworks.yguard.ObfuscatorTask*") - include(name: "com.yworks.yguard.ant.*") - include(name: "com.yworks.yguard.common.ant.*") - include(name: "com.yworks.yshrink.ant.*") - } + def archivePath = jar.archiveFile.get().asFile.path + ant.yguard { + inoutpair(in: archivePath, out: archivePath.replace(".jar", "_obf.jar")) + shrink(logfile: "${buildDir}/yshrink.log.xml") { + keep { + method(name: "void main(java.lang.String[])", "class": application.mainClassName) } - 'class'(name: "com.yworks.yguard.common.ant.YGuardBaseTask", classes: "public", methods: "public", fields: "none") - 'class'(name: "com.yworks.yguard.ObfuscatorTask", classes: "public", methods: "public", fields:"none") - 'class'(name: "com.yworks.yguard.yshrink.YShrinkModelImpl", classes: "public", methods: "public", fields: "none") - 'class'(name: "com.yworks.yguard.yshrink.YShrinkInvokerImpl", classes: "public", methods: "public", fields: "none") - 'class'(name: "com.yworks.yguard.YGuardTask", classes: "public", methods: "public", fields: "none") - method(class: "com.yworks.yguard.YGuardLogParser", name: "void main(java.lang.String[])") + } + rename(mainclass: application.mainClassName, logfile: "${buildDir}/yguard.log.xml") { + property(name: "error-checking", value: "pedantic") } } } diff --git a/examples/application/gradle.properties b/examples/application/gradle.properties new file mode 100644 index 00000000..909245f9 --- /dev/null +++ b/examples/application/gradle.properties @@ -0,0 +1 @@ +VERSION=2.9.x diff --git a/examples/application/pom.xml b/examples/application/pom.xml index 07a1afac..5aed49da 100644 --- a/examples/application/pom.xml +++ b/examples/application/pom.xml @@ -53,7 +53,6 @@ obfuscate - diff --git a/examples/application/settings.gradle b/examples/application/settings.gradle new file mode 100644 index 00000000..b34111ec --- /dev/null +++ b/examples/application/settings.gradle @@ -0,0 +1 @@ +rootProject.name = 'example' From 510e44b72501e0ae9a804ca4f4cc7b2ee54f6641 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 21 Oct 2019 17:14:42 +0200 Subject: [PATCH 07/38] Remove unneeded java plugin. --- build.gradle | 1 - 1 file changed, 1 deletion(-) diff --git a/build.gradle b/build.gradle index 6f31a2f7..bd3bd36c 100644 --- a/build.gradle +++ b/build.gradle @@ -1,6 +1,5 @@ plugins { // Apply the java and library plugin to add support for Java - id 'java' id 'java-library-distribution' // Apply yWorks coding style with editorconfig From 8301c165d3c7bff8756e7a63b4d12b213e3808ff Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 28 Oct 2019 13:01:37 +0100 Subject: [PATCH 08/38] Clean up LIBRARY_JARS usage when bundling. --- build.gradle | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/build.gradle b/build.gradle index a9741318..8f2d2480 100644 --- a/build.gradle +++ b/build.gradle @@ -19,12 +19,14 @@ repositories { } configurations { + annotation dependents.extendsFrom implementation } dependencies { - implementation project(':retroguard') + annotation project(':annotation') implementation project(':annotation') + implementation project(':retroguard') implementation 'com.google.guava:guava:28.1-android' implementation 'org.ow2.asm:asm:7.2' implementation 'org.apache.ant:ant:1.10.7' @@ -36,12 +38,17 @@ compileJava { targetCompatibility = 1.7 } -def DEPENDANT_JARS = ["retroguard.jar", "asm-7.2.jar", "guava-28.1-android.jar", "failureaccess-1.0.1.jar"] +def LIBRARIES = [String.format("retroguard-%s.jar", version), "guava-28.1-android.jar", "asm-7.2.jar"] +def LIBRARY_JARS = configurations.dependents.filter { + file -> file.name in LIBRARIES +} jar { manifest { attributes( - 'Class-Path': String.join(" ", *DEPENDANT_JARS), + 'Class-Path': String.join(" ", *LIBRARY_JARS.collect { + file -> file.name + }), 'Main-Class': 'com.yworks.yguard.YGuardLogParser' ) } @@ -53,7 +60,8 @@ distributions { contents { from file("$projectDir/LICENSE") into("lib") { - from configurations.dependents.filter { it.name in DEPENDANT_JARS.plus(String.format("ObfuscationAnnotation-%s.jar", version)) } + from LIBRARY_JARS + from configurations.annotation from jar } into("docs") { From 6a0a1edd97594acd302c471e764f4255af2664fb Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 28 Oct 2019 13:25:31 +0100 Subject: [PATCH 09/38] Add missing ant dependency. --- build.gradle | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.gradle b/build.gradle index 8f2d2480..ef229a1d 100644 --- a/build.gradle +++ b/build.gradle @@ -38,7 +38,7 @@ compileJava { targetCompatibility = 1.7 } -def LIBRARIES = [String.format("retroguard-%s.jar", version), "guava-28.1-android.jar", "asm-7.2.jar"] +def LIBRARIES = [String.format("retroguard-%s.jar", version), "guava-28.1-android.jar", "asm-7.2.jar", "ant-1.10.7.jar"] def LIBRARY_JARS = configurations.dependents.filter { file -> file.name in LIBRARIES } From 01d9c31fd2067f49f9862ba1bae6b7080e93a37d Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 28 Oct 2019 13:33:44 +0100 Subject: [PATCH 10/38] Update build.xml to reflect new versioned jars. --- examples/application/build.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/application/build.xml b/examples/application/build.xml index 19f26db2..7d69ac0f 100644 --- a/examples/application/build.xml +++ b/examples/application/build.xml @@ -33,18 +33,18 @@ - + - + - + - + From c9bbd41f5830df9fe51432963a930e09b9c83fee Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 28 Oct 2019 14:10:22 +0100 Subject: [PATCH 11/38] Add publications for annotation and retroguard. --- build.gradle | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/build.gradle b/build.gradle index ef229a1d..8d07b716 100644 --- a/build.gradle +++ b/build.gradle @@ -91,5 +91,19 @@ publishing { from project.components.java } + + annotation(MavenPublication) { + groupId = 'com.yworks.yguard' + artifactId = 'annotation' + + from project(':annotation').components.java + } + + retroguard(MavenPublication) { + groupId = 'com.yworks.yguard' + artifactId = 'retroguard' + + from project('retroguard').components.java + } } } From a97ae4934f91e12b2a5bce757fb10821435e98c8 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 28 Oct 2019 14:22:04 +0100 Subject: [PATCH 12/38] Set group correctly for all projects. --- build.gradle | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/build.gradle b/build.gradle index 8d07b716..30b406a9 100644 --- a/build.gradle +++ b/build.gradle @@ -12,6 +12,7 @@ plugins { allprojects { apply plugin: 'org.ec4j.editorconfig' version = String.format("%s.%s", VERSION_MAJOR, VERSION_MINOR) + group = 'com.yworks' } repositories { @@ -86,21 +87,18 @@ check.dependsOn editorconfigCheck publishing { publications { maven(MavenPublication) { - groupId = 'com.yworks' artifactId = 'yguard' from project.components.java } annotation(MavenPublication) { - groupId = 'com.yworks.yguard' artifactId = 'annotation' from project(':annotation').components.java } retroguard(MavenPublication) { - groupId = 'com.yworks.yguard' artifactId = 'retroguard' from project('retroguard').components.java From 222050d5f957f757ed6f71fdeaba439602c90759 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 28 Oct 2019 14:32:24 +0100 Subject: [PATCH 13/38] Update maven project to use yGuard from repository. --- examples/application/pom.xml | 62 +++++++++++++----------------------- 1 file changed, 22 insertions(+), 40 deletions(-) diff --git a/examples/application/pom.xml b/examples/application/pom.xml index 5aed49da..6db9109e 100644 --- a/examples/application/pom.xml +++ b/examples/application/pom.xml @@ -11,36 +11,17 @@ 1.7 1.7 com.yworks.example.HelloWorld - 2.9.x - ../../ + + + com.yworks + yguard + 2.9.x + compile + + - - maven-antrun-plugin - 1.8 - - - package - copy-libs - - - - - - - - - - - - - - run - - - - maven-antrun-plugin 1.8 @@ -53,21 +34,22 @@ obfuscate - - - + + + + - - - - - - + + + + + + - - - - + + + + From 4982c4cf9b3b2caf47f2a2425450bfcaccc3067f Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 28 Oct 2019 14:41:18 +0100 Subject: [PATCH 14/38] Modify build.gradle to use maven based compilation dependencies. --- examples/application/build.gradle | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/examples/application/build.gradle b/examples/application/build.gradle index 2224f480..cb01cd34 100644 --- a/examples/application/build.gradle +++ b/examples/application/build.gradle @@ -15,16 +15,17 @@ jar { } } -task copylibs(type: Copy) { - def zipFile = file("../../build/distributions/yguard-${VERSION}.zip") - def outputDir = file("${buildDir}/lib") +repositories { + mavenLocal() + mavenCentral() +} - from zipTree(zipFile) - into outputDir +dependencies { + compile 'com.yworks:yguard:2.9.x' } task yguard { - dependsOn jar, copylibs + dependsOn jar group 'yGuard' description 'Obfuscates and shrinks the java archive.' @@ -32,7 +33,7 @@ task yguard { ant.taskdef( name: 'yguard', classname: 'com.yworks.yguard.YGuardTask', - classpath: "${buildDir}/lib/yguard-${VERSION}/lib/yguard.jar" + classpath: sourceSets.main.runtimeClasspath.asPath ) def archivePath = jar.archiveFile.get().asFile.path From 0a88a6df253263f0bfa42421a3fcf22cafcb7aee Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 28 Oct 2019 16:49:32 +0100 Subject: [PATCH 15/38] Add CHANGELOG.md to replace old custom-made CHANGELOG. --- CHANGELOG.md | 273 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..f6f2f2f6 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,273 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [2.9.0] - 2019-10-17 +### Changed +- Replaced legacy build system with Gradle. +- Added `retroguard` dependency (LGPL-licensed) + +## [2.8.0] - 2019-10-02 +### Changed +- Replaced `y.base.Edge`, `y.base.Node` and `y.base.Graph` with a custom wrapper around Guava +- Removed parts licensed under `LGPL` into a dedicated library, which is linked statically. +- Relicensed the project under `MIT` + +## [2.7.2] - 2019-09-26 +### Fixed +- Fixed `UnsupportedOperationException` that occurred for Java 11 class files when excluding classes from obfuscation using the `extends` or `implements` attributes of the `rename.keep.class` element in the yGuard ANT task. +- Fixed yGuard's `language-conformity` mode `illegal` to no longer produce unqualified names that contain dots or spaces. + +## [2.7.1] - 2019-02-26 +### Added +- Added support for the `MethodParameters` attribute, which was introduced with the Java 8 `.class` file format. + +### Fixed +- Fixed `ClassCastException` that occurred when obfuscating Java 11 class files with `String` concatentation. +- Fixed `IllegalArgumentException` that occurred when excluding classes from obfuscation using the `extends` or `implements` attributes of the `rename.keep.class` element in the yGuard ANT task. + +## [2.7] - 2019-02-05 +### Added +- Added basic Java 11 class file support. +- Added Java 9 and Java 10 class file support. +- Added support for stacktraces with module prefixes. +- Added support for stacktraces with obfuscation prefixes. + +### Changed +- Improved translation of overloaded methods. + +## [2.6] - 2017-06-12 +### Added +- Added support for [Java 8 Type Annotations](https://blogs.oracle.com/java-platform-group/java-8s-new-type-annotations). +- The `implements` attribute now considers types in `` as well when determining the interfaces implemented by a given class. + +### Fixed +- Fixed incorrect obfuscation of `invokedynamic` instructions leading to AbstractMethodErrors of class files which had their constant pool entry order permutated for some reason (for example by the JarJar plugin for maven). + +### Changed +- Changed the class file version of the yGuard library, so yGuard can be run with Java 7 again. + +## [2.5.5] - 2017-01-27 +### Fixed +- Fixed `IllegalArgumentException: "Invalid fully qualified name (b)"` that occurred when referencing or attempting to obfuscate classes that start with a dollar ('$') sign. + +## [2.5.4] - 2016-02-19 +### Fixed +- Fixed `IllegalArgumentException` caused by Java 8 compatibility problems that arose in certain situations, for example when using hierarchy based keep instructions. + +## [2.5.3] - 2015-04-01 +### Fixed +- Fixed incorrect obfuscation of `invokedynamic` instructions leading to `AbstractMethodError` when using default methods. + +## [2.5.2] - 2014-03-17 +### Added +- Added support for renaming `META-INF/services` entries if the entry corresponds to a type that is obfuscated. + +### Fixed +- Fixed a bug that caused the stacktrace deobfuscation tool to ignore class name mappings that started with one or more $ characters. + +## [2.5.1] - 2013-10-30 +### Fixed +- Fixed broken binary class file of the attached `com.yworks.util.annotation.Obfuscation` annotation in `ObfuscationAnnotation.jar`. + +## [2.5] - 2013-10-23 +### Added +- Added support for controlling obfuscation exclusion via annotations. +- Improved Java 7 support. yGuard does now support `invokedynamic` in the obfuscation process. + +## [2.4.0.1] - 2012-09-28 +### Fixed +- Fixed a regexp that could cause yGuard to parse manifest files for a very long time. + +## [2.4] - 2011-09-20 +### Added +- Added basic Java 7 class file support + +### Fixed +- Fixed a bug that caused yGuard to introduce invalid signatures for typed classes with inner classes. +- Fixed a bug that caused yGuard to erroneously exclude all classes from obfuscation when an `implements` attribute was used for a `` element without an additional `name` or `expose` attribute. +- Fixed a bug that caused the shrinker to ignore the `` element if the default shrinking settings were used (i.e. if no `` element was defined). + +## [2.3.0.1] - 2010-06-22 +### Fixed +- Fixed a bug that caused the shrinker to remove the static initializer of a non-static inner class, when only fields of the inner class were referenced (e.g. compiler-generated switch map tables for enums). + +## [2.3.0] - 2008-10-06 +### Added +- yGuard won't try to initialize external classes needed for resolving anymore. +- The default behavior of the shrinker was changed to keep any referenced runtime visible annotation and parameter annotation attributes. + +### Fixed +- Fixed a bug that caused the shrinker to remove the enclosing method of anonymous inner classes declared as entry points. +- The shrinker will now correctly adhere to the "lineNumberTable", "runtimeVisibleParameterAnnotations" etc. attributes of the `` element. +- Fixed a bug that caused the shrinker to remove referenced Annotation elements from Annotation interfaces. +- yGuard now won't rename or remove the package-info class. +- Fixed possible "Illegal group reference" Exception in yGuard's parse tool. +- The shrinker will now keep classes that are used as field types of referenced fields. +- The shrinker will now correctly keep method attributes of methods that are kept as stubs. + +## [2.2.0] - 2007-04-26 +### Added +- yGuard is now fully JDK-1.6 compatible. +- The yGuard task now supports a way of specifying a set of jars that should be obfuscated at the same time using simple patternset syntax. +- yGuard now uses the same technique for all elements in the MANIFEST file to adjust fully qualified class name strings. +- It is now possible to tell yGuard not to obfuscate specific package names. +- yGuard can now be given a list of digest algorithms that will be used to create the digests in the manifest. +- yGuard now issues a warning if the package or class or method name of a native method is obfuscated. + +## [2.1.0] - 2006-10-12 +### Added +- Added `overloadEnabled` property + +### Fixed +- Fixed a bug that caused yGuard to throw a `NullPointerException` if a `attribute` element contained no nested `patternset`. +- Fixed a bug that caused yGuard to use multiple logging instances if a yGuard task was executed multiple times. +- Fixed LineNumberTable and SourceFile elements + +## [2.0.3] - 2006-08-09 +- Fixed a bug that broke the nested `map` element of the `rename` element. + +## [2.0.2] - 2006-07-31 +### Fixed +- Fixed a bug that caused yGuard to fail during class file parsing if a method signature contained an inner class of a parameterized class. +- yGuard will not complain about the Java 1.5 attributes `Bridge`, `Enum` and `Varargs` as "unknown attributes" anymore. +- Fixed a bug that caused all classnames to be kept from renaming if the `extends` attribute was used in combination with the `classes` attribute. + +## [2.0.1] - 2006-07-12 + +### Fixed +- Fixed an inconsistency between the interpretation of the Ant syntax in the `rename` and `shrink` elements. Now, both elements apply `patternset` elements in nested `method` and `field` elements to class names, just as stated in the yGuard documentation. + +### Changed +- If the `classes` attribute of the `class` element is not set or set to "none", the shrinking engine will now include the classes that match based on the given `name` attribute or nested `patternset`, effectively ignoring the classes attribute. + +## [2.0] - 2006-06-22 +### Added +- New elaborate code shrinking functionality. +- More powerful ant syntax: `extends/implements` attributes for the `class` element. +- yGuard now needs Java2 SDK 1.4.x or greater to function properly. + +### Changed +- General Ant syntax changes due to the introduction of the new `yguard`, `shrink` and `rename` elements. + +## [1.5.0_03] +### Fixed +- Fixed bad treatment of the new enclosing method feature in Tiger which sometimes led to AbstractMethodErrors at runtime. + +## [1.5.0_02] - 2005-05-31 +### Fixed +- Fixed bad annotation handling for non-trivial annotations. Annotations had not been parsed and handled correctly, which could lead to either errors during obfuscation or Errors at runtime. + +### Changed +- Improved obfuscation logic for enumerations. Now the two static methods valueOf(String) and values() don't have to be exposed manually anymore. + +## [1.5.0_01] - 2005-05-24 +### Fixed +- Fixed a bug that made yGuard ignore some of the attributes in the expose section ("sourcefile" and "linenumbertable"). +- Fixed a rare but severe bug that accidentally removed method attributes and sometimes led to `ArrayIndexOutOfBoundsExceptions` during the obfuscation. + +## [1.5] - 2005-05-19 +### Added +- Added JDK 1.5 (a.k.a Java 5.0 code-named Tiger) compatibility. yGuard can now deal correctly with the new JDK and Java features: generics, var-args, enumerations, annotations, new `.class` bytecode construct, signatures, local variable type table, enclosing method information. +- Implemented the ability to obfuscate/scramble/shrink line number information. This makes it possible to more easily debug stacktraces without exposing line number information in the obfuscated version of the application. +- Implemented the ability to obfuscate the source file information. This is necessary in order to view line number information in stack traces. It is now possible to reassign the source file attribute inside class files so that the original source file name is not exposed in the obfuscated application. +- Added the ability to determine on a per-class basis what attributes to expose or obfuscate. This includes line number information (with optional scrambling/compression or removal), source file attributes, deprecation attributes, etc. This makes it easy to obfuscate parts of your application while keeping the public API untouched and debug information for third party jars intact. +- Improved the stacktrace deobfuscation tool. It can now unscramble line number information from stacktraces, features a more polished view of the mapping rules and deobfuscates stacktraces more reliably if the stacktraces are ambiguous. + +## [1.3.2] - 2004-09-08 +### Added +- yGuard now helps in the detection of duplicate class files in source jars. In pedantic mode yGuard will terminate if duplicate classes are detected in different source jars. yGuard's obfuscate task will always fail if mutliple class files containing a definition for the same jar are detected. The log file displays useful information for finding the duplicate entries. +- Improved xml log file output for Unicode characters. + +### Fixed +- Fixed a name clash problem that occurred when already obfuscated code was being obfuscated again using different settings. +- Fixed a resolution problem concerning interfaces from external classpaths. + +### Changed +- Improved name generation. yGuard will now generate legal identifiers (with respect to `Character.isJavaIdentifierStart()` and `Character.isJavaIdentifierPart(char)` and `Character.isIdentifierIgnorable(char))` and should therefor produce jars that should verify correctly even on older jdks if yGuard is run using newer jdks. +- Made the log file viewer output more consistent with inner class names that were being mapped during obfuscation versus those who remained fixed. +- Jar file entries are now being sorted prior to being written to the jar. +- Improved handling of external classes. + +## [1.3.1_01] - 2004-04-27 +### Fixed +- Fixed a problem concerning the adjust elements throwing a RuntimeException in the pattern matching code. +- Fixed a problem where the wrong set of files was affected in the adjust section. + +### Changed +- yGuard now treats the _COMPATIBLE_ flag for the language conformity different. Field names and class names are now made up of lower ascii-only chars. + +## [1.3.1] - 2004-03-02 +### Added +- Improved the optional keeping of "Deprecated" tags. Somehow they still seem to get lost under certain conditions. Any feedback on this topic is welcomed. + +### Fixed +- Due to a compile time dependency, yGuard could not be used with jdk 1.3.x anymore even if the automatic resource adjustment feature was not used. This has now been made possible again. +- Fixed a rare problem that broke obfuscated code using static method invocations and static field references. +- There was a bug in the log file viewer (`java -jar yguard.jar [logfile.xml[.gz]]`) that made it crash under very rare circumstances. +- Implemented a workaround for an Ant incompatibility problem, which resulted in yGuard behaving differently on different platforms and in conjunction with different Ant versions. + +### Changed +- yGuard will now generate (empty) directory entries in the resulting jar files for each non-empty directory. + +## [1.3] - 2004-01-05 +### Added +- Added automatic text file and property file renaming mechanism. yGuard can now be configured to rename `.properties` files according to the obfuscation. +- It is now possible to process text files and replace occurances of class names with their obfuscated versions. +- One can now specify whether resource files should be kept in their original directory while at the same time the classes residing in the respective directory can be fully obfuscated to another package. +- yGuard can now automatically create gzipped (.gz) logfiles and work directly on compressed logfiles. This reduces the size of the logfiles drastically. +- It is now possible to simply specify a list of attributes, that should not be removed by yGuard (for example `Deprecated`) using the expose-attributes property. +- yGuard has a new name generation method (`language-conformity = compatible`), that creates jar file that can be successfully unzipped to the windows filesystem. +- In order to avoid namespace clashes, one can now easily specify a prefix for completeley obfuscated package hierarchies using the `obfuscation-prefix` property. +- Enhanced documentation (DTD, examples, and new features description). + +### Fixed +- Innerclasses making use of the .class construct should now always be correctly obfuscated using the replaceClassNameStrings feature. +- The `patch` element had a bug concerning field name mappings, which is now resolved. +- yGuard now tests whether a newly obfuscated name already exists in external jars and automatically generates names, that should not clash. +- yGuard should now work together with Ant version 1.6 (there was an undocumented change in the API of Ant). + +## [1.2] +### Added +- Added support for external libraries. This allows yGuard to obfuscate jars that have external dependencies more easily and using stronger obfuscation. It is now possible to specify dependencies using Ant classpath elements. yGuard then uses information found in these jars to resolve external dependencies. +- Improved error handling and task and logfile output. yGuard will now produce fewer unreasonable warnings. During the obfuscation run yGuard will give more detailed warnings and hints when unobfuscatable classes are detected. +- Added property error-checking which can be set to **pedantic**. In this case yGuard will not issue warnings but a build will fail instead of issueing simple warnings. This helps in finding problems. + +### Fixed +- Fixed a minor issue. The documentation stated, that: `` behaved like ` + + + +` but in the implementation `` had been applied. This has now been fixed to ``. +- Fixed some bugs in the documentation. + +## [1.1] - 2002-12-17 +### Added +- Added support for different naming schemes. These schemes result in smaller jar files, better obfuscation and lead to jar files, which cannot be unpacked to normal filesystems. +- Fixed two JBuilder incompatibilities. Innerclasses created by JBuilder do not prevent yGuard from working anymore and (correct) innerclasses created by yGuard do not crash JBuilder anymore (which btw. is a bug in JB). +- yGuard can now automatically obfuscate code of the form `Class.forName("com.mycompany.myapp.MyClass");` so that these classes can now be obfuscated by name, too. + +### Fixed +- Implemented a fix for the problem, where the `ClassName.class` code construct prevented classes from being obfuscated entirely. +- Fixed two bugs concerning the handling of manifest files. +- Fixed a bug concerning the handling of the `Main-Class` attribute of manifest files. + +### Changed +- Improved the serialization of the obfuscation map to the xml file, which can now be parsed back in by the included tool even for complicated naming schemes. +- Refactored the creation of the final jar files. The current implementation leads to more standard conform jar files. + +## [1.0.0] - 2002-11-28 +### Added +- The `Main-Class` attribute of the Manifest files will now be translated to the obfuscated name, if the main class is not exposed. + +### Changed +- Implemented more robust handling of Manifest files. Implementation now makes use of `java.util.jar.Manifest`. +- The `conserveManifest` attribute of the obfuscate task now conserves the manifest in a better way. + +[Unreleased]: https://github.com/yworks/yguard/compare/2.9.0...HEAD +[2.9.0]: https://github.com/yworks/yguard/compare/2.8.0...2.9.0 +[2.8.0]: https://github.com/yWorks/yguard/tree/2.8.0 From 3c16b5c75e86ca1605dab7da25ecfd3eb8b2922e Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 4 Nov 2019 17:18:30 +0100 Subject: [PATCH 16/38] Initial move from old HTML to Jekyll. --- docs/.gitignore | 5 + docs/3rdPartyLicenses/ant-license.txt | 204 -- docs/3rdPartyLicenses/asm-license.txt | 30 - docs/3rdPartyLicenses/guava-license.txt | 203 -- docs/3rdPartyLicenses/retroguard-LGPL.txt | 504 ---- docs/404.html | 25 + docs/Gemfile | 30 + docs/Gemfile.lock | 256 ++ docs/_config.yml | 57 + docs/_layouts/default.html | 49 + docs/ant/antmanual.css | 0 docs/ant/yguard.html | 78 - docs/compatibility.md | 27 + docs/documentation.css | 686 ----- docs/index.html | 820 ------ docs/index.md | 26 + docs/install.md | 90 + docs/internal-doc.html | 299 -- docs/task_documentation.md | 1465 ++++++++++ docs/test.xml | 172 -- docs/troubleshooting.md | 23 + docs/yguard_ant_howto.html | 3202 --------------------- 22 files changed, 2053 insertions(+), 6198 deletions(-) create mode 100644 docs/.gitignore delete mode 100644 docs/3rdPartyLicenses/ant-license.txt delete mode 100644 docs/3rdPartyLicenses/asm-license.txt delete mode 100644 docs/3rdPartyLicenses/guava-license.txt delete mode 100644 docs/3rdPartyLicenses/retroguard-LGPL.txt create mode 100644 docs/404.html create mode 100644 docs/Gemfile create mode 100644 docs/Gemfile.lock create mode 100644 docs/_config.yml create mode 100644 docs/_layouts/default.html delete mode 100644 docs/ant/antmanual.css delete mode 100644 docs/ant/yguard.html create mode 100644 docs/compatibility.md delete mode 100644 docs/documentation.css delete mode 100644 docs/index.html create mode 100644 docs/index.md create mode 100644 docs/install.md delete mode 100644 docs/internal-doc.html create mode 100644 docs/task_documentation.md delete mode 100644 docs/test.xml create mode 100644 docs/troubleshooting.md delete mode 100644 docs/yguard_ant_howto.html diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..f40fbd8b --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +_site +.sass-cache +.jekyll-cache +.jekyll-metadata +vendor diff --git a/docs/3rdPartyLicenses/ant-license.txt b/docs/3rdPartyLicenses/ant-license.txt deleted file mode 100644 index 1c572e31..00000000 --- a/docs/3rdPartyLicenses/ant-license.txt +++ /dev/null @@ -1,204 +0,0 @@ -/* - * Apache License - * Version 2.0, January 2004 - * http://www.apache.org/licenses/ - * - * TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - * - * 1. Definitions. - * - * "License" shall mean the terms and conditions for use, reproduction, - * and distribution as defined by Sections 1 through 9 of this document. - * - * "Licensor" shall mean the copyright owner or entity authorized by - * the copyright owner that is granting the License. - * - * "Legal Entity" shall mean the union of the acting entity and all - * other entities that control, are controlled by, or are under common - * control with that entity. For the purposes of this definition, - * "control" means (i) the power, direct or indirect, to cause the - * direction or management of such entity, whether by contract or - * otherwise, or (ii) ownership of fifty percent (50%) or more of the - * outstanding shares, or (iii) beneficial ownership of such entity. - * - * "You" (or "Your") shall mean an individual or Legal Entity - * exercising permissions granted by this License. - * - * "Source" form shall mean the preferred form for making modifications, - * including but not limited to software source code, documentation - * source, and configuration files. - * - * "Object" form shall mean any form resulting from mechanical - * transformation or translation of a Source form, including but - * not limited to compiled object code, generated documentation, - * and conversions to other media types. - * - * "Work" shall mean the work of authorship, whether in Source or - * Object form, made available under the License, as indicated by a - * copyright notice that is included in or attached to the work - * (an example is provided in the Appendix below). - * - * "Derivative Works" shall mean any work, whether in Source or Object - * form, that is based on (or derived from) the Work and for which the - * editorial revisions, annotations, elaborations, or other modifications - * represent, as a whole, an original work of authorship. For the purposes - * of this License, Derivative Works shall not include works that remain - * separable from, or merely link (or bind by name) to the interfaces of, - * the Work and Derivative Works thereof. - * - * "Contribution" shall mean any work of authorship, including - * the original version of the Work and any modifications or additions - * to that Work or Derivative Works thereof, that is intentionally - * submitted to Licensor for inclusion in the Work by the copyright owner - * or by an individual or Legal Entity authorized to submit on behalf of - * the copyright owner. For the purposes of this definition, "submitted" - * means any form of electronic, verbal, or written communication sent - * to the Licensor or its representatives, including but not limited to - * communication on electronic mailing lists, source code control systems, - * and issue tracking systems that are managed by, or on behalf of, the - * Licensor for the purpose of discussing and improving the Work, but - * excluding communication that is conspicuously marked or otherwise - * designated in writing by the copyright owner as "Not a Contribution." - * - * "Contributor" shall mean Licensor and any individual or Legal Entity - * on behalf of whom a Contribution has been received by Licensor and - * subsequently incorporated within the Work. - * - * 2. Grant of Copyright License. Subject to the terms and conditions of - * this License, each Contributor hereby grants to You a perpetual, - * worldwide, non-exclusive, no-charge, royalty-free, irrevocable - * copyright license to reproduce, prepare Derivative Works of, - * publicly display, publicly perform, sublicense, and distribute the - * Work and such Derivative Works in Source or Object form. - * - * 3. Grant of Patent License. Subject to the terms and conditions of - * this License, each Contributor hereby grants to You a perpetual, - * worldwide, non-exclusive, no-charge, royalty-free, irrevocable - * (except as stated in this section) patent license to make, have made, - * use, offer to sell, sell, import, and otherwise transfer the Work, - * where such license applies only to those patent claims licensable - * by such Contributor that are necessarily infringed by their - * Contribution(s) alone or by combination of their Contribution(s) - * with the Work to which such Contribution(s) was submitted. If You - * institute patent litigation against any entity (including a - * cross-claim or counterclaim in a lawsuit) alleging that the Work - * or a Contribution incorporated within the Work constitutes direct - * or contributory patent infringement, then any patent licenses - * granted to You under this License for that Work shall terminate - * as of the date such litigation is filed. - * - * 4. Redistribution. You may reproduce and distribute copies of the - * Work or Derivative Works thereof in any medium, with or without - * modifications, and in Source or Object form, provided that You - * meet the following conditions: - * - * (a) You must give any other recipients of the Work or - * Derivative Works a copy of this License; and - * - * (b) You must cause any modified files to carry prominent notices - * stating that You changed the files; and - * - * (c) You must retain, in the Source form of any Derivative Works - * that You distribute, all copyright, patent, trademark, and - * attribution notices from the Source form of the Work, - * excluding those notices that do not pertain to any part of - * the Derivative Works; and - * - * (d) If the Work includes a "NOTICE" text file as part of its - * distribution, then any Derivative Works that You distribute must - * include a readable copy of the attribution notices contained - * within such NOTICE file, excluding those notices that do not - * pertain to any part of the Derivative Works, in at least one - * of the following places: within a NOTICE text file distributed - * as part of the Derivative Works; within the Source form or - * documentation, if provided along with the Derivative Works; or, - * within a display generated by the Derivative Works, if and - * wherever such third-party notices normally appear. The contents - * of the NOTICE file are for informational purposes only and - * do not modify the License. You may add Your own attribution - * notices within Derivative Works that You distribute, alongside - * or as an addendum to the NOTICE text from the Work, provided - * that such additional attribution notices cannot be construed - * as modifying the License. - * - * You may add Your own copyright statement to Your modifications and - * may provide additional or different license terms and conditions - * for use, reproduction, or distribution of Your modifications, or - * for any such Derivative Works as a whole, provided Your use, - * reproduction, and distribution of the Work otherwise complies with - * the conditions stated in this License. - * - * 5. Submission of Contributions. Unless You explicitly state otherwise, - * any Contribution intentionally submitted for inclusion in the Work - * by You to the Licensor shall be under the terms and conditions of - * this License, without any additional terms or conditions. - * Notwithstanding the above, nothing herein shall supersede or modify - * the terms of any separate license agreement you may have executed - * with Licensor regarding such Contributions. - * - * 6. Trademarks. This License does not grant permission to use the trade - * names, trademarks, service marks, or product names of the Licensor, - * except as required for reasonable and customary use in describing the - * origin of the Work and reproducing the content of the NOTICE file. - * - * 7. Disclaimer of Warranty. Unless required by applicable law or - * agreed to in writing, Licensor provides the Work (and each - * Contributor provides its Contributions) on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - * implied, including, without limitation, any warranties or conditions - * of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - * PARTICULAR PURPOSE. You are solely responsible for determining the - * appropriateness of using or redistributing the Work and assume any - * risks associated with Your exercise of permissions under this License. - * - * 8. Limitation of Liability. In no event and under no legal theory, - * whether in tort (including negligence), contract, or otherwise, - * unless required by applicable law (such as deliberate and grossly - * negligent acts) or agreed to in writing, shall any Contributor be - * liable to You for damages, including any direct, indirect, special, - * incidental, or consequential damages of any character arising as a - * result of this License or out of the use or inability to use the - * Work (including but not limited to damages for loss of goodwill, - * work stoppage, computer failure or malfunction, or any and all - * other commercial damages or losses), even if such Contributor - * has been advised of the possibility of such damages. - * - * 9. Accepting Warranty or Additional Liability. While redistributing - * the Work or Derivative Works thereof, You may choose to offer, - * and charge a fee for, acceptance of support, warranty, indemnity, - * or other liability obligations and/or rights consistent with this - * License. However, in accepting such obligations, You may act only - * on Your own behalf and on Your sole responsibility, not on behalf - * of any other Contributor, and only if You agree to indemnify, - * defend, and hold each Contributor harmless for any liability - * incurred by, or claims asserted against, such Contributor by reason - * of your accepting any such warranty or additional liability. - * - * END OF TERMS AND CONDITIONS - * - * APPENDIX: How to apply the Apache License to your work. - * - * To apply the Apache License to your work, attach the following - * boilerplate notice, with the fields enclosed by brackets "[]" - * replaced with your own identifying information. (Don't include - * the brackets!) The text should be enclosed in the appropriate - * comment syntax for the file format. We also recommend that a - * file or class name and description of purpose be included on the - * same "printed page" as the copyright notice for easier - * identification within third-party archives. - * - * Copyright [yyyy] [name of copyright owner] - * - * 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. - */ - diff --git a/docs/3rdPartyLicenses/asm-license.txt b/docs/3rdPartyLicenses/asm-license.txt deleted file mode 100644 index 75284b46..00000000 --- a/docs/3rdPartyLicenses/asm-license.txt +++ /dev/null @@ -1,30 +0,0 @@ -ASM: a very small and fast Java bytecode manipulation framework -Copyright (c) 2000-2011 INRIA, France Telecom -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: - -1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -3. Neither the name of the copyright holders nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE -LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF -THE POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/3rdPartyLicenses/guava-license.txt b/docs/3rdPartyLicenses/guava-license.txt deleted file mode 100644 index 6b0b1270..00000000 --- a/docs/3rdPartyLicenses/guava-license.txt +++ /dev/null @@ -1,203 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - 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. - diff --git a/docs/3rdPartyLicenses/retroguard-LGPL.txt b/docs/3rdPartyLicenses/retroguard-LGPL.txt deleted file mode 100644 index 6b0b7977..00000000 --- a/docs/3rdPartyLicenses/retroguard-LGPL.txt +++ /dev/null @@ -1,504 +0,0 @@ - GNU LESSER GENERAL PUBLIC LICENSE - Version 2.1, February 1999 - - Copyright (C) 1991, 1999 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - -[This is the first released version of the Lesser GPL. It also counts - as the successor of the GNU Library Public License, version 2, hence - the version number 2.1.] - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -Licenses are intended to guarantee your freedom to share and change -free software--to make sure the software is free for all its users. - - This license, the Lesser General Public License, applies to some -specially designated software packages--typically libraries--of the -Free Software Foundation and other authors who decide to use it. You -can use it too, but we suggest you first think carefully about whether -this license or the ordinary General Public License is the better -strategy to use in any particular case, based on the explanations below. - - When we speak of free software, we are referring to freedom of use, -not price. Our General Public Licenses are designed to make sure that -you have the freedom to distribute copies of free software (and charge -for this service if you wish); that you receive source code or can get -it if you want it; that you can change the software and use pieces of -it in new free programs; and that you are informed that you can do -these things. - - To protect your rights, we need to make restrictions that forbid -distributors to deny you these rights or to ask you to surrender these -rights. These restrictions translate to certain responsibilities for -you if you distribute copies of the library or if you modify it. - - For example, if you distribute copies of the library, whether gratis -or for a fee, you must give the recipients all the rights that we gave -you. You must make sure that they, too, receive or can get the source -code. If you link other code with the library, you must provide -complete object files to the recipients, so that they can relink them -with the library after making changes to the library and recompiling -it. And you must show them these terms so they know their rights. - - We protect your rights with a two-step method: (1) we copyright the -library, and (2) we offer you this license, which gives you legal -permission to copy, distribute and/or modify the library. - - To protect each distributor, we want to make it very clear that -there is no warranty for the free library. Also, if the library is -modified by someone else and passed on, the recipients should know -that what they have is not the original version, so that the original -author's reputation will not be affected by problems that might be -introduced by others. - - Finally, software patents pose a constant threat to the existence of -any free program. We wish to make sure that a company cannot -effectively restrict the users of a free program by obtaining a -restrictive license from a patent holder. Therefore, we insist that -any patent license obtained for a version of the library must be -consistent with the full freedom of use specified in this license. - - Most GNU software, including some libraries, is covered by the -ordinary GNU General Public License. This license, the GNU Lesser -General Public License, applies to certain designated libraries, and -is quite different from the ordinary General Public License. We use -this license for certain libraries in order to permit linking those -libraries into non-free programs. - - When a program is linked with a library, whether statically or using -a shared library, the combination of the two is legally speaking a -combined work, a derivative of the original library. The ordinary -General Public License therefore permits such linking only if the -entire combination fits its criteria of freedom. The Lesser General -Public License permits more lax criteria for linking other code with -the library. - - We call this license the "Lesser" General Public License because it -does Less to protect the user's freedom than the ordinary General -Public License. It also provides other free software developers Less -of an advantage over competing non-free programs. These disadvantages -are the reason we use the ordinary General Public License for many -libraries. However, the Lesser license provides advantages in certain -special circumstances. - - For example, on rare occasions, there may be a special need to -encourage the widest possible use of a certain library, so that it becomes -a de-facto standard. To achieve this, non-free programs must be -allowed to use the library. A more frequent case is that a free -library does the same job as widely used non-free libraries. In this -case, there is little to gain by limiting the free library to free -software only, so we use the Lesser General Public License. - - In other cases, permission to use a particular library in non-free -programs enables a greater number of people to use a large body of -free software. For example, permission to use the GNU C Library in -non-free programs enables many more people to use the whole GNU -operating system, as well as its variant, the GNU/Linux operating -system. - - Although the Lesser General Public License is Less protective of the -users' freedom, it does ensure that the user of a program that is -linked with the Library has the freedom and the wherewithal to run -that program using a modified version of the Library. - - The precise terms and conditions for copying, distribution and -modification follow. Pay close attention to the difference between a -"work based on the library" and a "work that uses the library". The -former contains code derived from the library, whereas the latter must -be combined with the library in order to run. - - GNU LESSER GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License Agreement applies to any software library or other -program which contains a notice placed by the copyright holder or -other authorized party saying it may be distributed under the terms of -this Lesser General Public License (also called "this License"). -Each licensee is addressed as "you". - - A "library" means a collection of software functions and/or data -prepared so as to be conveniently linked with application programs -(which use some of those functions and data) to form executables. - - The "Library", below, refers to any such software library or work -which has been distributed under these terms. A "work based on the -Library" means either the Library or any derivative work under -copyright law: that is to say, a work containing the Library or a -portion of it, either verbatim or with modifications and/or translated -straightforwardly into another language. (Hereinafter, translation is -included without limitation in the term "modification".) - - "Source code" for a work means the preferred form of the work for -making modifications to it. For a library, complete source code means -all the source code for all modules it contains, plus any associated -interface definition files, plus the scripts used to control compilation -and installation of the library. - - Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running a program using the Library is not restricted, and output from -such a program is covered only if its contents constitute a work based -on the Library (independent of the use of the Library in a tool for -writing it). Whether that is true depends on what the Library does -and what the program that uses the Library does. - - 1. You may copy and distribute verbatim copies of the Library's -complete source code as you receive it, in any medium, provided that -you conspicuously and appropriately publish on each copy an -appropriate copyright notice and disclaimer of warranty; keep intact -all the notices that refer to this License and to the absence of any -warranty; and distribute a copy of this License along with the -Library. - - You may charge a fee for the physical act of transferring a copy, -and you may at your option offer warranty protection in exchange for a -fee. - - 2. You may modify your copy or copies of the Library or any portion -of it, thus forming a work based on the Library, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) The modified work must itself be a software library. - - b) You must cause the files modified to carry prominent notices - stating that you changed the files and the date of any change. - - c) You must cause the whole of the work to be licensed at no - charge to all third parties under the terms of this License. - - d) If a facility in the modified Library refers to a function or a - table of data to be supplied by an application program that uses - the facility, other than as an argument passed when the facility - is invoked, then you must make a good faith effort to ensure that, - in the event an application does not supply such function or - table, the facility still operates, and performs whatever part of - its purpose remains meaningful. - - (For example, a function in a library to compute square roots has - a purpose that is entirely well-defined independent of the - application. Therefore, Subsection 2d requires that any - application-supplied function or table used by this function must - be optional: if the application does not supply it, the square - root function must still compute square roots.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Library, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Library, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote -it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Library. - -In addition, mere aggregation of another work not based on the Library -with the Library (or with a work based on the Library) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may opt to apply the terms of the ordinary GNU General Public -License instead of this License to a given copy of the Library. To do -this, you must alter all the notices that refer to this License, so -that they refer to the ordinary GNU General Public License, version 2, -instead of to this License. (If a newer version than version 2 of the -ordinary GNU General Public License has appeared, then you can specify -that version instead if you wish.) Do not make any other change in -these notices. - - Once this change is made in a given copy, it is irreversible for -that copy, so the ordinary GNU General Public License applies to all -subsequent copies and derivative works made from that copy. - - This option is useful when you wish to copy part of the code of -the Library into a program that is not a library. - - 4. You may copy and distribute the Library (or a portion or -derivative of it, under Section 2) in object code or executable form -under the terms of Sections 1 and 2 above provided that you accompany -it with the complete corresponding machine-readable source code, which -must be distributed under the terms of Sections 1 and 2 above on a -medium customarily used for software interchange. - - If distribution of object code is made by offering access to copy -from a designated place, then offering equivalent access to copy the -source code from the same place satisfies the requirement to -distribute the source code, even though third parties are not -compelled to copy the source along with the object code. - - 5. A program that contains no derivative of any portion of the -Library, but is designed to work with the Library by being compiled or -linked with it, is called a "work that uses the Library". Such a -work, in isolation, is not a derivative work of the Library, and -therefore falls outside the scope of this License. - - However, linking a "work that uses the Library" with the Library -creates an executable that is a derivative of the Library (because it -contains portions of the Library), rather than a "work that uses the -library". The executable is therefore covered by this License. -Section 6 states terms for distribution of such executables. - - When a "work that uses the Library" uses material from a header file -that is part of the Library, the object code for the work may be a -derivative work of the Library even though the source code is not. -Whether this is true is especially significant if the work can be -linked without the Library, or if the work is itself a library. The -threshold for this to be true is not precisely defined by law. - - If such an object file uses only numerical parameters, data -structure layouts and accessors, and small macros and small inline -functions (ten lines or less in length), then the use of the object -file is unrestricted, regardless of whether it is legally a derivative -work. (Executables containing this object code plus portions of the -Library will still fall under Section 6.) - - Otherwise, if the work is a derivative of the Library, you may -distribute the object code for the work under the terms of Section 6. -Any executables containing that work also fall under Section 6, -whether or not they are linked directly with the Library itself. - - 6. As an exception to the Sections above, you may also combine or -link a "work that uses the Library" with the Library to produce a -work containing portions of the Library, and distribute that work -under terms of your choice, provided that the terms permit -modification of the work for the customer's own use and reverse -engineering for debugging such modifications. - - You must give prominent notice with each copy of the work that the -Library is used in it and that the Library and its use are covered by -this License. You must supply a copy of this License. If the work -during execution displays copyright notices, you must include the -copyright notice for the Library among them, as well as a reference -directing the user to the copy of this License. Also, you must do one -of these things: - - a) Accompany the work with the complete corresponding - machine-readable source code for the Library including whatever - changes were used in the work (which must be distributed under - Sections 1 and 2 above); and, if the work is an executable linked - with the Library, with the complete machine-readable "work that - uses the Library", as object code and/or source code, so that the - user can modify the Library and then relink to produce a modified - executable containing the modified Library. (It is understood - that the user who changes the contents of definitions files in the - Library will not necessarily be able to recompile the application - to use the modified definitions.) - - b) Use a suitable shared library mechanism for linking with the - Library. A suitable mechanism is one that (1) uses at run time a - copy of the library already present on the user's computer system, - rather than copying library functions into the executable, and (2) - will operate properly with a modified version of the library, if - the user installs one, as long as the modified version is - interface-compatible with the version that the work was made with. - - c) Accompany the work with a written offer, valid for at - least three years, to give the same user the materials - specified in Subsection 6a, above, for a charge no more - than the cost of performing this distribution. - - d) If distribution of the work is made by offering access to copy - from a designated place, offer equivalent access to copy the above - specified materials from the same place. - - e) Verify that the user has already received a copy of these - materials or that you have already sent this user a copy. - - For an executable, the required form of the "work that uses the -Library" must include any data and utility programs needed for -reproducing the executable from it. However, as a special exception, -the materials to be distributed need not include anything that is -normally distributed (in either source or binary form) with the major -components (compiler, kernel, and so on) of the operating system on -which the executable runs, unless that component itself accompanies -the executable. - - It may happen that this requirement contradicts the license -restrictions of other proprietary libraries that do not normally -accompany the operating system. Such a contradiction means you cannot -use both them and the Library together in an executable that you -distribute. - - 7. You may place library facilities that are a work based on the -Library side-by-side in a single library together with other library -facilities not covered by this License, and distribute such a combined -library, provided that the separate distribution of the work based on -the Library and of the other library facilities is otherwise -permitted, and provided that you do these two things: - - a) Accompany the combined library with a copy of the same work - based on the Library, uncombined with any other library - facilities. This must be distributed under the terms of the - Sections above. - - b) Give prominent notice with the combined library of the fact - that part of it is a work based on the Library, and explaining - where to find the accompanying uncombined form of the same work. - - 8. You may not copy, modify, sublicense, link with, or distribute -the Library except as expressly provided under this License. Any -attempt otherwise to copy, modify, sublicense, link with, or -distribute the Library is void, and will automatically terminate your -rights under this License. However, parties who have received copies, -or rights, from you under this License will not have their licenses -terminated so long as such parties remain in full compliance. - - 9. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Library or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Library (or any work based on the -Library), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Library or works based on it. - - 10. Each time you redistribute the Library (or any work based on the -Library), the recipient automatically receives a license from the -original licensor to copy, distribute, link with or modify the Library -subject to these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties with -this License. - - 11. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Library at all. For example, if a patent -license would not permit royalty-free redistribution of the Library by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Library. - -If any portion of this section is held invalid or unenforceable under any -particular circumstance, the balance of the section is intended to apply, -and the section as a whole is intended to apply in other circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 12. If the distribution and/or use of the Library is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Library under this License may add -an explicit geographical distribution limitation excluding those countries, -so that distribution is permitted only in or among countries not thus -excluded. In such case, this License incorporates the limitation as if -written in the body of this License. - - 13. The Free Software Foundation may publish revised and/or new -versions of the Lesser General Public License from time to time. -Such new versions will be similar in spirit to the present version, -but may differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Library -specifies a version number of this License which applies to it and -"any later version", you have the option of following the terms and -conditions either of that version or of any later version published by -the Free Software Foundation. If the Library does not specify a -license version number, you may choose any version ever published by -the Free Software Foundation. - - 14. If you wish to incorporate parts of the Library into other free -programs whose distribution conditions are incompatible with these, -write to the author to ask for permission. For software which is -copyrighted by the Free Software Foundation, write to the Free -Software Foundation; we sometimes make exceptions for this. Our -decision will be guided by the two goals of preserving the free status -of all derivatives of our free software and of promoting the sharing -and reuse of software generally. - - NO WARRANTY - - 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO -WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. -EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR -OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY -KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE -LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME -THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - - 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN -WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY -AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU -FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR -CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE -LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING -RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A -FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF -SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH -DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Libraries - - If you develop a new library, and you want it to be of the greatest -possible use to the public, we recommend making it free software that -everyone can redistribute and change. You can do so by permitting -redistribution under these terms (or, alternatively, under the terms of the -ordinary General Public License). - - To apply these terms, attach the following notices to the library. It is -safest to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least the -"copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later version. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - -Also add information on how to contact you by electronic and paper mail. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the library, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the - library `Frob' (a library for tweaking knobs) written by James Random Hacker. - - , 1 April 1990 - Ty Coon, President of Vice - -That's all there is to it! - - diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 00000000..086a5c9e --- /dev/null +++ b/docs/404.html @@ -0,0 +1,25 @@ +--- +permalink: /404.html +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 00000000..727383f0 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,30 @@ +source "https://rubygems.org" +# Hello! This is where you manage which Jekyll version is used to run. +# When you want to use a different version, change it below, save the +# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: +# +# bundle exec jekyll serve +# +# This will help ensure the proper Jekyll version is running. +# Happy Jekylling! +# This is the default theme for new Jekyll sites. You may change this to anything you like. +#gem "minima", "-> 2.5.0" +# If you want to use GitHub Pages, remove the "gem "jekyll"" above and +# uncomment the line below. To upgrade, run `bundle update github-pages`. +gem "github-pages", group: :jekyll_plugins +gem 'jemoji' +# If you have any plugins, put them here! +#group :jekyll_plugins do +# gem "jekyll-feed", "~> 0.12" +#end + +# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem +# and associated library. +install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do + gem "tzinfo", "~> 1.2" + gem "tzinfo-data" +end + +# Performance-booster for watching directories on Windows +gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform? + diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 00000000..b7a7d129 --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,256 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (4.2.11.1) + i18n (~> 0.7) + minitest (~> 5.1) + thread_safe (~> 0.3, >= 0.3.4) + tzinfo (~> 1.1) + addressable (2.7.0) + public_suffix (>= 2.0.2, < 5.0) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.11.1) + colorator (1.1.0) + commonmarker (0.17.13) + ruby-enum (~> 0.5) + concurrent-ruby (1.1.5) + dnsruby (1.61.3) + addressable (~> 2.5) + em-websocket (0.5.1) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0.6.0) + ethon (0.12.0) + ffi (>= 1.3.0) + eventmachine (1.2.7) + execjs (2.7.0) + faraday (0.17.0) + multipart-post (>= 1.2, < 3) + ffi (1.11.1) + forwardable-extended (2.6.0) + gemoji (3.0.1) + github-pages (202) + activesupport (= 4.2.11.1) + github-pages-health-check (= 1.16.1) + jekyll (= 3.8.5) + jekyll-avatar (= 0.6.0) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.1.6) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.11.0) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.12.1) + jekyll-mentions (= 1.4.1) + jekyll-optional-front-matter (= 0.3.0) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.2.0) + jekyll-redirect-from (= 0.14.0) + jekyll-relative-links (= 0.6.0) + jekyll-remote-theme (= 0.4.0) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.5.0) + jekyll-sitemap (= 1.2.0) + jekyll-swiss (= 0.4.0) + jekyll-theme-architect (= 0.1.1) + jekyll-theme-cayman (= 0.1.1) + jekyll-theme-dinky (= 0.1.1) + jekyll-theme-hacker (= 0.1.1) + jekyll-theme-leap-day (= 0.1.1) + jekyll-theme-merlot (= 0.1.1) + jekyll-theme-midnight (= 0.1.1) + jekyll-theme-minimal (= 0.1.1) + jekyll-theme-modernist (= 0.1.1) + jekyll-theme-primer (= 0.5.3) + jekyll-theme-slate (= 0.1.1) + jekyll-theme-tactile (= 0.1.1) + jekyll-theme-time-machine (= 0.1.1) + jekyll-titles-from-headings (= 0.5.1) + jemoji (= 0.10.2) + kramdown (= 1.17.0) + liquid (= 4.0.0) + listen (= 3.1.5) + mercenary (~> 0.3) + minima (= 2.5.0) + nokogiri (>= 1.10.4, < 2.0) + rouge (= 3.11.0) + terminal-table (~> 1.4) + github-pages-health-check (1.16.1) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (~> 4.0) + public_suffix (~> 3.0) + typhoeus (~> 1.3) + html-pipeline (2.12.0) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.6.0) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.8.5) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (~> 1.14) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.6.0) + jekyll (~> 3.0) + jekyll-coffeescript (1.1.1) + coffee-script (~> 2.2) + coffee-script-source (~> 1.11.1) + jekyll-commonmark (1.3.1) + commonmarker (~> 0.14) + jekyll (>= 3.7, < 5.0) + jekyll-commonmark-ghpages (0.1.6) + commonmarker (~> 0.17.6) + jekyll-commonmark (~> 1.2) + rouge (>= 2.0, < 4.0) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.11.0) + jekyll (~> 3.3) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.12.1) + jekyll (~> 3.4) + octokit (~> 4.0, != 4.4.0) + jekyll-mentions (1.4.1) + html-pipeline (~> 2.3) + jekyll (~> 3.0) + jekyll-optional-front-matter (0.3.0) + jekyll (~> 3.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.2.0) + jekyll (~> 3.0) + jekyll-redirect-from (0.14.0) + jekyll (~> 3.3) + jekyll-relative-links (0.6.0) + jekyll (~> 3.3) + jekyll-remote-theme (0.4.0) + addressable (~> 2.0) + jekyll (~> 3.5) + rubyzip (>= 1.2.1, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.5.0) + jekyll (~> 3.3) + jekyll-sitemap (1.2.0) + jekyll (~> 3.3) + jekyll-swiss (0.4.0) + jekyll-theme-architect (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.5.3) + jekyll (~> 3.5) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.1) + jekyll (~> 3.3) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.10.2) + gemoji (~> 3.0) + html-pipeline (~> 2.2) + jekyll (~> 3.0) + kramdown (1.17.0) + liquid (4.0.0) + listen (3.1.5) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + ruby_dep (~> 1.2) + mercenary (0.3.6) + mini_portile2 (2.4.0) + minima (2.5.0) + jekyll (~> 3.5) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.12.2) + multipart-post (2.1.1) + nokogiri (1.10.4) + mini_portile2 (~> 2.4.0) + octokit (4.14.0) + sawyer (~> 0.8.0, >= 0.5.3) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (3.1.1) + rb-fsevent (0.10.3) + rb-inotify (0.10.0) + ffi (~> 1.0) + rouge (3.11.0) + ruby-enum (0.7.2) + i18n + ruby_dep (1.5.0) + rubyzip (2.0.0) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.8.2) + addressable (>= 2.3.5) + faraday (> 0.8, < 2.0) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + thread_safe (0.3.6) + typhoeus (1.3.1) + ethon (>= 0.9.0) + tzinfo (1.2.5) + thread_safe (~> 0.1) + tzinfo-data (1.2019.3) + tzinfo (>= 1.0.0) + unicode-display_width (1.6.0) + wdm (0.1.1) + +PLATFORMS + ruby + +DEPENDENCIES + github-pages + jemoji + tzinfo (~> 1.2) + tzinfo-data + wdm (~> 0.1.1) + +BUNDLED WITH + 2.0.2 diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..e6bcb1e7 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,57 @@ +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole blog, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'bundle exec jekyll serve'. If you change this file, please restart the server process. +# +# If you need help with YAML syntax, here are some quick references for you: +# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml +# https://learnxinyminutes.com/docs/yaml/ +# +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. + +title: yGuard +email: yguard@yworks.com +description: >- # this means to ignore newlines until "baseurl:" + The open-source Java obfuscation tool working with Ant, Maven and Gradle by yWorks - the diagramming experts +#baseurl: "" # the subpath of your site, e.g. /blog +#url: "" # the base hostname & protocol for your site, e.g. http://example.com +plugins: + - jemoji + +github_username: yWorks + +show_downloads: ["true"] +github: + zip_url: https://github.com/yWorks/yguard/releases/download/2.9.0/yguard-2.9.0.zip + +# Build settings +theme: jekyll-theme-cayman + +# Exclude from processing. +# The following items will not be processed, by default. +# Any item listed under the `exclude:` key here will be automatically added to +# the internal "default list". +# +# Excluded items can be processed by explicitly listing the directories or +# their entries' file path in the `include:` list. +# +# exclude: +# - .sass-cache/ +# - .jekyll-cache/ +# - gemfiles/ +# - Gemfile +# - Gemfile.lock +# - node_modules/ +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html new file mode 100644 index 00000000..887af914 --- /dev/null +++ b/docs/_layouts/default.html @@ -0,0 +1,49 @@ + + + + + {% if site.google_analytics %} + + + {% endif %} + + +{% seo %} + + + + + + + + + + +
+ {{ content }} + + +
+ + + diff --git a/docs/ant/antmanual.css b/docs/ant/antmanual.css deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/ant/yguard.html b/docs/ant/yguard.html deleted file mode 100644 index 66bd7bb8..00000000 --- a/docs/ant/yguard.html +++ /dev/null @@ -1,78 +0,0 @@ - - - TaskName - - - - - -

TaskName

- -

Description

- -

- -

- -

Attributes

- - - - - - - - - - - -
AttributeDescriptionRequired
namedescdefault.
-

- -

-

Child Elements

- -

- -

- - -

Nested Elements

- -

- -

nested name

- -

If fork is enabled, additional parameters may be passed to - the new VM via nested <jvmarg> elements. For example:

- -
-  example
-
- -

would..

- -

<jvmarg> allows.

- - -

Examples

- -
-  <junit>
-  <test name="my.test.TestCase"/>
-  </junit>
-
- -

Runs the test defined in my.test.TestCase in the same - VM. No output will be generated unless the test fails.

- - -
- -

Copyright © 2000-2005 The Apache Software Foundation. All rights - Reserved.

- - diff --git a/docs/compatibility.md b/docs/compatibility.md new file mode 100644 index 00000000..746dc7a7 --- /dev/null +++ b/docs/compatibility.md @@ -0,0 +1,27 @@ +--- +layout: default +title: Compatibility +permalink: /compatibility/ +--- + +## Technical requirements + +yGuard requires JDK 1.7.x or greater and Ant 1.5 or greater installed on your system. It may work with earlier versions of these pieces of software as well, however this has not been tested thoroughly. yGuard 1.3.x and upwards works together with Ant 1.6. + +## Java 11 Compatibility + +Beginning with version 2.7, yGuard supports obfuscation of Java class files that contain `nesthost` or `nestmembers` attributes which were introduced with the Java 11 `.class` file format. + +yGuard does **not** support obfuscating `dynamic` instructions which were introduced with the Java 11 `.class` file format. + +## Java 9 / Java 10 Compatibility + +Beginning with version 2.7, yGuard supports obfuscation of Java class files that contain module information which was introduced with the Java 9 `.class` file format. yGuard does not change module names, though. + +yGuard does **not** support obfuscating multi-release Java archives which were introduced with Java 9. + +## Java 7 / Java 8 Compatibility + +Beginning with version 2.5, yGuard supports obfuscation of Java class files that contain the `invokedynamic` instruction, which was introduced with the Java 7 `.class` file format. JDK 7 does not contain any means of issuing this instruction, with JDK 8 it is being issued when using lambda expressions or default methods. + +While yGuard does fully support obfuscating `invokedynamic` instructions and therefore default methods and lambda expressions, shrinking of Java class files that contain this instruction is not supported yet. diff --git a/docs/documentation.css b/docs/documentation.css deleted file mode 100644 index c562df02..00000000 --- a/docs/documentation.css +++ /dev/null @@ -1,686 +0,0 @@ -@import url('https://fonts.googleapis.com/css?family=News+Cycle'); -@import url('https://fonts.googleapis.com/css?family=Roboto:300,500'); -@keyframes pulse { - 0% { - transform: scale(1); - } - 90% { - transform: scale(1.02); - } - 95% { - transform: scale(1.1); - } - 100% { - transform: scale(1); - } -} -.pulse { - animation-duration: 3s; - animation-name: pulse; - animation-iteration-count: infinite; - animation-fill-mode: both; -} -template { - display: none; -} -html, -body { - margin: 0; -} -body { - font-family: "Roboto", "Source Sans Pro", "Helvetica Neue Light", "HelveticaNeue-Light", "Helvetica Neue", Calibri, Helvetica, Arial, sans-serif; - color: #404040; - font-size: 16px; - font-weight: 300; -} -h1, -h2, -h3, -h4, -h5, -dt { - color: #242265; - font-weight: bold; - font-weight: 500; - line-height: 1.2; -} -.sr-only { - position: absolute; - width: 1px; - height: 1px; - padding: 0; - margin: -1px; - overflow: hidden; - clip: rect(0, 0, 0, 0); - border: 0; -} -span.angle-right { - background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Cpath fill='none' stroke='%23242265' stroke-width='10' d='M20 20l30 30-30 30'/%3E%3C/svg%3E") no-repeat 100% 100%; - padding: 16px 16px 16px 16px; - margin-left: 8px; - margin-top: 10px; - height: 15px; -} -header .logo { - background: url("data:image/svg+xml,%3Csvg version='1.1' id='Layer_1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' viewBox='0 0 96.6 101.3' xml:space='preserve'%3E%3Cpath fill='%23242265' d='M4,40.8l0.1,19.4C4.2,70,9.5,79.1,18,84l16.8,9.6c8.5,4.9,19,4.8,27.5-0.1l16.7-9.8c8.5-5,13.7-14.1,13.6-23.9 l-0.1-19.4c0-9.8-5.3-18.9-13.9-23.8L61.9,7.1c-8.5-4.9-19-4.8-27.5,0.1l-16.7,9.8C9.2,21.9,4,31,4,40.8'/%3E%3Cpath fill='%2300d8ff' d='M49.8,53.8c-0.3-1.2-0.3-2.5-0.3-3.8c0-1,0.2-2.1,0.4-3.1c0.4-1.7,1.2-3.2,2.1-4.6c1.6-2.7,3.1-6.1,1-9 c-1.7-2.3-5-2.9-7.5-1.3c-2.9,2-2.8,5.8-1.3,8.6c0.8,1.5,1.7,2.8,2.3,4.4c0.7,1.7,0.9,3.4,0.9,5.2c0,0.1,0,0.3,0,0.4c-0.1,1.7-0.3,3.4-1,5c-0.7,1.5-1.6,2.9-2.4,4.3c-1.5,2.8-1.8,6.6,1.1,8.7c2.4,1.7,5.8,1.2,7.5-1.1c2.2-2.9,0.8-6.3-0.8-9C50.9,57,50.1,55.5,49.8,53.8z'/%3E%3C/svg%3E") no-repeat 100% 100%; -} -.footer-block.logo { - width: 160px; - height: 200px; - background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 385.54 566.93'%3E%3Cpath fill='%23eee' d='M383.07,160a119,119,0,0,0-60-102.79L250.37,15.67a119,119,0,0,0-119,.55L59,58.43A119,119,0,0,0,0,161.79l.39,83.72a119,119,0,0,0,60,102.82l72.7,41.52a119,119,0,0,0,119-.55l72.31-42.21a119,119,0,0,0,59-103.35Zm-92.15,12.66a35.66,35.66,0,0,1-13.46,2.52c-4.07,0-8.15,0-12.22,0a61.63,61.63,0,0,0-20,3.25,79.9,79.9,0,0,0-13,6.38c-4.1,2.31-8.17,4.69-12.14,7.21a48.71,48.71,0,0,0-16.89,17.22,50.05,50.05,0,0,0-6.46,20c-.56,6.11-.45,12.25-.42,18.39,0,6.5.46,12.94,2.39,19.21a72.92,72.92,0,0,0,6.1,13.69c3.26,5.86,7.16,11.37,9.2,17.89,2.11,6.76,2.14,13.41-.93,19.81-3.72,7.76-9.9,12.4-18.56,13.49a22.59,22.59,0,0,1-19.75-7c-5.56-5.73-7.6-12.88-6.57-20.85,1-7.53,4.77-13.84,8.59-20.16,3.94-6.52,7.52-13.24,9-20.84a72.49,72.49,0,0,0,1-8.05,148.27,148.27,0,0,0,.29-17.51c-.26-7.52-.72-15.07-3.87-22.13a49.73,49.73,0,0,0-9.65-14.89,71.91,71.91,0,0,0-15.47-11.61c-4.58-2.67-9.12-5.42-13.89-7.75a56.49,56.49,0,0,0-20.7-5.54c-3.71-.28-7.41-.1-10.63-.29-5.73,0-11,.29-16.14-1.07-10.13-2.68-16.93-8.81-19.47-19.16-2.89-11.8,4.72-24.35,16.42-27.55,8.71-2.38,16.27-.13,23.15,5.29,4.73,3.73,7.75,8.79,10.68,13.91,2.73,4.76,5.31,9.62,8.62,14A54.94,54.94,0,0,0,151,173.78c5.74,3.61,11.57,7.07,17.62,10.09,8.79,4.39,18,6.68,28,5.59,9.35-1,17.56-4.78,25.45-9.49,3.49-2.07,7-4,10.5-6.18A57,57,0,0,0,251.8,153.9c3-5.12,5.72-10.45,9.22-15.28,4.24-5.83,9.67-10,16.78-11.61,10.52-2.45,22.87,3,27.28,14.11C310.09,153.79,303.76,167.53,290.92,172.66Z'/%3E%3Cg id='yWorks'%3E%3Cpath fill='%23eee' d='M149.78,511.73c0-20.47,14.69-34.86,35.46-34.86s35.61,14.39,35.61,34.86-14.84,35-35.61,35-35.46-14.54-35.46-35m54.59,0c0-12.16-7.7-20.62-19.13-20.62s-19.15,8.46-19.15,20.62,7.87,20.63,19.15,20.63,19.13-8.46,19.13-20.63'/%3E%3Cpath fill='%23eee' d='M276,480l-4.15,13.66a24.8,24.8,0,0,0-8.61-1.49c-9.34,0-15.72,6.08-15.72,16.62v36.05H231.37V478.65h11l3.11,9.79c3.87-7.42,10.54-11.28,19.15-11.28A22.43,22.43,0,0,1,276,480'/%3E%3Cpath fill='%23eee' d='M70.25,478.65v.44L35.51,566.93H18.3v-.3l10.4-23.44L.36,479.09v-.44H17.87l18.55,46.73c1.63,4-1.34-4.9,0,0,1.33-4.9,2.67-8.9,4-12.91l12.91-33.82Z'/%3E%3Cpath fill='%23eee' d='M132.71,478.65,122.48,508c-.89,2.52-1.78,5.2-2.52,8.17a68.74,68.74,0,0,0-3.86-8.31l-12.91-26H99.78l-12.91,26c-1.34,2.67-2.52,5.19-3.71,8.16-.75-2.82-1.49-5.34-2.37-8l-7.67-22-8.84,22.35,13.84,37H83l18.54-36.95L120,545.43H125l24.77-66.33v-.44H132.71Z'/%3E%3Cpath fill='%23eee' d='M365.65,505.5c-7.13-2.52-12-5-12-9.35,0-4.16,4.31-5.63,9.36-5.63a33.31,33.31,0,0,1,14.69,3.86l5.63-10.83a41.46,41.46,0,0,0-21.66-5.94c-12.6,0-23.44,6.38-23.44,18.54,0,10.84,8.16,16.32,18.7,20.33,6.52,2.52,12.76,4.9,12.76,9.8,0,4.15-3.86,6.82-9.79,6.82a34,34,0,0,1-18.1-5.49l-1.07-.75v15.06a46.4,46.4,0,0,0,20.36,4.38c14.53,0,24.48-7.71,24.48-20,0-11-8.31-16.48-19.89-20.78'/%3E%3Cpolygon fill='%23eee' points='333.17 535.87 311.6 510.7 333.17 484.98 333.17 478.65 319.61 478.65 297.64 504.91 297.64 455.79 281.47 455.79 281.47 544.83 297.64 544.83 297.64 516.63 321.38 544.83 333.17 544.83 333.17 535.87'/%3E%3C/g%3E%3C/svg%3E") no-repeat 100% 100%; -} -a { - color: #2b75b9; - text-decoration: none; -} -a:hover { - text-decoration: underline; -} -strong, -b { - font-weight: bold; - font-weight: 500; -} -pre { - padding: 10px 20px; - background-color: #f7f7f7; - border-left: 5px solid #e1e1e1; - line-height: 1.5em; - overflow: auto; - font-style: normal; - font-family: monospace; -} -code { -} -.important { - padding: 10px 20px; - background-color: #fbeeed; - border-left: 5px solid #d9534f; - margin-bottom: 10px; - -webkit-transition: background-color 0.5s ease-out; - -moz-transition: background-color 0.5s ease-out; - -ms-transition: background-color 0.5s ease-out; - -o-transition: background-color 0.5s ease-out; - transition: background-color 0.5s ease-out; -} -.highlight-important { - background-color: #ffbebe; -} -.note { - padding: 10px 20px; - background-color: #f6fbfe; - border-left: 5px solid #6bb9f0; - font-style: italic; - margin-bottom: 10px; -} -header { - position: relative; - height: 80px; - line-height: 80px; - background-color: #00d8ff; - display: flex; - box-shadow: 0 3px 6px rgba(0, 0, 0, 0.16), 0 3px 6px rgba(0, 0, 0, 0.23); - padding-left: 180px; -} -header a { - color: #242265; -} -header .logo { - width: 60px; - height: 60px; - padding: 5px; - box-sizing: border-box; - margin-top: 10px; - margin-right: 10px; -} -header .title { - color: #242265; - display: flex; - font-size: 1.2em; - font-weight: 400; -} -header .title #header-angle { - height: 60px; - width: 30px; - margin-left: 5px; -} -body > .content { - line-height: 1.5em; - padding-top: 20px; - width: 800px; - padding-left: 250px; - padding-bottom: 20px; -} -@media screen and (max-width: 1500px) { - body > .content { - width: 600px; - padding-left: 200px; - } - header { - padding-left: 130px; - } -} -@media screen and (max-width: 900px) { - body > .content { - width: 600px; - padding-left: 150px; - } - header { - padding-left: 80px; - } -} -@media screen and (max-width: 900px) { - body > .content { - width: 400px; - padding-left: 80px; - } - header { - padding-left: 10px; - } -} -@media screen and (max-width: 600px) { - body > .content { - width: 250px; - padding-left: 20px; - } - header { - padding-left: 0px; - } -} -.main { - display: flex; -} -.main .content { - padding: 20px 20px; -} -@media screen and (max-width: 900px) { - .main .content { - padding: 20px 10px; - } -} -@media screen and (max-width: 900px) { - .main { - flex-direction: column; - } -} -.content li { - margin-top: .7em; -} -.content li > p { - margin-top: .25em; - margin-bottom: 0; -} -.content li:first-child { - margin-top: 0; -} -.content li > ul, -.content li > ol, -.content li li { - margin: .4em 0; -} -.content dt { - font-weight: bold; - margin-top: 1em; - margin-bottom: 0.5em; -} -.content dt:first-child { - margin-top: 0; -} -.content dd > p { - margin: 0.5em 0; -} -.content h2 { - margin-top: 1.3em; - margin-bottom: .7em; -} -.content h3 { - margin-top: 1.1em; - margin-bottom: .4em; -} -.content h4 { - margin-bottom: .4em; -} -.content h1:first-child { - margin-top: 0; -} -.content td p.tableblock { - margin: 0; -} -.sidebar { - position: relative; - flex: 0 0 300px; - background-color: #eee; - padding: 20px; -} -@media screen and (max-width: 900px) { - .sidebar { - flex: 0 0 auto; - box-shadow: 0 3px 6px rgba(0, 0, 0, 0.16), 0 3px 6px rgba(0, 0, 0, 0.23); - } -} -.sidebar .search-container { - text-align: right; - width: 300px; -} -.sidebar .search-container #search { - outline: none; - border-top: none; - border-left: none; - border-right: none; - border-bottom: 1px solid lightgray; - width: 270px; - margin-bottom: 2em; - background: none; - padding: 5px 30px 5px 5px; -} -@media screen and (max-width: 900px) { - .sidebar .search-container #search { - position: absolute; - top: 0; - bottom: 0; - left: 0; - right: 0; - margin: 0; - font-size: 24px; - padding-left: 20px; - } -} -.sidebar .search-container svg { - vertical-align: top; -} -.sidebar .accordion-pane { - transition: background-color 0.5s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -@media screen and (max-width: 900px) { - .sidebar .accordion-pane { - display: none; - } -} -.sidebar .accordion-pane .accordion-title { - padding: 5px; - margin: 0; - font-weight: 500; - font-size: 1em; - cursor: pointer; - position: relative; - transition: background-color 0.5s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -.sidebar .accordion-pane a { - font-weight: 500; -} -.sidebar .accordion-pane .accordion-icon { - background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Cpath fill='none' stroke='%23666' stroke-width='10' d='M20 35l30 30 30-30'/%3E%3C/svg%3E") no-repeat 50% 50%; - background-size: 24px 24px; - width: 16px; - height: 100%; - display: inline-block; - position: absolute; - right: 10px; - top: 0; - transition: transform 0.5s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -.sidebar .accordion-pane .accordion-content { - padding: 20px; - display: none; -} -.sidebar .accordion-pane.expanded { - background-color: #e6e6e6; - margin-top: 5px; -} -.sidebar .accordion-pane.expanded .accordion-title { - background-color: #cccccc; -} -.sidebar .accordion-pane.expanded .accordion-content { - display: block; -} -.sidebar .accordion-pane.expanded .accordion-icon { - transform: rotateZ(180deg); -} -.demo-items > div { - font-size: 14px; - line-height: 2em; -} -.demo-items > div:not(:last-of-type) { - margin-bottom: 5px; -} -.demo-items > div.filtered { - opacity: 0.5; -} -@media screen and (max-width: 900px) { - footer { - text-align: inherit; - } -} -.demo-grid { - display: block; - margin-top: 2em; -} -.demo-grid .grid-item { - background-color: #eee; - position: relative; - display: inline-block; - vertical-align: text-top; - width: 240px; - height: 300px; - margin: 16px 16px; - box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 1px 2px rgba(0, 0, 0, 0.24); - overflow: hidden; - transition: box-shadow 0.3s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -.demo-grid .grid-item:focus { - box-shadow: 0 10px 20px rgba(0, 0, 0, 0.19), 0 6px 6px rgba(0, 0, 0, 0.23); -} -.demo-grid .grid-item:hover, -.demo-grid .grid-item:focus { - box-shadow: 0 10px 20px rgba(0, 0, 0, 0.19), 0 6px 6px rgba(0, 0, 0, 0.23); -} -.demo-grid .grid-item:hover .description, -.demo-grid .grid-item:focus .description { - height: 200px; -} -.demo-grid .grid-item:hover .description .details, -.demo-grid .grid-item:focus .description .details { - opacity: 1; -} -.demo-grid .grid-item:hover .thumbnail, -.demo-grid .grid-item:focus .thumbnail { - height: 100px; -} -.demo-grid .grid-item:hover .thumbnail img, -.demo-grid .grid-item:focus .thumbnail img { - transform: translate(-50%, -50%) scale(0.8); - opacity: 0.6; -} -.demo-grid .grid-item:hover .thumbnail .actions, -.demo-grid .grid-item:focus .thumbnail .actions { - opacity: 0.7; -} -.demo-grid .grid-item:hover .thumbnail .actions:hover, -.demo-grid .grid-item:focus .thumbnail .actions:hover { - opacity: 1; -} -.demo-grid .grid-item.filtered { - display: none; -} -.demo-grid .grid-item .thumbnail { - position: relative; - overflow: hidden; - height: 200px; - transition: height 0.5s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -.demo-grid .grid-item .thumbnail .category { - position: absolute; - bottom: 0; - left: 0; - z-index: 1; - padding: 6px 10px; - background-color: #336699; - color: #f0f0f0; - text-transform: uppercase; - font-weight: 500; - font-size: 11px; -} -.demo-grid .grid-item .thumbnail img { - height: 200px; - position: absolute; - top: 50%; - left: 50%; - transform: translate(-50%, -50%); - transition: transform 0.5s cubic-bezier(0.23, 1, 0.32, 1) 0s, opacity 0.5s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -.demo-grid .grid-item .thumbnail .actions { - position: absolute; - top: 20px; - left: 0; - right: 0; - opacity: 0; - text-align: center; - box-sizing: border-box; - padding: 10px; - transition: opacity 0.5s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -.demo-grid .grid-item .thumbnail .actions a { - font-size: 14px; - color: #333; - line-height: 22px; - height: 20px; - display: inline-block; -} -.demo-grid .grid-item .thumbnail .actions a.action-run { - background: url("data:image/svg+xml,%3Csvg fill='%23333' height='24' viewBox='0 0 24 24' width='24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M0 0h24v24H0z' fill='none'/%3E%3Cpath d='M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 14.5v-9l6 4.5-6 4.5z'/%3E%3C/svg%3E") no-repeat; - background-size: 60px 60px; - padding: 30px; - animation-duration: 3s; - animation-name: pulse; - animation-iteration-count: infinite; - animation-fill-mode: both; -} -.demo-grid .grid-item .thumbnail .actions a.action-source { - background: url("data:image/svg+xml,%3Csvg fill='%23333' height='24' viewBox='0 0 24 24' width='24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M0 0h24v24H0z' fill='none'/%3E%3Cpath d='M12 4.5C7 4.5 2.73 7.61 1 12c1.73 4.39 6 7.5 11 7.5s9.27-3.11 11-7.5c-1.73-4.39-6-7.5-11-7.5zM12 17c-2.76 0-5-2.24-5-5s2.24-5 5-5 5 2.24 5 5-2.24 5-5 5zm0-8c-1.66 0-3 1.34-3 3s1.34 3 3 3 3-1.34 3-3-1.34-3-3-3z'/%3E%3C/svg%3E") no-repeat; - background-size: 20px 20px; - padding-left: 20px; -} -.demo-grid .grid-item .description { - position: relative; - padding: 10px; - height: 100px; - box-sizing: border-box; - overflow: hidden; - transition: height 0.5s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -.demo-grid .grid-item .description .title { - position: relative; - margin: 0; - font-size: 1.1em; - z-index: 1; - font-weight: 500; -} -.demo-grid .grid-item .description .details { - margin: 0.5em 0 0 0; - font-size: 14px; - opacity: 0; - transition: opacity 0.5s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -.demo-grid .grid-item .tags { - position: absolute; - bottom: 0; - left: 0; - right: 0; - padding: 10px 10px 5px 10px; - transition: opacity 0.3s cubic-bezier(0.23, 1, 0.32, 1) 0s; -} -.demo-grid .grid-item .tags .tag { - display: inline-block; - font-size: 11px; - background-color: #a7d2ff; - padding: 0 6px; - height: 24px; - line-height: 24px; - box-sizing: border-box; - border-radius: 6px; - margin-bottom: 5px; - margin-right: 5px; -} -.demoTable { - font-weight: 300; -} -p.demoCategoryLocation { - margin-bottom: 20px; -} -footer { - font-family: "News Cycle", "Source Sans Pro", "Helvetica Neue Light", "HelveticaNeue-Light", "Helvetica Neue", Calibri, Helvetica, Arial, sans-serif; - background-color: #454545; - text-align: center; - color: #d2d2d2; - display: block; - font-size: 14px; - padding: 20px; -} -footer a { - color: #fff; -} -footer a:hover { - color: #7DA3C9; - -webkit-transition: 0.3s ease-in-out; - -moz-transition: 0.3s ease-in-out; - -o-transition: 0.3s ease-in-out; - transition: 0.3s ease-in-out; -} -@media screen and (max-width: 900px) { - footer { - text-align: inherit; - } -} -footer h4 { - color: #79a4d0; - text-transform: uppercase; -} -footer .logo { - height: 100%; - max-height: 200px; - max-width: 200px; - padding: 10px; - box-sizing: border-box; -} -@media screen and (max-width: 900px) { - footer .logo { - visibility: collapse; - } -} -footer .footer-block { - vertical-align: top; - text-align: left; - padding: 5px 20px; - display: inline-block; -} -@media screen and (max-width: 900px) { - footer .footer-block { - text-align: inherit; - } -} -footer .social a { - margin-right: 5px; -} -footer .copyright { - margin-top: 5em; - display: inline-block; -} -@media screen and (max-width: 900px) { - footer .copyright { - margin-top: 1em; - } -} - -.contents li { - margin: 4px; -} -.contents ul { - margin: 4px; -} -.contents code { - background-color: transparent; - border: none; - padding: 0; -} - -.listing { - background-color: #f7f7f7; - padding: 1px 4px; - font-weight: 300; - width: 100%; -} -.listing tr:first-child td { - border-top: none; -} -.listing th { - border-left: 1px solid #e1e1e1; - border-bottom: 2px solid #e1e1e1; -} -.listing th:first-child { - border-left: none; - border-bottom: 2px solid #e1e1e1; -} -.listing td { - border-top: 1px solid #e1e1e1; - border-left: 1px solid #e1e1e1; - vertical-align: top; -} -.listing td:first-child { - border-left: none; - vertical-align: top; -} -.listing td:nth-of-type(3) { - border-left: 1px solid #e1e1e1; - text-align: center; - vertical-align: top; -} -.listing td:nth-of-type(4) { - border-left: 1px solid #e1e1e1; - text-align: center; - vertical-align: top; -} - -.obfuscation .listing td:last-child { - text-align: center; -} - -.matrix tr:first-child td { - border-bottom: 1px solid #e1e1e1; -} -.matrix td:first-child { - border-right: 1px solid #e1e1e1; - text-align: right; -} - -.attributes li { - margin: 4px; -} -.attributes ul { - margin: 4px; -} - -.obfuscation code { - background-color: transparent; - border: none; - font-family: monospace; -} - -.properties li { - margin: 4px; -} -.properties ul { - margin: 4px; -} - -.attribute { - font-family: monospace; -} - -.element { - font-family: monospace; -} - -.keyword { - font-family: monospace; -} - -.property { - font-family: monospace; -} - -.child-elements li { - margin: 2px; -} -.child-elements ul { - margin: 2px; -} - -.programlisting { - font-size: smaller; -} - -p.title { - font-weight: 400; - margin-top: 24px; - margin-bottom: 8px; -} diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 156a4375..00000000 --- a/docs/index.html +++ /dev/null @@ -1,820 +0,0 @@ - - - yGuard @VERSION@ Release Notes - - - -
- -
yGuard
-
-
- -

yGuard @VERSION@ Release Notes

- -

Contents of the yGuard distribution

-
- - - - - - - - - - - - - - - - - -
README.htmlthis file
documentation - -
lib/ant task library: -
    -
  • yguard.jar
    • -
  • ObfuscationAnnotation.jar
    • -
-
3rdPartyLicenses/3rd Party Licenses: - -
-
-

Please read the documentation for - installation - instructions.

- - -

Technical requirements

-

yGuard requires JDK 1.7.x or greater and Ant 1.5 or greater installed on - your system. - It may work with earlier versions of these pieces of software as well, - however this has not - been tested thoroughly. yGuard 1.3.x and upwards works together with Ant - 1.6.

-

- - -

Java 11 Compatibility

-

- Beginning with version 2.7, yGuard supports obfuscation of Java class files - that contain nesthost or nestmembers attributes - which were introduced with the Java 11 .class file format. -

-

- yGuard does not support obfuscating dynamic - instructions which were introduced with the Java 11 .class file - format. -

- - - -

Java 9 / Java 10 Compatibility

-

- Beginning with version 2.7, yGuard supports obfuscation of Java class files - that contain module information which was introduced with the Java 9 - .class file format. yGuard does not change module names, - though. -

-

- yGuard does not support obfuscating multi-release Java archives which - were introduced with Java 9. -

- - - -

Java 7 / Java 8 Compatibility

- -

- Beginning with version 2.5, yGuard supports obfuscation of Java class files - that contain the invokedynamic instruction, which was - introduced with the Java 7 .class file format. - JDK 7 does not contain any means of issuing this instruction, with JDK 8 it - is being issued when using lambda expressions or default methods. -

-

- While yGuard does fully support obfuscating invokedynamic - instructions and therefore default methods and lambda expressions, - shrinking of Java class files that contain this instruction is not supported - yet. -

- -

Changelog

- -

yGuard 2.9.0 - Changes since 2.8.0

-
    -
  • Replaced ant based build with Gradle
    • -
  • -
- -

yGuard 2.8.0 - Changes since 2.7.2

-
    -
  • Replaced y.base.Edge, y.base.Node and y.base.Graph with a custom wrapper around Guava
    • -
  • Removed parts licensed under LGPL into a dedicated library, which is linked statically.
    • -
  • Relicensed the project under MIT.
    • -
  • Old code that was unused has been cleaned up.
    • -
- -

yGuard 2.7.2 - Changes since 2.7.1

-

Bug fixes

-
    -
  • - Fixed UnsupportedOperationException that occurred for Java 11 - class files when excluding classes from obfuscation using the - extends or implements attributes of the - rename.keep.class element in the yGuard ANT task. -
    • -
  • - Fixed yGuard's language-conformity mode illegal - to no longer produce unqualified names that contain dots or spaces. -
    • -
- -

yGuard 2.7.1 - Changes since 2.7

-

Improvements

-
    -
  • - Added support for the MethodParameters attribute, which was - introduced with the Java 8 .class file format. -
    • -
- -

Bug fixes

-
    -
  • - Fixed ClassCastException that occurred when obfuscating Java - 11 - class files with String concatentation. -
    • -
  • - Fixed IllegalArgumentException that occurred when excluding - classes from obfuscation using the extends or - implements attributes of the rename.keep.class - element in the yGuard ANT task. -
    • -
- -

yGuard 2.7 - Changes since 2.6

-

New Features

-
    -
  • - Added basic Java 11 class file support (see the - note on Java 11 compatibility). -
    • -
  • - Added Java 9 and Java 10 class file support (see the - note on Java 9 compatibility). -
    • -
  • - Improved yGuard's obfuscation log translation tool. -
      -
    • Added support for stacktraces with module prefixes.
      • -
    • Added support for stacktraces with obfuscation prefixes.
      • -
    • Improved translation of overloaded methods.
      • -
    -
    • -
- -

Bug fixes

-
    -
  • - Fixed NullPointerException that occurred when parsing class - files with retained Java 8 type annotations that use annotation - parameters. -
    • -
- -

yGuard 2.6 - Changes since 2.5.5

-
    -
  • - Fixed incorrect obfuscation of invokedynamic instructions - leading to AbstractMethodErrors of class files which had their constant - pool entry order permutated for some reason (for example by the JarJar - plugin for maven). -
    • -
  • - Added support for - Java 8 Type Annotations. -
    • -
  • - The implements attribute now considers types in - <externalclasses> as well when determining the - interfaces implemented by a given class. -
    • -
  • - Changed the class file version of the yGuard library, so yGuard can be - run with Java 7 again. -
    • -
- -

yGuard 2.5.5 - Changes since 2.5.4

-
    -
  • - Fixed IllegalArgumentException: "Invalid fully qualified name - (b)" that occurred when referencing or attempting to obfuscate - classes that start with a dollar ('$') sign. -
    • -
- -

yGuard 2.5.4 - Changes since 2.5.3

-
    -
  • - Fixed IllegalArgumentException caused by Java 8 compatibility - problems that arose in certain situations, for example when using - hierarchy based keep instructions. -
    • -
- -

yGuard 2.5.3 - Changes since 2.5.2

-
    -
  • - Fixed incorrect obfuscation of invokedynamic instructions - leading to AbstractMethodError when using default methods. -
    • -
- -

yGuard 2.5.2 - Changes since 2.5.1

-
    -
  • - Added support for renaming META-INF/services entries if the - entry corresponds to a type that is obfuscated. -
    • -
  • - Fixed a bug that caused the stacktrace deobfuscation tool to ignore class - name mappings that started with one or more $ characters. -
    • -
- -

yGuard 2.5.1 - Changes since 2.5

-
    -
  • - Fixed broken binary class file of the attached - com.yworks.util.annotation.Obfuscation annotation in - ObfuscationAnnotation.jar. -
    • -
- -

yGuard 2.5 - Changes since 2.4.0.1

-
    -
  • - Added support for controlling obfuscation exclusion via annotations. -
    • -
  • - Improved Java 7 support. yGuard does now support - invokedynamicin the obfuscation process. -
    • -
- -

yGuard 2.4.0.1 - Changes since 2.4

-
    -
  • - Fixed a regexp that could cause yGuard to parse manifest files for a - very long time. -
    • -
- - -

yGuard 2.4 - Changes since 2.3.0.1

-
    -
  • - Added basic Java 7 class file support (see the note - on Java 7 compatibility). -
    • -
  • - Fixed a bug that caused yGuard to introduce invalid signatures for typed - classes with inner classes. -
    • -
  • - Fixed a bug that caused yGuard to erroneously exclude all classes from - obfuscation when an implements attribute was used for a - <class> element without an additional name - or expose attribute. -
    • -
  • - Fixed a bug that caused the shrinker to ignore the - <attribute> element if the default shrinking settings - were used (i.e. if no <keep> element was defined). -
    • -
- -

yGuard 2.3.0.1 - Changes since 2.3.0

-
    -
  • - Fixed a bug that caused the shrinker to remove the static initializer of - a non-static inner class, when only fields of the inner class were - referenced (e.g. compiler-generated switch map tables for enums). -
    • -
- -

yGuard 2.3.0 - Changes since 2.2.0

-
    -
  • - yGuard won't try to initialize external classes needed for resolving - anymore. -
    • -
  • - The default behavior of the shrinker was changed to keep any referenced - runtime visible annotation and parameter annotation attributes. -
    • -
  • - The shrinker will now correctly adhere to the "lineNumberTable", - "runtimeVisibleParameterAnnotations" etc. attributes of the - <keep> element. -
    • -
  • - Fixed a bug that caused the shrinker to remove the enclosing method of - anonymous inner classes declared as entry points. -
    • -
  • Fixed a bug that caused the shrinker to remove referenced Annotation - elements from Annotation interfaces. -
    • -
  • yGuard now won't rename or remove the package-info class.
    • -
  • - Fixed possible "Illegal group reference" Exception in yGuard's parse - tool. -
    • -
  • - The shrinker will now keep classes that are used as field types of - referenced fields. -
    • -
  • - The shrinker will now correctly keep method attributes of methods that - are kept as stubs. -
    • -
- -

yGuard 2.2.0 - Changes since 2.1.0

-
    -
  • yGuard is now fully JDK-1.6 compatible.
    • -
  • - The yGuard task now supports a way of specifying a set of jars that - should be obfuscated at the same time using simple patternset syntax. -
    • -
  • - yGuard now uses the same technique for all elements in the MANIFEST file - to adjust fully qualified class name strings. -
    • -
  • - It is now possible to tell yGuard not to obfuscate specific package - names. -
    • -
  • - yGuard can now be given a list of digest algorithms that will be used to - create the digests in the manifest. -
    • -
  • - yGuard now issues a warning if the package or class or method name of a - native method is obfuscated. -
    • -
- -

yGuard 2.1.0 - Changes since 2.0.3

-
    -
  • - Fixed a bug that caused yGuard to throw a NullPointerException if a - attribute element contained no nested - patternset. -
    • -
  • - Fixed a bug that caused yGuard to use multiple logging instances if a - yGuard task was executed multiple times. -
    • -
  • Fixed LineNumberTable and SourceFile elements
    • -
  • Added overloadEnabled property
    • -
- -

yGuard 2.0.3 - Changes since 2.0.2

-
    -
  • - Fixed a bug that broke the nested map element of the - rename element. -
    • -
- -

yGuard 2.0.2 - Changes since 2.0.1

-
    -
  • - Fixed a bug that caused yGuard to fail during class file parsing if a - method signature contained an inner class of a parameterized class. -
    • -
  • - yGuard will not complain about the Java 1.5 attributes - Bridge, Enum and Varargs as - "unknown attributes" anymore. -
    • -
  • - Fixed a bug that caused all classnames to be kept from renaming if the - extends attribute was used in combination with the - classes attribute. -
    • -
- -

yGuard 2.0.1 - Changes since 2.0

-
    -
  • - Fixed an inconsistency between the interpretation of the Ant syntax in - the rename and shrink elements. Now, both - elements apply patternset elements in nested - method and field elements to class names, just - as stated in the yGuard documentation. -
    • -
  • - If the classes attribute of the class element - is not set or set to "none", the shrinking engine will now - include the classes that match based on the given name - attribute or nested patternset, effectively ignoring the - classes attribute. -
    • -
- -

yGuard 2.0 - Changes since 1.5.0_03

-
    -
  • New elaborate code shrinking functionality.
    • -
  • - More powerful ant syntax: extends/implements - attributes for the class element. -
    • -
  • - General Ant syntax changes due to the introduction of the new - yguard, shrink and rename elements. -
    • -
  • yGuard now needs Java2 SDK 1.4.x or greater to function properly.
    • -
- -

yGuard 1.5.0_03 - Changes since 1.5.0_02

-
    -
  • - Fixed bad treatment of the new enclosing method feature in Tiger which - sometimes led to AbstractMethodErrors at runtime. -
    • -
- -

yGuard 1.5.0_02 - Changes since 1.5.0_01

-
    -
  • - Improved obfuscation logic for enumerations. Now the two static methods - valueOf(String) and values() don't have to be exposed manually anymore. -
    • -
  • - Fixed bad annotation handling for non-trivial annotations. Annotations had - not been parsed and handled correctly, which could lead to either - errors during obfuscation or Errors at runtime. -
    • -
- -

yGuard 1.5.0_01 - Changes since 1.5

-
    -
  • - Fixed a bug that made yGuard ignore some of the attributes in the expose - section ("sourcefile" and "linenumbertable"). -
    • -
  • - Fixed a rare but severe bug that accidentally removed method attributes - and sometimes led to ArrayIndexOutOfBoundsExceptions during the - obfuscation. -
    • -
- -

yGuard 1.5 - Changes since 1.3.2

-
    -
  • - Added JDK 1.5 (a.k.a Java 5.0 code-named Tiger) compatibility. - yGuard can now deal correctly with the new JDK and Java features: - generics, var-args, enumerations, annotations, new ".class" - bytecode construct, signatures, local variable type table, enclosing - method information. -
    • -
  • - Implemented the ability to obfuscate/scramble/shrink line number - information. This makes it possible to more easily debug stacktraces - without exposing line number information in the obfuscated version of the - application. -
    • -
  • - Implemented the ability to obfuscate the source file information. This is - necessary in order to view line number information in stack traces. It is - now possible to reassign the source file attribute inside class files so - that the original source file name is not exposed in the obfuscated - application. -
    • -
  • - Added the ability to determine on a per-class basis what attributes to - expose or obfuscate. This includes line number information (with optional - scrambling/compression or removal), source file attributes, deprecation - attributes, etc. - This makes it easy to obfuscate parts of your application while keeping - the public API untouched and debug information for third party jars - intact. -
    • -
  • - Improved the stacktrace deobfuscation tool. It can now unscramble line - number information from stacktraces, features a more polished view of the - mapping rules and deobfuscates stacktraces more reliably if the - stacktraces are ambiguous. -
    • -
- -

yGuard 1.3.2 - Changes since 1.3.1_01

-
    -
  • - Improved name generation. yGuard will now generate legal identifiers - (with respect to Character.isJavaIdentifierStart() - and Character.isJavaIdentifierPart(char) and - Character.isIdentifierIgnorable(char)) and should - therefor produce jars that should verify correctly even on older jdks - if yGuard is run using newer jdks. -
    • -
  • - yGuard now helps in the detection of duplicate class files in source jars. - In pedantic mode yGuard will terminate if duplicate classes are detected - in different source jars. yGuard's obfuscate task will always fail if - mutliple class files containing a definition for the same jar are - detected. The log file displays useful information for finding the - duplicate entries. -
    • -
  • Improved xml log file output for Unicode characters.
    • -
  • - Made the log file viewer output more consistent with inner class names - that were being mapped during obfuscation versus those who remained fixed. -
    • -
  • - Jar file entries are now being sorted prior to being written to the jar. -
    • -
  • Improved handling of external classes.
    • -
  • - Bugfixes: -
      -
    • - Fixed a name clash problem that occurred when already obfuscated code - was being obfuscated again using different settings. -
      • -
    • - Fixed a resolution problem concerning interfaces from external - classpaths. -
      • -
    -
    • -
- -

yGuard 1.3.1_01 - Changes since 1.3.1

-
    -
  • - yGuard now treats the COMPATIBLE flag for the language conformity - different. - Field names and class names are now made up of lower ascii-only chars. -
    • -
  • - Bugfixes: -
      -
    • - Fixed a problem concerning the adjust elements throwing - a RuntimeException in the pattern matching code. -
      • -
    • - Fixed a problem where the wrong set of files was affected in the - adjust section. -
      • -
    -
    • -
- -

yGuard 1.3.1 - Changes since 1.3

-
    -
  • yGuard will now generate (empty) directory entries in the resulting jar - files for each non-empty directory. -
    • -
  • - Improved the optional keeping of "Deprecated" tags. Somehow they still - seem to get lost under certain conditions. - Any feedback on this topic is welcomed. -
    • -
  • - Due to a compile time dependency, yGuard could not be used with jdk 1.3.x - anymore even if the automatic resource adjustment feature was not used. - This has now been made possible again. -
    • -
  • - Bugfixes: -
      -
    • - Fixed a rare problem that broke obfuscated code using static method - invocations and static field references. -
      • -
    • - There was a bug in the log file viewer (java -jar yguard.jar - [logfile.xml[.gz]]) that made it crash under very rare - circumstances. -
      • -
    • - Implemented a workaround for an Ant incompatibility problem, which - resulted in yGuard behaving differently on different platforms and in - conjunction with different Ant versions. -
      • -
    -
    • -
- -

yGuard 1.3 - Changes since 1.2

-
    -
  • - Added automatic text file and property file renaming mechanism. yGuard can - now be configured to rename .properties files according to the - obfuscation. -
    • -
  • - It is now possible to process text files and replace occurances - of class names with their obfuscated versions. -
    • -
  • - One can now specify whether resource files should be kept in their - original directory while at the same time the classes residing in the - respective directory can be fully obfuscated to another package. -
    • -
  • - yGuard can now automatically create gzipped (.gz) logfiles and work - directly on compressed logfiles. This reduces the size of the logfiles - drastically. -
    • -
  • - It is now possible to simply specify a list of attributes, that should not - be removed by yGuard (for example "Deprecated") using the - expose-attributes property. -
    • -
  • - yGuard has a new name generation method (language-conformity - = compatible), that creates jar file that can be - successfully unzipped to the windows filesystem. -
    • -
  • - In order to avoid namespace clashes, on can now easily specify a prefix - for completeley obfuscated package hierarchies using the - obfuscation-prefix property. -
    • -
  • - Enhanced documentation (DTD, examples, and new features description). -
    • -
  • - Bugfixes: -
      -
    • - Innerclasses making use of the .class construct should now always be - correctly obfuscated using the replaceClassNameStrings feature. -
      • -
    • - The patch element had a bug concerning field name - mappings, which is now resolved. -
      • -
    • - yGuard now tests whether a newly obfuscated name already exists in - external jars and automatically generates names, that should not - clash. -
      • -
    • yGuard should now work together with Ant version 1.6 (there was an - undocumented change in the API of Ant). -
      • -
    -
    • -
- -

yGuard 1.2 - Changes since 1.1

-
    -
  • - Added support for external libraries. This allows yGuard to obfuscate - jars that have external dependencies more easily and using stronger - obfuscation. It is now possible to specify dependencies using Ant - classpath - elements. yGuard then uses information found in these jars to resolve - external dependencies. -
    • -
  • - Improved error handling and task and logfile output. yGuard will now - produce - fewer unreasonable warnings. During the obfuscation run yGuard will give - more detailed warnings and hints when unobfuscatable classes are detected. -
    • -
  • - Added property error-checking which can be set to - pedantic. In this case yGuard will not issue warnings but a - build will fail instead of issueing simple warnings. This helps in finding - problems. -
    • -
  • - Fixed a minor issue. The documentation stated, that - 
    <class classes="protected"/>
    - behaved like - 
    <class classes="protected">
-  <patternset>
-    <include name="**.*"/>
-  </patternset>
-</class>
    - but in the implementation <include name="*"/> - had been applied. This has now been fixed to <include - name="**.*"/>. -
    • -
  • - Fixed some bugs in the documentation. -
    • -
- -

yGuard 1.1 - Changes since 1.0.1

-
    -
  • - Added support for different naming schemes. These schemes result in - smaller - jar files, better obfuscation and lead to jar files, - which cannot be unpacked to normal filesystems. -
    • -
  • - Fixed two JBuilder incompatibilities. Innerclasses created by JBuilder do - not prevent yGuard from working anymore and (correct) innerclasses created - by yGuard do not crash JBuilder anymore (which btw. is a bug in JB). -
    • -
  • - Implemented a fix for the problem, where the ClassName.class - code construct prevented classes from being obfuscated entirely. -
    • -
  • - yGuard can now automatically obfuscate code of the form - Class.forName("com.mycompany.myapp.MyClass"); - so that these classes can now be obfuscated by name, too. -
    • -
  • - Improved the serialization of the obfuscation map to the xml file, which - can - now be parsed back in by the included tool even for complicated naming - schemes. -
    • -
  • - Refactored the creation of the final jar files. The current implementation - leads to more standard conform jar files. -
    • -
  • - Fixed two bugs concerning the handling of manifest files. -
    • -
  • - Fixed a bug concerning the handling of the Main-Class attribute of - manifest - files. -
    • -
- -

Changes since 1.0

-
    -
  • - Implemented more robust handling of Manifest files. Implementation now - makes - use of java.util.jar.Manifest. -
    • -
  • - The Main-Class attribute of the Manifest files will now be translated to - the - obfuscated name, if the main class is not exposed. -
    • -
  • - The conserveManifest attribute of the obfuscate task now conserves the - manifest in a better way. -
    • -
- -
- - - - diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..3a107393 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,26 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: default +--- + +`yGuard` is an open-source Java obfuscation tool. With `yGuard`, it is easy as pie (:cake:) to configure obfuscation through an extensive ant task. +This documentation explains how to use the `yGuard` Java obfuscation and shrinking software. + +yGuard is brought to you by [yWorks GmbH](https://www.yworks.com/), creator of the family of graph and diagram visualization frameworks [yFiles](https://www.yworks.com/yfiles) and other excellent [products](https://www.yworks.com/products). + +### Table of contents + +- [Installation](/install) + - [Using `Ant`](/install/#installation-using-ant) + - [Using `Maven`](/install/#installation-using-maven) + - [Using `Gradle`](/install/#installation-using-gradle) +- [Compatibility](/compatibility) +- [Task documentation](/task) +- [Examples](https://github.com/yWorks/yguard/tree/master/examples) +- [Troubleshooting](/troubleshooting) + +### Problems and Bug Reports + +If you experience any problems or think you have found a bug feel free to open an issue on our [public issue tracker](https://github.com/yWorks/yguard/issues). Please make sure you have read the [documentation](/task) thoroughly before. We will do our best and try to answer your questions. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..6c3ecb30 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,90 @@ +--- +layout: default +title: Installation +permalink: /install/ +--- + +Depending on your build system, you will use `AntRun` or `Ant` directly to install `yGuard`. + +### Installation using `Ant` +Download the bundle via the [latest release from GitHub](https://github.com/yWorks/yguard/releases/latest). After downloading and extracting the `jar` files, place it in a path near to your build script. You may use absolute paths, but our example following example expect the jar file to lie in the same directory as your build file. Once extracted, you can use the `yguard` element like so: + +```xml + + + + + + + + +``` + +### Installation using `Maven` +You can use `yGuard` directly from `Maven` central. Add the `yGuard` dependency to your `POM`: + +```xml + + com.yworks + yguard + 2.9.x + compile + +``` + +Once declared, you can use the `antrun` plugin to define the `yGuard` task like so: +```xml + + maven-antrun-plugin + 1.8 + + + package + + run + + obfuscate + + + + + + + + + + + + +``` + +### Installation using `Gradle` + +You can use `yGuard` directly from `Maven` central. You can define and use `yGuard` in your `build.gradle`: + +```groovy +repositories { + mavenCentral() +} + +dependencies { + compile 'com.yworks:yguard:2.9.x' +} + +task yguard { + group 'yGuard' + description 'Obfuscates and shrinks the java archive.' + + doLast { + ant.taskdef( + name: 'yguard', + classname: 'com.yworks.yguard.YGuardTask', + classpath: sourceSets.main.runtimeClasspath.asPath + ) + + ant.yguard { + // see the yGuard task documentation for information about the yGuard element + } + } +} +``` diff --git a/docs/internal-doc.html b/docs/internal-doc.html deleted file mode 100644 index 94a81c72..00000000 --- a/docs/internal-doc.html +++ /dev/null @@ -1,299 +0,0 @@ - - - - YShrink Internal Documentation - - - - - - -

YShrink Internal Documentation

- -

Contents

- - -

- -

Overview

- -

basic steps in com.yworks.yshrink.YShrink.doShrinkPairs():

-
    -
  1. Init model: create nodes for each class, method and field. Additionally, create a single entrypoint-node and one - NEW-node for each class.
    2. -
  2. Mark all entrypoints: using a composite EntryPointFilter, mark/log every entrypoint-node in the model.
    3. -
  3. Create all dependency edges using the com.yworks.yshrink.core.Analyzer.
    4. -
  4. Create additional entrypoint-edges between the entrypoint-node and each entrypoint that doesn't represent an - ordinary method (non-abstract,non-static,non-constructor).
    5. -
  5. Mark all obsolete classes, methods and fields using the com.yworks.yshrink.core.Shrinker.
    6. -
  6. Write out all non-obsolete classes using the com.yworks.yshrink.core.Writer.
    7. -
-

- -

- -

Dependency Analysis

- - -
-
-

Basic Model Edges

 -
- -
-
    -
  • - Create EXTENDS edges from each class to its superclass, if the superclass is contained in the model.
    - [Method: com.yworks.yshrink.core.Analyzer.createInheritanceEdges()] -
    • -
  • - Create IMPLEMENTS edges from each class to all of its interfaces, if the interface is contained in the model. -
    - [Method: com.yworks.yshrink.core.Analyzer.createInheritanceEdges()] -
    • -
  • - Create MEMBER_OF edges from each method, field and from the special NEW-node to the class it belongs to. -
    • -
  • - Create ENCLOSE edge from each inner class to its enclosing class or method. -
    • - -
-
-
- -
-
-

Method Invocations

 -
- -
- Basic Algorithm:.
- -
    -
  • - Create INVOKE and RESOLVE edges to the first implementation of the target method found in the target class or - any superclass of the target class.
    - While searching for the implementation, create RESOLVE edges to each class that does not implement the target - method.
    - [Method: com.yworks.yshrink.core.Analyzer.createEdgesToAncestorMethods()] -
    • -
  • - Create INVOKE edges to all implementations of the target method in any sublcasses of the target class.
    - [Method: com.yworks.yshrink.core.Analyzer.createSubtreeEdges()] -
    • -
- - Special Rules: - -
    -
  • - If the target class is an interface, the basic algorithm is run on all implementations of that interface.
    - [Method: com.yworks.yshrink.core.Analyzer.createEdgesToAncestorMethods()]
    • -
  • - If the target class is an interface or the target class is abstract and the target method is declared in any - parent - interface of the abstract class, a RESOLVE edge is created to the declaration of the target method.
    - [Method: com.yworks.yshrink.core.Analyzer.createEdgeToDeclation()] -
    • -
  • - If the invocation is a call to a super method, the basic algorithm is NOT applied. Instead:
    -
      -
    • If the call is a "chain" call to the super-constructor, a special CHAIN edge is created.
      • -
    • - Else, a SUPER edge is created to the implementation of the target method in the first super - class of the target class that implements the target method. -
      • -
    - [Method: com.yworks.yshrink.core.Analyzer.createInvokeEdges()] -
    • -
  • - For constuctor calls, an ordinary INVOKE edge is created to the specific <init> method.
    - Additionally, a special CREATES Edge is created to the special NEW node in [Method: - com.yworks.yshrink.core.Analyzer.createTypeInstructionEdges()], - indicating that the target class is instantiated. -
    • -
- -
-
- - -
-
-

External Dependencies, Entrypoints

 -
- -
-
    -
  • If a class inherits from any external class that cannot be resolved, ASSUME edges are created from the - NEW-node to every none-private method.
    • -
  • If all external classes/interfaces that a class inherits from can be resolved, ASSUME edges are created from - the NEW-node to any - method overriding a method of the external ancestor classes/interfaces.
    - If the class itself does not override an externally defined method, the parent classes of that class contained - in the model are searched for an - implementation and the ASSUME edge is created to that implementation instead.
    • -
  • For all entrypoint-methods that are members of an ancestor class that is contained in the model, - an ASSUME edge is created from the NEW-node to its implementation in the class itself or a parent class.
    • -
- [Method: com.yworks.yshrink.core.Analyzer.createAssumeEdges()] -
-
- -
-
-

Type Instructions

 -
- -
-
    -
  • - For each type instruction with opcode ANEWARRAY, MULTIANEWARRAY, INSTANCEOF, CHECKCAST or LDC (class version >= - 0.49), - a RESOLVE edge is created from the source method to the corresponding type. -
    • -
  • - If the opcode is NEW, a CREATES edge is created to the NEW-node of the corresponding type. -
    • -
-
- [Method: com.yworks.yshrink.core.Analyzer.createTypeInstructionEdges()] -
- -
-
-

Method Signatures

 -
- -
-
    -
  • RESOLVE edges are created from each method to its return type, exception types and argument types.
    • -
- [Method: com.yworks.yshrink.core.Analyzer.createMethodSignatureEdges()] -
-
- - -
-
-

Field References

 -
- -
-
    -
  • - A REFERENCES edge is created from the referencing method to the field in the class the declares the field. - If the field is not declared in the runtime class, the superclasses and interfaces of the - runtime class are searched for the declaration. While searching for the declaration, - RESOLVE edges are created to the visited concrete classes. -
    • -
- [Method: com.yworks.yshrink.core.Analyzer.createReferenceEdges()] -
-
- -
-
-

.class-construct

 -
- -
-
    -
  • - If the version of a class is >= 0.49, the .class-construct is easily identified by LDC opcodes. -
    - [Method: com.yworks.yshrink.core.Analyzer.createTypeInstructionEdges()] -
    • -
  • - If the version of a class is < 0.49, the .class-construct is identified by checking each field - in [Method: com.yworks.yshrink.core.Analyzer.createReferenceEdges()] - for the synthetic field "class$.." that is inserted in the bytecode by javac. RESOLVE edges are - created to all possible classes given by the name of the synthetic field.
    - [Method: com.yworks.yshrink.core.Analyzer.checkLegacyDotClassField()] -
    • -
  • jikes/eclipse compiler etc are not yet accounted for.
    • -
-
-
- - - -

- - -

- -

Shrinking

- - -
-
    -
  • Initially, no node is marked as instantiated and all nodes are marked as obsolete.
    • -
  • Using the global entrypoint-node as the startnode, a dfs is run on the dependency graph.
    • -
  • Edges are traversed under the following conditions:
    • -
      -
    • If the target node is a class or field node, the edge may always be traversed.
      • -
    • An edge to a method node may be traversed if it is not a RESOLVE edge and:
      • -
        -
      • The target method is static or
        • -
      • The edge represents a super call or
        • -
      • The target node is the NEW-node of a class or
        • -
      • The target method is a constructor or
        • -
      • The target method is private or
        • -
      • The target method is a regular method and the class the method belongs to is marked as instantiated - or
        • -
      • The target method is needed, i.e. a child class of the class the method belongs to is instantiated and - does not override the method.
        • -
      -
    -
  • If an edge is allowed to be traversed and the target node is a NEW-node, the corresponding class is marked as - instantiated.
    • -
  • As long as the amount of classes marked as instantiated increases, rerun the dfs.
    • -
  • If the amount of classes marked as instantiated does not increase between two dfs-rounds, - a last dfs is run in order to mark all reachable nodes as non-obsolete. - Also, the RESOLVE edges that target methods are allowed to be traversed in this last round in - order to mark the target methods as needed for resolving (that is, only a stub of these methods is - needed).
    • -
-
-

- - -

- -

- - \ No newline at end of file diff --git a/docs/task_documentation.md b/docs/task_documentation.md new file mode 100644 index 00000000..f032d4a5 --- /dev/null +++ b/docs/task_documentation.md @@ -0,0 +1,1465 @@ +--- +layout: default +title: Task documentation +permalink: /task/ +--- + +## Preamble + +Using the `yGuard` Ant task, name obfuscation and code shrinking can be seamlessly integrated into your deployment process. + +The `yguard` task contains two nested elements that perform the name obfuscation and code shrinking separately: + +- The [shrink](#the-shrink-element) element removes all code elements that are not reachable from the entrypoints given in the nested [keep](#the-keep-element) element. +- The [rename](#the-rename-element) element performs name-obfuscation, renaming all packages, classes, methods and fields according to a selectable name-mapping scheme. Elements can be excluded from the renaming process by annotating them with a certain annotation class in the source code or using a nested [keep](#the-keep-element) element. + +## The yguard Element + +The yguard task contains elements that define basic properties common to the nested `rename` and `shrink` tasks. +Please see the [troubleshooting section](/troubleshooting) to learn about common pitfalls when using name obfuscation and shrinking software. + +#### Attributes + +The `yguard` element has no attributes. + +#### Child Elements + +- [inoutpair](#the-inoutpair-element) +- [externalclasses](#the-externalclasses-element) +- [attribute](#the-attribute-element) +- [rename](#the-rename-element) +- [shrink](#the-shrink-element) + +### The `inoutpair` Element + +At least one `inoutpair` element or one non-empty `inoutpairs` element has to be specified in order to run the yguard tasks. This element specifies the paths to the input and output jar files. + +#### Attributes + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
in + Specifies an exisiting jar file, which contains the unshrinked and + unobfuscated .class files. + Yes
out + Specifies a path to a jar file which will be created and used to + put the results of the shrinking and obfuscation process. + Yes
resources + Will only be considered if the + yguard element + contains a nested + shrink element. +
+ Determines how the shrinking engine handles all non-.class files. +
+ Currently the following three resource policies are supported: +
    +
  • copy
    + the default, simply copies all resource files to the output jar. +
    • +
  • auto
    + copies only those resource files that reside in a directory that + still contains one or more .class files after shrinking. +
    • +
  • none
    + discards all resource files. +
    • +
+ 		+ No, defaults to copy. +
+ +#### Child Elements + +The `inoutpair` element has no child elements. + +If multiple jar files need to be obfuscated at once the `inoutpairs` element can be used alternatively. + +## The `inoutpairs` Elements +Additionally or alternatively to `inoutpair` elements this element can be specified in order to specify the paths to the input and output jar files. + +#### Attributes + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
resources + Will only be considered if the + yguard element + contains a nested + shrink element. +
+ Determines how the shrinking engine handles all non-.class files. +
+ Currently the following three resource policies are supported: +
    +
  • copy
    + the default, simply copies all resource files to the output jar. +
    • +
  • auto
    + copies only those resource files that reside in a directory that + still contains one or more .class files after shrinking. +
    • +
  • none
    + discards all resource files. +
    • +
+ 		+ No, defaults to copy. +
+ +#### Child Elements + +- [patternset](http://ant.apache.org/manual/Types/patternset.html) +- optionally a [mapper](http://ant.apache.org/manual/Types/mapper.html) that determines the name mapping between the unobfuscated and obfuscated versions of the jar files. Note that `identitymapper` and `mergemapper` are not supported. All matched jar file names need to be mapped to exactly one jar file name that differs from the original jar file. + +#### Examples + +```xml + + + + + + + + + + + + + + + + +``` + +## The `externalclasses` Element +If the jar to be processed by `yGuard` depends on external classes or libraries, this element can be used to specify classpaths to these entities. These libraries will neither be shrinked nor obfuscated. Use the `inoutpair` element for this purpose! See [external-example] for an example of when to use this element. +In order to achieve a maximum shrinking effect by the `shrink` task, all external dependencies should be declared in the `externalclasses` element. Otherwise, all non-private methods of classes that inherit from unresolvable classes will not be shrinked. + +The elements attributes and child elements can be seen on the [Ant documentation page about using path elements](http://ant.apache.org/manual/using.html#path). + +## The attribute Element +Using the `attribute` element, you can specify which attributes present in the input classes should be kept in the obfuscated output classes. + +See [linked example] for an example of when to use this element. + +#### Attributes + + + + + + + + + + + + + + +
AttributeDescriptionRequired
nameA comma-separated list of attribute names that are to + be retained in the shrinked and/or + obfuscated class + files. + Yes
+ +#### Child Elements + +- [patternset](http://ant.apache.org/manual/Types/patternset.html) + +#### Example + +```xml + + + + + +``` + +This will retain the attributes named _"SourceFile"_, _"LineNumberTable"_, and _"LocalVariableTable"_ effectively enabling debugging information for all classes in the `com.mycompany.mylibrary` package and subpackages. + +## The `shrink` Element +The `shrink` task removes all classes, fields and methods that are not reachable from a number of entrypoints given by a nested [keep]() element. +See the [examples]() explenation of some common use cases. If your code uses reflection, please read the [troubleshooting](/troubleshooting) section for information on this topic. + +#### Attributes + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
logfileDetermines the name of the logfile that is generated + during the shrinking process. The logfile contains information about + the entrypoints the shrinking engine uses, the removed classes, + methods and fields as well as any warnings. +
+ If the name ends with a ".gz", yGuard will automatically create a + gzipped version of the file which potentially saves a lot of disc + space. + 		+ No, defaults toyshrinklog.xml +
+ createStubs + + Instead of removing methods completely, this attribute causes the + shrink task to insert a method + stub that throws a java.lang.InternalError if it is + called. This attribute is very useful if the shrinking process + causes your application to break and you are uncertain about which + additional code entities you have to include in the + keepelement.
+ Note that classes considered as completely obsolete by the shrinking + engine are still removed completely - this attribute only + affects obsolete methods of non-obsolete classes. + 		+ No, defaults to false +
+ +#### Child Elements + +- [keep](#the-keep-element) +- [entrypointjar](#the-entrypointjar-element) + +## The `entrypointjar` Element + +The `entrypointjar` element can be used for convenience if your application uses libraries that are to be shrinked, but the jarfile using these libraries should be left untouched by the shrinking engine. Such a jarfile could be specified as an `entrypointjar`. + +#### Attributes + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
namePath to to the jar file to use as entrypointjar.Yes
+ +#### Child Elements + +The `entrypointjar` element has no child elements. + +#### Example + +```xml + + + + + + +``` + +## The `rename` Element +The basic idea is, that all elements will be renamed by this task. There are different use cases, where you sometimes want to exclude or simply just have to exclude some elements from name obfuscation, i.e. **not** rename them but keep in the API as is. See the [examples]() for explanation of some common use cases. If your code uses reflection, please read the [troubleshooting](/troubleshooting) section for information on this topic. Excluding elements can be achieved by using the [keep](#the-keep-element) element, the `mainclass` attribute of the `rename` element and by annotating elements in the source code with the annotation that is specified in the `annotationClass` attribute of the `rename` element. Using the nested `keep` element, you have to specify all classes, methods, fields, and attributes that should be excluded from name obfuscation. Another way is to [annotate the elements directly in the source code](#annotate) that should be obfuscated or excluded. You can use the yFiles obfuscation annotation `com.yworks.util.annotation.Obfuscation` for that or specify your own annotation in the `annotationClass` attribute of this element. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
mainclassCan be used as a shortcut to specify the mainclass + of your application. Both the class name and the main method will be + excluded from name obfuscation. + Alternatively you may want to consider to exclude the main method + only. If your jar contains a Main-Class attribute, the + rename task will automatically adjust + the value to the obfuscated + name. + No
logfileDetermines the name of the logfile that is generated + during the renaming process. The logfile contains information about + the mappings the name obfuscator generates as well as any warnings. +
+ If the name ends with a ".gz", yGuard will automatically create a + gzipped version of the file which potentially saves a lot of disc + space. + 		+ No, defaults toyguardlog.xml
conservemanifest + A boolean attribute (valid values: + true/false) that determines whether the + manifest file of the jars should be left untouched by the renaming + engine. If set to false, the manifest will be modified + to reflect the new message digests. + + No, defaults to false. +
+ replaceClassNameStrings + + A boolean attribute (valid values: + true/false) that determines whether the + renaming engine should try to replace hardcoded Strings, which + are used in conjunction with the MyClass.class + construct. + If set to false, those Strings will be left untouched + and code of the form MyClass.class will break if + MyClass gets obfuscated by name. If set to true (the + default), yGuard will try to workaround this problem by replacing + the hardcoded String with the appropriate obfuscated name. However + this will only work if the unobfuscated class file has been + generated with the usual compilers ('javac', 'jikes' and 'bjc') or + compilers, that produce similar bytecode. This can also have the + side-effect of modifying too many Strings, e.g if you have code that + looks likeSystem.out.println("com.mycompany.MyClass");, + it might get replaced, if MyClass.class resides in the + very same class with something like + System.out.println("com.A.OoO");. It will most likely + fail if the class has been previously obfuscated by another + obfuscation tool or a different compiler has been used for + compilation. Anyway it is always worth it to give it a try, if you + want to have 'full obfuscation'. + + No, defaults to true +
annotationClass + Specifies the name of the annotation class that can be used to + exclude elements by annotating them in the source code. The + specified annotation can be any annotation that fits the convention. + + No, defaults to com.yworks.util.annotation.Obfuscation +
+ +#### Child Elements + +- [keep](#the-keep-element) +- [property](#the-property-element) +- [patch](#the-patch-property) +- [adjust](#the-adjust-property) +- [map](#the-map-property) + +## The property Element + +`property` elements can be used to give hints to the name obfuscation engine. Depending on the exact version of yGuard, the task may use these hints to control the process of obfuscation. + +#### Attributes + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
name + Specifies a key which may be interpreted by the obfuscation task. + Yes
value + Specifies the corresponding value of the property. + Yes
+ +#### Supported properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
error-checking + Can be used to tell yGuard to bail out if it detects any problems. + Currently this property can be set to the following value: +
    +
  • + pedantic
    + Will make the obfuscation run fail, i.e. the target which uses + the renameelement will fail, if + yGuard detects any problems. +
    • +
+
naming-scheme + Can be used to tell the renaming engine to use a different naming + scheme during the obfuscation. + Currently this property can be set to one of the following values: +
    +
  • + small
    + Will produce very short names, i.e. the resulting jar + file will be as small as possible. +
    • +
  • + best
    + Will produce names, that are very likely to be misunderstood by + decompilers and disassemblers. Using this naming-scheme it is + even impossible on most filesystems to successfully unjar or + unzip the resulting jar file (Windows, Standard Unix, Standard + Linux, MacOS). + However this scheme takes up a lot of space and the resulting + jar is likely to become large (typically roughly double the + size). +
    • +
  • + mix
    + Is a mixture of both the other two values, which leads to + reasonable small but still hard to decompile jar files. +
    • +
+
language-conformity + Can be used to advise the renaming engine to produce names, that + should be decompilable by most decompilers. On the other hand, + yGuard can produce class files that should be executable and + verifiable by all of todays virtual machines, but produces + absolutely nonsense names when decompiled (Ever tried to compile + 'int class = false.this super(String$super.init if);' + ?!) + Currently this property can be set to one of the following values: +
    +
  • + compatible
    + Will produce names, that are ok for (most) decompilers, java, + jar and manifest files and can be unzipped to most filesystems. +
    • +
  • + legal
    + Will produce names, that are ok for (some) decompilers, java, + jar and manifest files. +
    • +
  • + illegal
    + Will produce names, that will crash some tools but usually + not the jvm, but JBuilder7 in many occasions for example. +
    • +
+
overload-enabled + Determines whether the renaming engine tries to use the same names + for methods with different signatures or whether it always generates + unique method names. + Setting this property to false eases the analysis of + stacktraces but reduces the obfuscation effect. +
obfuscation-prefix + Can be used to instruct the renaming engine to prefix packages, that + are fully obfuscated with a given package prefix, e.g. + com.mycompany.obf. +
digests + Can be used to tell yGuard which digest algorithms should be used + for the digest generation in the manifest file. Valid values are + either none, or a comma-separated + list of digest-algorithm identifiers, e.g. + SHA-1, MD5 (which is the default). +
expose-attributes + Can be used to give yGuard a list of attributes yGuard should expose + in addition to the standard attributes. + By default yGuard removes unneeded attributes like "Deprecated" from + methods. The value can be a comma separated list of attributes as + defined in + Section 4.7 of the VM Specification of the .class File Format. + E.g. in order to keep the "Deprecated" attribute one can add the + following property: +
+ <property name="expose-attributes" value="Deprecated"/> +
+ Note that this affects all classes which will be obfuscated. For a + better control of which attributes should be exposed in what classes + use the Attribute Element. +
+ +#### Child Elements +The `property` element has no child elements. + +## The `keep` Element + +This element is a child of the [rename](#the-rename-element) or [shrink](#the-shrink-element) element. It can be used to specify elements that are excluded from the parent `rename` or `shrink` task. The excluded classes, methods and fields are defined using nested [package](#the-package-element), [class](#the-class-element), [method](#the-method-element) and [field](#the-field-element) elements. + +#### Attributes + +The `keep` element provides a number of boolean attributes that determine whether debug information and annotations present in the input class files are to be retained in the output files. The default behavior of the `rename` and `shrink` elements for the respective attributes is explained in the table below. +Note that a more fine-grained control over which attributes to keep for which class files is possible using the [attribute](#the-attribute-element) element. Also, the `attribute` element allows to define attributes to keep for both the rename and the shrinkelement in a common place. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionDefault (rename)Default (shrink)
sourcefile + Determines whether the name of the original source code file should + be included in the output class files. + removeremove
linenumbertable + Determines whether the line number table, that contains a mapping + from each opcode in the class file to the line number in the + original source code file should be included in the output class + files. + remove remove
localvariabletable + Determines whether the local variable table, that contains a mapping + from each local variable in the class file to the name that has been + used in the original source code file should be included in the + output class files. + remove remove
localvariabletypetable + Determines whether the local variable type table, that contains a + mapping from each local variable in the class file to the name and + its generic type signature that has been used in the original source + code file should be included in the output class files. + remove remove
runtimevisibleannotations + Determines whether annotations with the retention policy + RetentionPolicy.RUNTIMEshould be included in the output + class files. + keep keep
runtimevisibleparameterannotations + Determines whether method paramater annotations with the retention + policy RetentionPolicy.RUNTIME should be included in + the output class files. + keep keep
runtimeinvisibleannotations + Determines whether annotations with the retention policy + RetentionPolicy.CLASSshould be included in the output + class files. + keep remove
runtimeinvisibleparameterannotations + + Determines whether method paramater annotations with the retention + policy RetentionPolicy.CLASS should be included in the + output class files. + keep remove
+ +## The `class` Element + +The `class` element can be used for excluding certain classes and/or their fields and methods from the renaming or shrinking process. +If no `name`, `extends` or `implements` attribute is given and the `class` element contains no nested `patternset`, a `class` element matches all class names. + +The `classes`, `methods` and `fields` attributes tell the shrinking and renaming engines which classes, methods and fields to keep based on their visibility. The following table lists the possible values for all of these attributes and shows which elements will be excluded. A '*' denotes, that elements that have the given visibility will be excluded for the specified attribute value. A '-' denotes that the these elements will not be excluded from the process. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Value/Visibilitypublicprotectedfriendlyprivate
none----
public*---
protected**--
friendly***-
private****
+ +#### Attributes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
nameThe name of the class to be kept.No
classesThe visibility of the classes to be kept. + No, defaults to none
methodsThe visibility of the methods to be kept. + No, defaults to none
fieldsThe visibility of the fields to be kept. + No, defaults to none
extends + If no name attribute is given, keeps + all classes that equal or extend the class defined by the given + fully qualified classname. +
+ See example 7 for an example usage of this + attribute. + 		No
implements + If no name attribute is given, keeps + all classes that equal or implement the class defined by the given + fully qualified classname. +
+ See example 7 for an example usage of this + attribute. + 		No
+ +#### Child elements + +- [patternset](http://ant.apache.org/manual/Types/patternset.html) + +#### Explanation + +There are three possible ways of specifying which classes will be excluded from the shrinking and obfuscation process: + +_1)_ One can specify a single java class using the fully qualified name in java syntax with the name attribute. For example: +```xml + +``` +_2)_ One can specify multiple java classes using a modified version of a patternset. The patternset's includes and excludes element should use java syntax, but the usual wildcards are allowed. Some examples: +```xml + + + + + + + +``` +_3)_ This will expose all classes which reside in the package subtree of `com.mycompany` and whose name ends with `Bean` except for those, that reside in the `com.mycompany.secretpackage` package and the single `SecretBean` in `com.mycompany.myapp`. + +```xml + + + + + + + +``` + +This will expose the `MainClass` class and all classes, which reside in packages like `org.w3c.sax1`, `org.w3c.sax2`, `org.w3c.saxb` except for inner classes. `'$'` is used as a separator between outer class names and inner class names. Since Ant uses `'$'` as an escape character, you have to use two consecutive `'$'s` (`'$$'`) if you want to pass one as an argument to the task. + +_4)_ Finally one can specify classes depending on their visibility, i.e. depending whether they have been declared `public`, `protected`, `package-private` or `private` (inner classes). This can be achieved by additionally specifying the classes attribute in the class element. + + ```xml + + + + + +``` + +This will keep all class names, that are either `public` or `protected` and which reside in one of the subpackages of `com.mycompany.myapi` (note the abbreviation: the trailing dot behaves like the trailing `'/'` in the usual patternset, i.e. it could be rewritten as `com.mycompany.myapi.**.*`) + +```xml + + + + + +``` + +This example shows the very common use case of excluding a complete public API from the shrinking and obfuscation process. There is an abbreviation for this use case: you can omit the `patternset` element, since in the case where the `classes` attribute is specified and there is no `patternset` child element used, the task will automatically apply this rule. In this example all classes will be exposed, that are either `public` or `protected`. Their methods and fields will be exposed as long as they are declared `public` or `protected`. If a class is `package-private` or `private` (inner classes), neither itself nor its methods or fields will be exposed. + +The last example shows how to keep the `public` methods of certain classes only, but neither field names nor the class names themselves. +```xml + + + + + +``` + +## The `method` Element +Using the `method` element you can specify methods by signature which should be excluded from shrinking or name obfuscation. + +#### Attributes + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
name + Specifies the method to keep. Use the complete signature using + fully qualified class names and the return type! + Yes
class + Specifies the class which contains the method. Use the normal java + syntax, i.e. the fully qualified name. + This attribute can be omitted, if the patternset element is used as + a child element, in which case all classes matching the patternset + will be searched and their corresponding methods will be kept. + No
+ +#### Child Elements + +- [patternset](http://ant.apache.org/manual/Types/patternset.html) + +#### Examples + +```xml + + + + + + + + + + + + +``` + +This will keep the main method of the `MyClass` class and the `foo` method. Additionally all `readObject` and `writeObject` methods (used for serialization) will be kept in all classes of the `com.mycompany.myapp.data` package. Note that you have to specify the return argument's type, even if it is void and that you have to use the fully qualified name for all classes, even those, that are in the `java.lang package`. + +## The `field` Element + +Using the `field` element you can specify fields by name which should be excluded from shrinking or name obfuscation. + +#### Attributes + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
name + Specifies the field to keep. + Use the name of the field only, do not include its type! + Yes
class + Specifies the class which contains the field. + Use the normal java syntax, i.e. the fully qualified name. + This attribute can be omitted, if the + patternset element is used as + a child element, in which case the all classes matching the + patternset will be searched and their corresponding fields will be + kept. + No
+ +#### Child Elements + +- [patternset](http://ant.apache.org/manual/Types/patternset.html) + +#### Examples + +```xml + + + + + + +``` + +This will keep the field named `field` of the `MyClass` class. Additionally all the `serialVersionUID` fields (used for serialization) will be kept in all classes of the `com.mycompany.myapp.data` package. + +## The `package` Element +The `package` element can be used for excluding certain package's names from the renaming process. It cannot be used for the shrinking process. + +All packages that are matched be the nested patternset element will not be obfuscated. This has no influence on the class, method, or field names but will only result in the package's name not being obfuscated. Normally, it is not necessary to use this element, instead the [class element](#the-class-element) is used to keep class names (and thus their package names) from being obfuscated. + +#### Child Elements + +- [patternset](http://ant.apache.org/manual/Types/patternset.html) + +#### Example + +```xml + + + + + +``` + +This will keep the names of all packages that are direct descendants of `com.mycompany.myapp`. This will not influence the names of the classes contained in these packages. + +## The `sourcefile` Element + +The `sourcefile` element allows for a special treatment of the sourceFile attribute by the rename element. +Using nested property elements, the mapping of sourceFile attributes in obfuscated class files can be adjusted. + +#### Attributes + + + + + + + + + + + + + + +
NameDescription
mapping + The value of this property determines the name all + sourceFile attributes matched by the + sourcefile element are mapped to. +
+ +#### Child Elements + +- [property](#the-property-element) +- [patternset](http://ant.apache.org/manual/Types/patternset.html) + +#### Example + +```xml + + + + + + +``` + +This will map all of the `sourceFile` attributes in the packages below `com.mycompany.myapp` to _"y"_, which is small and generally a nice letter. + +## The `linenumbertable` Element + +The `linenumbertable` element allows for a special treatment of the linenumbertable attribute by the [rename](#the-rename-element) element. + +Using nested `property` elements, the mapping of `linenumbertable` attributes in obfuscated class files can be adjusted. + +#### Attributes + + + + + + + + + + + + + + + + + + + +
NameDescription
mapping-scheme + Can be used with the following two values: +
    +
  • + scramble
    + This will use a non-trivial algorithm to scramble the line + numbers in the existing file. + The algorithm implemented uses a different scrambling scheme for + each class. The optional + scrambling-salt property can be + used to provide an integer value that will be used to "salt" + the algorithm's random seed for the scrambling. + The size of the (uncompressed) .class file will not change using + this mapping scheme. +
    • +
  • + squeeze
    + This will use a simple algorithm that virtually puts all of a + method's code into the first line of code of the method. It will + appear as if each method had been written in a single line of + code. + The advantage of this scheme is drastically reduced size + requirements and thus smaller .class files, while at the same + time it will be possible to unambiguously determine the exact + method from a stacktrace. +
    • +
+
scrambling-salt + Can be used in conjunction with + mapping-scheme to provide an integer + value that will be used to "salt" the algorithm's random seed for + the scrambling. +
+ +#### Child Elements + +- [property](#the-property-element) +- [patternset](http://ant.apache.org/manual/Types/patternset.html) + +#### Examples + +```xml + + + + + +``` + +This will keep the line numbers of all the classes in the `com.mycompany.myapp` packages and subpackages. Note that in order to see the line numbers in stacktraces, the sourcefile attribute has to be retained for those files, too, since otherwise the JDK will display _"Unknown source"_ for the stack elements. + +```xml + + + + + + + + + + + +``` + +This will keep scrambled line numbers for all classes found in and below the `com.mycompany.myapp` packages. The scrambling algorithm will use the given _"salt"_ value to use a predefined scrambling scheme. In order to see the scrambled line numbers, a [sourcefile](#the-sourcefile-element) element is used on the same patternset, which is referenced by its previously declared reference id, to rename the source files to _"y"_. + +## The `adjust` Element +Using the `adjust` element one can specify resource files whose names and/or contents should be adjusted by the rename engine to reflect the obfuscated class names. + +**Note**: This will only adjust files that are part of the *inoutpair* jars! _I.e._ the fileset's root directory is the combined root of all jars that are passed to yGuard via the `inoutpair` elements. yGuard will not modify any of the files on disk, except for the out-jar! + +#### Attributes + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
replaceName + Specifies whether or not the names of the specified resources should + be adjusted. + No, defaults to false +
replaceContent + Specifies whether or not the contents of resource files should be + adjusted. + No, defaults to false +
replacePath + Specifies whether or not the paths to the resource files should be + adjusted. + No, defaults to true
+ +#### Child Elements + +The adjust element can be used just like the standard Ant [`ZipFileSet`](http://ant.apache.org/manual/Types/zipfileset.html) element. + +#### Examples + +```xml + + + + + + + + + + + + + +``` + +## The `map` Element + +The `map` element is an immediate optional child of the [rename element](#the-rename-element). It can be used to specify the mapping for the renaming process directly. This is an advanced topic. + +#### Child Elements + +- [package](#the-package-element) +- [class](#the-class-element) +- [method](#the-method-element) +- [field](#the-field-element) + +All of these elements use the `name` attribute to specify the specific element. The `method` and `field` elements need the `class` attribute in order to function properly. Neither wildcards nor nested `patternset` elements are allowed. Use the `map` attribute to specify the new name (subpackage, classname, methodname and fieldname respectively). + +#### Examples + +```xml + + + + + + + + +``` + +In this example the package structure `com.mycompany.myapp` will be obfuscated to `etc.nocompany.asdf`. The `MainApp` class will be called `foo` and its `main` method will be remapped to `bar` (and can therefor not be executed from commandline anymore). The field called `field` will be renamed to `a`. + +## Controlling obfuscation exclusion with annotations + +In order to exclude certain elements from obfuscation, it is possible to use annotations in the source code instead of listing those elements in the [keep element](#the-keep-element). + +Any annotation class can be used for this, but it must be specified in the `annotationClass` attribute of the [rename element](#the-rename-element) and follow the convention as explained below to work. yGuard contains such an annotation in the distribution package ready for use. The annotation class is `com.yworks.util.annotation.Obfuscation` and can be found in the yGuard distribution in `ObfuscationAnnotation.jar`. Feel free add this attribute definition to your own codebase and possibly adjust the package name to your needs. Here is the source code for it: + +### `Obfuscation.java` + +```java +package com.yworks.util.annotation; + +public @interface Obfuscation { + + boolean exclude() default true; + + boolean applyToMembers() default true; +} +``` + +This class is also the default annotation yGuard is looking for when obfuscating. + +The convention for annotation classes that yGuard understands as obfuscation controlling annotations requires two attributes: + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionDefault value
exclude + Specifies whether the annotated element should be excluded from the + obfuscation. Note, that when retaining a class, the hierarchy of + that class, i.e. the chain of outer class names and the package + name, is also retained. + true
applyToMembers + Specifies whether the child elements of the annotated element, if + not otherwise specified, should be excluded from the obfuscation. + For example, when annotating a class with + exclude = true and this attribute set to + true, inner classes, fields and methods of this + class will be excluded from obfuscation. Annotating a child element + of an element that has this attribute set to true will + override the parents annotation configuration. + true
+ +## Generating Patch JARs + +The true power of the `map` element lies in its use together with the `patch` element, which itself is a child element of the `rename` top level element. + +#### Attributes + +The `patch` element has no attributes. + +#### Child Elements + +- [class](#the-class-element) + +#### Examples + +Using the `patch` element one can generate jars, that can be used to serve as patches for versions of an application that have already been deployed in obfuscated form. During the main obfuscation run, yGuard produces an xml-logfile, in which the mapping between the unobfuscated and obfuscated names is contained. The patch element is used to declare a set of classes, that need to be patched. During the obfuscation, yGuard will include those files in the obfuscated jars only, that are declared inside this element. + +```xml + + + + + + + + + +``` +This will only include the MainClass class and all classes that belong to the bugs package in a patch jar. In order to work with the previously delivered obfuscated version, it is important to use the map element to specify the mapping of the elements from the previous run. This can most conveniently be achieved by specifying the log file from the corresponding run in the map element's logfile attribute. + +## Deobfuscating Stacktraces Etc. + +yGuard provides a simple tool that makes it easy for the obfuscating party to deobfuscate stacktraces which have been obfuscated using yGuard. During the obfuscation yGuard produces an xml logfile which can automatically be gzipped for convenient storage. You should always keep those logfiles in order to be able to deobfuscate fully qualified classnames or methods or fields for debugging purposes e.g. +In order to run the yGuard deobfuscation tool do the following: + +``` +Console> java -jar yguard.jar mylogfile.xml +``` + +A tiny GUI will popup that will enable you to easily deobfuscate stacktraces and fully qualified classnames as well as provide a convenient way to browse the mapping generated by yGuard. +In the main window a tree view displays the package, class, and classmember hierarchy using the unobfuscated names. For each entry that has been obfuscated (classes, packages, methods, and fields that have not been obfuscated at all may not always be shown in the tree) the corresponding mapped/obfuscated name is displayed. +The two buttons at the top of the window allow to change the sorting of the items in the tree structure, so that they are either sorted according to their names before or after the obfuscation. Items will always be sorted by type first: packages, classes, innerclasses, methods, and fields. Small icons provide a convenient way to quickly find the corresponding items. + +The lower part of the window contains an editable text area that can be used to enter text or paste stacktraces in. Pressing the button at the bottom of the window labelled "Deobfuscate" will trigger the deobfuscation of the contents in the text area. The tool will try to identify fully qualified class names (separated by dots) and use the mapping information to reconstruct the original names. If the tool identifies a stack trace element, it will try to deobfuscate scrambled line numbers, too, if they have been scrambled during the obfuscation process. + +# DTD used for Ant `` + +The obfuscation and shrinking process can be completely configured inside your Ant script. The yguard task and nested elements should be used according to the following DTD. Note that this is for information purposes only, i.e. you do not have to include the following lines anywhere. This DTD should just provide a quick overview of the yGuard syntax. Due to restrictions of the DTD specification, the given DTD does not describe all available yGuard options. Please browse through the documentation above for complete documentation of the yGuard Ant task elements. + +```xml + + + + + + + + + + +name CDATA #REQUIRED> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +**Attention** users of IDEs that "support" the creation of Ant files (e.g. IDEA's IntelliJ): Your IDE may indicate some errors inside your ANT file when you use yGuard specific elements. This is because the IDE does not know about the DTD used by yGuard. However this is not a real problem, since the Ant file should nevertheless work as expected. diff --git a/docs/test.xml b/docs/test.xml deleted file mode 100644 index 54db54e4..00000000 --- a/docs/test.xml +++ /dev/null @@ -1,172 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ]> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..14e2cb75 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,23 @@ +--- +layout: default +title: Troubleshooting +permalink: /troubleshooting/ +--- + +There are a couple of things you should be aware of when obfuscating and shrinking software. +The weakest part of an application considering name obfuscation and code shrinking is code that uses reflection to dynamically load classes, invoke methods etc. Therefore, you have to be especially careful when using the yguard task on applications that rely on reflection. +The most important facts to keep in mind when using yGuard are described here briefly: + +- If you use the `rename` task, code in the form of `MyApplication.class` will break if `MyApplication` will be obfuscated by name and the obfuscation switch [replaceClassNameStrings](/task/#the-rename-element) is set to `false`. The `shrink` task will currently recognize code in the form of `MyApplication.class` only if the java files were compiled using an arbitrary version of the standard javac compiler (although the shrinking engine might recognize the `.class` construct also if the classes were compiled using a compiler that generates similar bytecode). +- Automatic introspection and reflection will break in most cases, when you decide to obfuscate the corresponding methods and fields. If you use the `shrink` task and your application uses reflection you should explicitly designate all entities loaded per reflection as code entrypoints using the [keep](/todo/#the-keep-element) element. +If your application is broken after using the `shrink` task, consider using the [createStubs](/task/#the-shrink-element) attribute of the `shrink` task to find out which additional entities you need to include in the keep element. +- `Class.forName(className)` will not work when using the `rename` task unless you use the obfuscated name string in your variable or the String is a local constant and [replaceClassNameStrings](/task/#the-keep-element) is not set or set to `true`. If you use the `shrink` task, `className` should be contained in the list of entrypoints using the `keep` element. +- The customized serialization mechanism will not work if you obfuscated or shrinked the writeObject and readObject methods as well as the serializationUID field. +- Simple bean introspection will not work, if you decide to obfuscate your public accessor methods, since it makes use of reflection. +- If you do not set the `-Xmx` property for the Java virtual machine, the `yguard` Ant task might fail due to a `java.lang.OutOfMemoryError`. +To solve this problem, set the `-Xmx` option in the `ANT_OPTS` variable, e.g.: +``` +bash> export ANT_OPTS="-Xmx512M" +or +cshell> setenv ANT_OPTS "-Xmx512M" +``` diff --git a/docs/yguard_ant_howto.html b/docs/yguard_ant_howto.html deleted file mode 100644 index 6641b65b..00000000 --- a/docs/yguard_ant_howto.html +++ /dev/null @@ -1,3202 +0,0 @@ - - - - yGuard @VERSION_MAJOR@ - Ant Java Bytecode Obfuscator and Shrinker - Documentation - - - - - - - - - - - - - - - -
- -
yGuard
-
-
- -

- This document explains how to use the yGuard Java obfuscation and shrinking - software together with Ant. yGuard - is a product of yWorks GmbH, creator - of - the outstanding JavaTM graph visualization - framework - yFiles and other fine - products. -

- -

yGuard @VERSION_MAJOR@ Ant Task Documentation

- -

Contents

- -
- -
- - - -

Introduction

- -
-

- Using the yGuard Ant task, name obfuscation and code shrinking can be - seamlessly integrated into your deployment - process.
- The yguard task - contains two nested elements that perform the name obfuscation - and code shrinking separately: -

-
    -
  • The shrink element - removes all code elements that are not reachable from - the entrypoints given in the nested - keep element. -
    • -
  • The rename element - performs name-obfuscation, renaming all packages, - classes, methods and fields according to a selectable name-mapping - scheme.
    - Elements can be excluded from the renaming process by annotating them - with a certain annotation class in the source code or using - a nested keep element. -
    • -
-

- Both elements operate on the same set of input and output files - specified in the containing - yguard element. -

-
- - - -

Installation

- -
-

- In order to make use of yGuard's yguard task - you must have Ant properly installed and configured to run it. After - downloading - and extracting the jar files (yguard.jar, retroguard.jar, asm-7.2.jar, guava-28.1-android.jar, failureaccess-1.0.1.jar), place it in a path - near to your build script. You may use absolute paths, but in the following - example, we expect the jar file to lie in the same directory as your build - file. -

- -

- In order the get the Ant task running you should insert a couple of lines - in your build script (build.xml): -

- - 
<target name="yguard">
-  <taskdef name="yguard"
-  classname="com.yworks.yguard.YGuardTask"
-  classpath="yguard.jar"/>
-  <yguard>
-    <!-- insert your yguard elements here -->
-  </yguard>
-</target>
- -

- For a complete build.xml file have a look at the - examples section. -

-
- - - -

General Hints & Troubleshooting

- -
-

- There are a couple of things you should be aware of when obfuscating and - shrinking software. -
- The weakest part of an application considering name obfuscation and code - shrinking is code that uses reflection to dynamically load classes, invoke - methods etc. Therefore, you have to be especially careful when using the - yguard task on applications that rely on - reflection. -
- The most important facts to keep in mind when using yGuard are described - here briefly: -

-
    -
  • If you use the rename task, code in the - form of MyApplication.class will break - if MyApplication will be obfuscated by name - and the obfuscation switch - replaceClassNameStrings - is set tofalse. - The shrink task will currently recognize - code in the form of MyApplication.class only if - the java files - were compiled using an arbitrary version of the standard javac compiler - (although the shrinking engine might - recognize the .class construct also if the classes were - compiled using a compiler that generates - similar bytecode). -
    • -
  • Automatic introspection and reflection will break in most cases, when - you decide to obfuscate the corresponding methods and fields. If you use - the shrink task and your - application uses - reflection you should explicitly designate all entities loaded per - reflection as code entrypoints using the - keep element. -
    - If your application is broken after using the - shrinktask, consider using the - createStubs - attribute of the shrink task to find out - which additional entities you - need to include in the keep - element. -
    • -
  • Class.forName(className) will not work when using the - rename task unless you use the - obfuscated name string in your variable or the String is a local - constant and - replaceClassNameStrings - is not set or set to true. - If you use the shrink task, - className should be contained in the list of entrypoints - using - the keep element. -
  • The customized serialization mechanism will not work if you - obfuscated or shrinked the writeObject and readObject methods as well as - the serializationUID field. -
    • -
  • Simple bean introspection will not work, if you decide to - obfuscate your public accessor methods, since it makes use of - reflection. -
    • -
  • - If you do not set the -Xmx property for the Java virtual - machine, the yguard Ant task - might fail due to a java.lang.OutOfMemoryError.
    - To solve this problem, set the -Xmx option in the ANT_OPTS - variable, e.g.: - 
    bash> export ANT_OPTS="-Xmx512M"
-or
-cshell> setenv ANT_OPTS "-Xmx512M"
    -
    • -
-
- - - -

The yguard Element

- -
-

- The yguard task contains elements that define - basic properties common to the nested - rename and - shrink tasks.
- Please see the General Hints & Troubleshooting - section to learn about common pitfalls when using name obfuscation and - shrinking software. -

- -
-

Attributes

-

- The yguard element has no attributes. -

-
- -
-

Child Elements

- -
-
- - - -

The inoutpair Elements

- -
-

- At least one inoutpair element or one - non-empty inoutpairs element has to be - specified in order to run the yguard tasks. This element specifies the - paths to the input and output jar files. -

- -
-

Attributes

- - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
in - Specifies an exisiting jar file, which contains the unshrinked and - unobfuscated .class files. - Yes
out - Specifies a path to a jar file which will be created and used to - put the results of the shrinking and obfuscation process. - Yes
resources - Will only be considered if the - yguard element - contains a nested - shrink element. -
- Determines how the shrinking engine handles all non-.class files. -
- Currently the following three resource policies are supported: -
    -
  • copy
    - the default, simply copies all resource files to the output jar. -
    • -
  • auto
    - copies only those resource files that reside in a directory that - still contains one or more .class files after shrinking. -
    • -
  • none
    - discards all resource files. -
    • -
- 		- No, defaults to copy. -
-
- -
-

Child Elements

-

- The inoutpair element has no child elements. -

-
- -

- If multiple jar files need to be obfuscated at once the - inoutpairs element can be used alternatively. -

-
- - - -

The inoutpairs Elements

- -
-

- Additionally or alternatively to inoutpair - elements this element can be specified in order - to specify the paths to the input and output jar files. -

- -
-

Attributes

- - - - - - - - - - - - - - -
AttributeDescriptionRequired
resources - Will only be considered if the - yguard element - contains a nested - shrink element. -
- Determines how the shrinking engine handles all non-.class files. -
- Currently the following three resource policies are supported: -
    -
  • copy
    - the default, simply copies all resource files to the output jar. -
    • -
  • auto
    - copies only those resource files that reside in a directory that - still contains one or more .class files after shrinking. -
    • -
  • none
    - discards all resource files. -
    • -
- 		- No, defaults to copy. -
-
- -
-

Child Elements

-
    -
  • patternset
    • -
  • - optionally a - mapper - that determines the name mapping between the unobfuscated and obfuscated - versions of the jar files. - Note that identitymapper and - mergemapper are not supported. All matched - jar file names need to be mapped to exactly one jar file name - that differs from the original jar file. -
    • -
-
- -
-

Some examples:

- 
<!-- use all jars in the input-lib-dir directory and obfuscate them to *_obf.jar -->
-<inoutpairs resources="auto">
-  <fileset dir="${input-lib-dir}">
-    <include name="myapp*.jar"/>
-    <exclude name="*_obf.jar"/>
-  </fileset>
-  <mapper type="glob" from="*.jar" to="*_obf.jar"/>
-</inoutpairs>
-
-<!-- the above mapper is the default one so the following snippet does the same -->
-<inoutpairs resources="auto">
-  <fileset dir="${input-lib-dir}">
-    <include name="myapp*.jar"/>
-    <exclude name="*_obf.jar"/>
-  </fileset>
-</inoutpairs>
-
-
- - - -

The externalclasses Element

- -
-

- If the jar to be processed by yGuard depends on external classes or - libraries, this - element can be used to specify classpaths to these entities. - These libraries will neither be shrinked nor obfuscated. Use the - inoutpair element for this purpose! - See example 4 later in this document for - an example of when to use this - element.
- In order to achieve a maximum shrinking effect by the - shrink task, all external dependencies should - be declared in the externalclasses element. - Otherwise, all non-private methods of classes - that inherit from unresolvable classes will not be shrinked. -

- -

- The elements attributes and child elements can be seen on the - Ant documentation page about using path elements. -

-
- - - -

The attribute Element

- -
-

- Using the attribute element, you can specify - which attributes present in the input - classes should be kept in the obfuscated output classes.
- See example 6 later in this document for an - example of when to use this - element.
-

- -
-

Attributes

- - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
nameA comma-separated list of attribute names that are to - be retained in the shrinked and/or - obfuscated class - files. - Yes
-
- -
-

Child Elements

- -
- -
-

- An example: -

- 
<attribute name="SourceFile, LineNumberTable, LocalVariableTable">
-  <patternset>
-    <include name="com.mycompany.mylibrary.**"/>
-  </patternset>
-</attribute>
- -

- This will retain the attributes named "SourceFile", - "LineNumberTable", and "LocalVariableTable" - effectively enabling debugging information for all classes in the - com.mycompany.mylibaray package and subpackages. -

-
-
- - - -

The shrink Element

- -
-

- The shrink task removes all classes, fields - and methods that are not reachable from a number of entrypoints given by - a nested keep element. -
- See the Complete Examples section for explanation - of some common use cases. - If your code uses reflection, please read the - General Hints & Troubleshooting - section for information on this topic. -

- -
-

Attributes

- - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
logfileDetermines the name of the logfile that is generated - during the shrinking process. The logfile contains information about - the entrypoints the shrinking engine uses, the removed classes, - methods and fields as well as any warnings. -
- If the name ends with a ".gz", yGuard will automatically create a - gzipped version of the file which potentially saves a lot of disc - space. - 		- No, defaults toyshrinklog.xml -
- createStubs - - Instead of removing methods completely, this attribute causes the - shrink task to insert a method - stub that throws a java.lang.InternalError if it is - called. This attribute is very useful if the shrinking process - causes your application to break and you are uncertain about which - additional code entities you have to include in the - keepelement.
- Note that classes considered as completely obsolete by the shrinking - engine are still removed completely - this attribute only - affects obsolete methods of non-obsolete classes. - 		- No, defaults to false -
-
- -
-

Child Elements

- -
-
- - - -

The entrypointjar Element

- -
-

- The entrypointjar element can be used for - convenience if your application uses libraries that are to be shrinked, - but the jarfile using these libraries should be left untouched by the - shrinking engine. Such a jarfile could be specified as an - entrypointjar.
-

- -
-

Attributes

- - - - - - - - - - - - - -
AttributeDescriptionRequired
namePath to to the jar file to use as entrypointjar. - Yes
-
- -
-

Child Elements

-

- The entrypointjar element has no child - elements. -

-
- -
-

Example

- 
<yguard>
-  <inoutpair in="lib-in.jar" out="lib-out.jar" />
-  <shrink>
-    <entrypointjar name="myApp.jar"/>
-  </shrink>
-</yguard>
-
-
- - - -

The rename Element

- -
-

- The basic idea is, that all elements will be renamed by this task. There - are different use cases, where you sometimes want to exclude or simply - just have to exclude some elements from name obfuscation, i.e. not - rename them but keep in the API as is. See the - Complete Examples section for explanation - of some common use cases. - If your code uses reflection, please read the - General Hints & Troubleshooting - section for information on this topic. - Excluding elements can be achieved by using the - keep element, the - mainclass attribute of the - rename element and by annotating elements in - the source code with the annotation that is specified in the - annotationClass attribute of the - rename element. - Using the nested keep - element, you have to specify all classes, methods, fields, and attributes - that should be excluded from name obfuscation. - Another way is to annotate the elements directly in - the source code that should be obfuscated or excluded. You can use the - yFiles obfuscation annotation - com.yworks.util.annotation.Obfuscation for that or specify - your own annotation in the - annotationClass - attribute of this element. -

- -
-

Attributes

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
mainclassCan be used as a shortcut to specify the mainclass - of your application. Both the class name and the main method will be - excluded from name obfuscation. - Alternatively you may want to consider to exclude the main method - only. If your jar contains a Main-Class attribute, the - rename task will automatically adjust - the value to the obfuscated - name. - No
logfileDetermines the name of the logfile that is generated - during the renaming process. The logfile contains information about - the mappings the name obfuscator generates as well as any warnings. -
- If the name ends with a ".gz", yGuard will automatically create a - gzipped version of the file which potentially saves a lot of disc - space. - 		- No, defaults toyguardlog.xml
conservemanifest - A boolean attribute (valid values: - true/false) that determines whether the - manifest file of the jars should be left untouched by the renaming - engine. If set to false, the manifest will be modified - to reflect the new message digests. - - No, defaults to false. -
- replaceClassNameStrings - - A boolean attribute (valid values: - true/false) that determines whether the - renaming engine should try to replace hardcoded Strings, which - are used in conjunction with the MyClass.class - construct. - If set to false, those Strings will be left untouched - and code of the form MyClass.class will break if - MyClass gets obfuscated by name. If set to true (the - default), yGuard will try to workaround this problem by replacing - the hardcoded String with the appropriate obfuscated name. However - this will only work if the unobfuscated class file has been - generated with the usual compilers ('javac', 'jikes' and 'bjc') or - compilers, that produce similar bytecode. This can also have the - side-effect of modifying too many Strings, e.g if you have code that - looks likeSystem.out.println("com.mycompany.MyClass");, - it might get replaced, if MyClass.class resides in the - very same class with something like - System.out.println("com.A.OoO");. It will most likely - fail if the class has been previously obfuscated by another - obfuscation tool or a different compiler has been used for - compilation. Anyway it is always worth it to give it a try, if you - want to have 'full obfuscation'. - - No, defaults to true -
annotationClass - Specifies the name of the annotation class that can be used to - exclude elements by annotating them in the source code. The - specified annotation can be any annotation that fits the convention. - - No, defaults to com.yworks.util.annotation.Obfuscation -
-
- -
-

Child Elements

- -
-
- - - -

The property Elements

- -
-

- property elements can be used to give hints - to the name obfuscation engine. Depending on the exact version of yGuard, - the task may use these hints to control the process of obfuscation. -

- -
-

Attributes

- - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
name - Specifies a key which may be interpreted by the obfuscation task. - Yes
value - Specifies the corresponding value of the property. - Yes
-
- -
-

The following properties are supported:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameDescription
error-checking - Can be used to tell yGuard to bail out if it detects any problems. - Currently this property can be set to the following value: -
    -
  • - pedantic
    - Will make the obfuscation run fail, i.e. the target which uses - the renameelement will fail, if - yGuard detects any problems. -
    • -
-
naming-scheme - Can be used to tell the renaming engine to use a different naming - scheme during the obfuscation. - Currently this property can be set to one of the following values: -
    -
  • - small
    - Will produce very short names, i.e. the resulting jar - file will be as small as possible. -
    • -
  • - best
    - Will produce names, that are very likely to be misunderstood by - decompilers and disassemblers. Using this naming-scheme it is - even impossible on most filesystems to successfully unjar or - unzip the resulting jar file (Windows, Standard Unix, Standard - Linux, MacOS). - However this scheme takes up a lot of space and the resulting - jar is likely to become large (typically roughly double the - size). -
    • -
  • - mix
    - Is a mixture of both the other two values, which leads to - reasonable small but still hard to decompile jar files. -
    • -
-
language-conformity - Can be used to advise the renaming engine to produce names, that - should be decompilable by most decompilers. On the other hand, - yGuard can produce class files that should be executable and - verifiable by all of todays virtual machines, but produces - absolutely nonsense names when decompiled (Ever tried to compile - 'int class = false.this super(String$super.init if);' - ?!) - Currently this property can be set to one of the following values: -
    -
  • - compatible
    - Will produce names, that are ok for (most) decompilers, java, - jar and manifest files and can be unzipped to most filesystems. -
    • -
  • - legal
    - Will produce names, that are ok for (some) decompilers, java, - jar and manifest files. -
    • -
  • - illegal
    - Will produce names, that will crash some tools but usually - not the jvm, but JBuilder7 in many occasions for example. -
    • -
-
overload-enabled - Determines whether the renaming engine tries to use the same names - for methods with different signatures or whether it always generates - unique method names. - Setting this property to false eases the analysis of - stacktraces but reduces the obfuscation effect. -
obfuscation-prefix - Can be used to instruct the renaming engine to prefix packages, that - are fully obfuscated with a given package prefix, e.g. - com.mycompany.obf. -
digests - Can be used to tell yGuard which digest algorithms should be used - for the digest generation in the manifest file. Valid values are - either none, or a comma-separated - list of digest-algorithm identifiers, e.g. - SHA-1, MD5 (which is the default). -
expose-attributes - Can be used to give yGuard a list of attributes yGuard should expose - in addition to the standard attributes. - By default yGuard removes unneeded attributes like "Deprecated" from - methods. The value can be a comma separated list of attributes as - defined in - Section 4.7 of the VM Specification of the .class File Format. - E.g. in order to keep the "Deprecated" attribute one can add the - following property: -
- <property name="expose-attributes" value="Deprecated"/> -
- Note that this affects all classes which will be obfuscated. For a - better control of which attributes should be exposed in what classes - use the Attribute Element. -
-
- - -
-

Child Elements

-

- The property element has no child elements. -

-
-
- - - -

The keep Element

- -
-

- This element is a child of the rename - or shrink element. - It can be used to specify elements that are excluded from the parent - rename or shrink - task. The excluded classes, methods and fields are defined using nested - package, - class, - method and - field elements. -
- The elements given in the keep element are - considered as code entrypoints. All code reachable from these entrypoints - will be implicitly excluded from - shrinking, too. -

- -
-

Attributes

- -

- The keep element provides a number of - boolean attributes that determine whether debug information and - annotations present in the input class files are to be retained in the - output files. The default behavior of the - rename and - shrink elements for the respective - attributes is explained in the table below. -
- Note that a more fine-grained control over which attributes to keep for - which class files is possible using the - attribute element. - Also, the attribute element allows to - define attributes to keep for both the - rename and the - shrinkelement in a common place. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionDefault (rename)Default (shrink)
sourcefile - Determines whether the name of the original source code file should - be included in the output class files. - removeremove
linenumbertable - Determines whether the line number table, that contains a mapping - from each opcode in the class file to the line number in the - original source code file should be included in the output class - files. - remove remove
localvariabletable - Determines whether the local variable table, that contains a mapping - from each local variable in the class file to the name that has been - used in the original source code file should be included in the - output class files. - remove remove
localvariabletypetable - Determines whether the local variable type table, that contains a - mapping from each local variable in the class file to the name and - its generic type signature that has been used in the original source - code file should be included in the output class files. - remove remove
runtimevisibleannotations - Determines whether annotations with the retention policy - RetentionPolicy.RUNTIMEshould be included in the output - class files. - keep keep
runtimevisibleparameterannotations - Determines whether method paramater annotations with the retention - policy RetentionPolicy.RUNTIME should be included in - the output class files. - keep keep
runtimeinvisibleannotations - Determines whether annotations with the retention policy - RetentionPolicy.CLASSshould be included in the output - class files. - keep remove
runtimeinvisibleparameterannotations - - Determines whether method paramater annotations with the retention - policy RetentionPolicy.CLASS should be included in the - output class files. - keep remove
-
- - -
-

Common Child Elements

- - -

- Child Elements only available in the - rename task -

-

- The rename task - allows for a special treatment of the - linenumbertable and - sourcefile attributes. - This treatment can be specified in the following child elements: -

- -
-
- - - -

The class Element

- -
-

- The class element can be used for excluding - certain classes and/or their fields and methods from the renaming or - shrinking process. -
- If no - name, - extends or - implements - attribute is given and the - class element contains no nested - patternset, a - class element matches all class names. -

- -

- The - classes, - methods and - fields - attributes tell the shrinking and renaming engines which classes, methods - and fields to keep based on their visibility. - The following table lists the possible values for all of these attributes - and shows which elements will be excluded. A '*' denotes, that elements - that have the given visibility will be excluded for the specified - attribute value. A '-' denotes that the these elements will not be - excluded from the process. -

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Value/Visibilitypublicprotectedfriendlyprivate
none----
public*---
protected**--
friendly***-
private****
-
- -
-

Attributes

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
nameThe name of the class to be kept.No
classesThe visibility of the classes to be kept. - No, defaults to none
methodsThe visibility of the methods to be kept. - No, defaults to none
fieldsThe visibility of the fields to be kept. - No, defaults to none
extends - If no name attribute is given, keeps - all classes that equal or extend the class defined by the given - fully qualified classname. -
- See example 7 for an example usage of this - attribute. - 		No
implements - If no name attribute is given, keeps - all classes that equal or implement the class defined by the given - fully qualified classname. -
- See example 7 for an example usage of this - attribute. - 		No
-
- -
-

Child Elements

- -
- -
-

Explanation

-

- There are three possible ways of specifying which classes will be excluded - from the shrinking and obfuscation process: -

- -
    -
  1. One can specify a single java class using the fully qualified name - in java syntax with the name attribute. - For example: - 
    <class name="mypackage.MyClass"/>
    -
    2. -
  2. One can specify multiple java classes using a modified version of - a patternset. The patternset's includes and excludes element should - use java syntax, but the usual wildcards are allowed. - Some examples: - 
    <class>
-  <patternset>
-    <include name="com.mycompany.**.*Bean"/>
-    <exclude name="com.mycompany.secretpackage.*"/>
-    <exclude name="com.mycompany.myapp.SecretBean"/>
-  </patternset>
-</class>
    - This will expose all classes which reside in the package subtree - of com.mycompany and whose name ends with Bean except - for those, that reside in the com.mycompany.secretpackage - package and the single SecretBean in - com.mycompany.myapp. - 
    <class>
-  <patternset>
-    <include name="com.mycompany.myapp.MainClass"/>
-    <include name="org.w3c.sax?."/>
-    <exclude name="org.w3c.sax?.**.*$$*"/>
-  </patternset>
-</class>
    - This will expose the MainClass class - and all classes, which reside in packages like - org.w3c.sax1, - org.w3c.sax2, - org.w3c.saxb - except for inner classes. - '$' is used as a separator between outer class names - and inner class names. Since Ant uses '$' as an escape character, you - have to use two consecutive '$'s ('$$') if - you want to pass one as an argument to the task. -
    3. -
  3. - Finally one can specify classes depending on their visibility, i.e. - depending whether they have been declared - public, - protected, - package-private or - private (inner classes). - This can be achieved by additionally specifying the - classes attribute in the - class element. - 
    <class classes="protected">
-  <patternset>
-    <include name="com.mycompany.myapi."/>
-  </patternset>
-</class>
    - This will keep all class names, that are either - public or - protected and - which reside in one of the subpackages of - com.mycompany.myapi - (note the abbreviation: the trailing dot behaves like the trailing - '/' in the usual patternset, i.e. it could - be rewritten as com.mycompany.myapi.**.*) - 
    <class classes="protected"
-  methods="protected"
-  fields="protected">
-  <patternset>
-    <include name="**.*"/>
-  </patternset>
-</class>
    - This example shows the very common use case of excluding a complete - public API from the shrinking and obfuscation process. - There is an abbreviation for this use case: you can omit the - patternset element, since in the case - where the classes attribute is - specified and there is no patternset - child element used, the task will automatically apply this rule. - In this example all classes will be exposed, that are either - public or - protected. - Their methods and fields will be exposed as long as they are declared - public or - protected. - If a class is package-private or - private (inner classes), neither itself - nor its methods or fields will be exposed. -

    - The last example shows how to keep the - public methods of certain classes only, - but neither field names nor the class names themselves. - 

    <class classes="none" methods="public" fields="none">
-  <patternset>
-    <include name="com.mycompany.myapi."/>
-  </patternset>
-</class>
    -
    4. -
-
-
- - - -

The method Element

- -
-

- Using the method element you can specify - methods by signature which should be excluded from shrinking or name obfuscation. -

- -
-

Attributes

- - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
name - Specifies the method to keep. Use the complete signature using - fully qualified class names and the return type! - Yes
class - Specifies the class which contains the method. Use the normal java - syntax, i.e. the fully qualified name. - This attribute can be omitted, if the patternset element is used as - a child element, in which case all classes matching the patternset - will be searched and their corresponding methods will be kept. - No
-
- -
-

Child Elements

- -
- -
-

Examples

- 
<method class="com.mycompany.myapp.MyClass"
-  name="void main(java.lang.String[])"/>
-<method class="com.mycompany.myapp.MyClass"
-  name="int foo(double[][], java.lang.Object)"/>
-<method name="void writeObject(java.io.ObjectOutputStream)">
-  <patternset>
-    <include name="com.mycompany.myapp.data.*"/>
-  </patternset>
-</method>
-<method name="void readObject(java.io.ObjectInputStream)">
-  <patternset>
-    <include name="com.mycompany.myapp.data.*"/>
-  </patternset>
-</method>
-

- This will keep the main method of the MyClass class and the - foo method. - Additionally all readObject and writeObject - methods (used for serialization) will be kept in all classes of the - com.mycompany.myapp.data package. - Note that you have to specify the return argument's type, even if it is - void and that you have to use the fully - qualified name for all classes, even those, that are in the - java.lang package. -

-
-
- - - -

The field Element

- -
-

- Using the field element you can specify - fields by name which should be excluded from shrinking or name - obfuscation. -

- -
-

Attributes

- - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
name - Specifies the field to keep. - Use the name of the field only, do not include its type! - Yes
class - Specifies the class which contains the field. - Use the normal java syntax, i.e. the fully qualified name. - This attribute can be omitted, if the - patternset element is used as - a child element, in which case the all classes matching the - patternset will be searched and their corresponding fields will be - kept. - No
-
- -
-

Child Elements

- -
- -
-

Examples

- 
<field class="com.mycompany.myapp.MyClass" name="field"/>
-<field name="serialVersionUID">
-  <patternset>
-    <include name="com.mycompany.myapp.data.*"/>
-  </patternset>
-</field>
-

- This will keep the field named field of the - MyClass class. - Additionally all the serialVersionUID fields (used for serialization) - will be kept in all classes of the com.mycompany.myapp.data - package. -

-
-
- - - -

The package Element

- -
-

- The package element can be used for excluding - certain package's names from the renaming process. It cannot be used for - the shrinking process. -
- All packages that are matched be the nested - patternset - element will not be obfuscated. This has no influence on the class, - method, or field names but will only result in the package's name not - being obfuscated. - Normally, it is not necessary to use this element, instead the - class element is used - to keep class names (and thus their package names) from being obfuscated. -

- -
-

Child Elements

- -
- -
-

Examples

- 
<package>
-  <patternset>
-    <include name="com.mycompany.myapp.*"/>
-  </patternset>
-</package>
-

- This will keep the names of all packages that are direct descendants - of com.mycompany.myapp. This will not influence the names - of the classes contained in these packages. -

-
-
- - - -

The sourcefile Element

- -
-

- The sourcefile element allows for a special - treatment of the sourceFile attribute by - the rename element. -
- Using nested property elements, the mapping - of sourceFile attributes in obfuscated - class files can be adjusted. -

- -
-

The following properties are supported:

- - - - - - - - - - - - - - -
NameDescription
mapping - The value of this property determines the name all - sourceFile attributes matched by the - sourcefile element are mapped to. -
-
- -
-

Child Elements

- -
- -
-

Examples

- 
<sourcefile>
-  <property name="mapping" value="y"/>
-  <patternset>
-    <include name="com.mycompany.myapp.**"/>
-  </patternset>
-</sourcefile>
-

- This will map all of the sourceFile - attributes in the packages below com.mycompany.myapp to - "y", which is small and generally a nice letter. -

-
-
- - - -

The linenumbertable Element

- -
-

- The linenumbertable element allows for a - special treatment of the linenumbertable - attribute by the rename - element. -
- Using nested property elements, the mapping - of linenumbertable attributes in obfuscated - class files can be adjusted. -

- -
-

The following properties are supported:

- - - - - - - - - - - - - - - - - - -
NameDescription
mapping-scheme - Can be used with the following two values: -
    -
  • - scramble
    - This will use a non-trivial algorithm to scramble the line - numbers in the existing file. - The algorithm implemented uses a different scrambling scheme for - each class. The optional - scrambling-salt property can be - used to provide an integer value that will be used to "salt" - the algorithm's random seed for the scrambling. - The size of the (uncompressed) .class file will not change using - this mapping scheme. -
    • -
  • - squeeze
    - This will use a simple algorithm that virtually puts all of a - method's code into the first line of code of the method. It will - appear as if each method had been written in a single line of - code. - The advantage of this scheme is drastically reduced size - requirements and thus smaller .class files, while at the same - time it will be possible to unambiguously determine the exact - method from a stacktrace. -
    • -
-
scrambling-salt - Can be used in conjunction with - mapping-scheme to provide an integer - value that will be used to "salt" the algorithm's random seed for - the scrambling. -
-
- -
-

Child Elements

-
    -
  • property
    • -
  • patternset
    • -
-
- -
-

Examples

- 
<linenumbertable>
-  <patternset>
-    <include name="com.mycompany.myapp.**"/>
-  </patternset>
-</linenumbertable>
-

- This will keep the line numbers of all the classes in the - com.mycompany.myapp packages and subpackages. - Note that in order to see the line numbers in stacktraces, the - sourcefile - attribute has to be retained for those files, too, since otherwise the - JDK will display "Unknown source" for the stack elements. -

- - 
<linenumbertable>
-  <property name="mapping-scheme" value="scramble"/>
-  <property name="scrambling-salt" value="1234"/>
-  <patternset id="CompanyPatternSet">
-    <include name="com.mycompany.myapp.**"/>
-  </patternset>
-</linenumbertable>
-<sourcefile>
-  <property name="mapping" value="y"/>
-  <patternset refid="CompanyPatternSet"/>
-</sourcefile>
-

- This will keep scrambled line numbers for all classes found in and below - the com.mycompany.myapp packages. - The scrambling algorithm will use the given "salt" value to use a - predefined scrambling scheme. - In order to see the scrambled line numbers, a - sourcefile - element is used on the same patternset, which is referenced by its - previously declared reference id, to rename the source files to - "y". -

-
-
- - - -

The adjust Element

- -
-

- Using the adjust element one can specify - resource files whose names and/or contents should be adjusted by the - rename engine to reflect the obfuscated class names. -
- Note: - This will only adjust files that are part of the - inoutpair jars! I.e. the fileset's root - directory is the combined root of all jars that are passed to yGuard via - the inoutpair elements. yGuard will not - modify any of the files on disk, except for the out-jar! -

- -
-

Attributes

- - - - - - - - - - - - - - - - - - - - - - - - -
AttributeDescriptionRequired
replaceName - Specifies whether or not the names of the specified resources should - be adjusted. - No, defaults to false -
replaceContent - Specifies whether or not the contents of resource files should be - adjusted. - No, defaults to false -
replacePath - Specifies whether or not the paths to the resource files should be - adjusted. - No, defaults to true
-
- -
-

Child Elements

-

- The adjust element can be used just like the - standard Ant - ZipFileSet - element. -

-
- -
-

- Some examples: -

- 
<!-- adjust the names of all java property files in the jars -->
-<adjust replaceName="true">
-  <include name="**/*.properties"/>
-</adjust>
-
-<!-- adjust the classnames specified within a single XML file in the jar -->
-<adjust file="plugins.xml" replaceContent="true" />
-
-<!-- suppress the adjustment of the resource path
-com/mycompany/myapp/resource in the jar. -->
-<!-- the package com.mycompany.myapp still gets obfuscated. -->
-<adjust replacePath="false">
-  <include name="com/mycompany/myapp/resource/*"/>
-</adjust>
-
-
- - - -

The map Element

- -
-

- The map element is an immediate optional - child of the rename - element. It can be used to specify the mapping for the renaming process - directly. This is an advanced topic. -

- -
-

Child Elements

-
    -
  • package
    • -
  • class
    • -
  • method
    • -
  • field
    • -
- -

- All of these elements use the name - attribute to specify the specific element. The - method and - field elements need the - class attribute in order to function - properly. - Neither wildcards nor nested patternset - elements are allowed. - Use the map attribute to specify the new - name (subpackage, classname, methodname and fieldname respectively). -

-
- -
-

- Some examples: -

- - 
<map>
-  <package name="com" map="etc"/>
-  <package name="com.mycompany" map="nocompany"/>
-  <package name="com.mycompany.myapp" map="asdf"/>
-  <class name="com.mycompany.myapp.MainApp" map="foo"/>
-  <method class="com.mycompany.myapp.MainApp"
-    name="void main(java.lang.String[])" map="bar"/>
-  <field class="com.mycompany.myapp.MainApp" name="field" map="a"/>
-</map>
-

- In this example the package structure com.mycompany.myapp - will be obfuscated to etc.nocompany.asdf. - The MainApp class will be called foo and its - main method will be remapped to bar (and can - therefor not be executed from commandline anymore). - The field called field will be renamed to a. -

-
-
- - - -

Controlling obfuscation exclusion with annotations

- -
-

- In order to exclude certain elements from obfuscation, it is possible to - use annotations in the source code instead of listing those elements in - the keep element. -

-

- Any annotation class can be used for this, but it must be specified in the - annotationClass - attribute of the rename - element and follow the convention as explained below to work. - yGuard contains such an annotation in the distribution package ready for - use. The annotation class is - com.yworks.util.annotation.Obfuscation and can be found in - the yGuard distribution in thelib/ObfuscationAnnotation.jar. - Feel free add this attribute definition to your own codebase and possibly - adjust the package name to your needs. Here is the source code for it: -

- -

Obfuscation.java

- 
package com.yworks.util.annotation;
-
-public @interface Obfuscation {
-
-  boolean exclude() default true;
-
-  boolean applyToMembers() default true;
-}
-
- -

- This class is also the default annotation yGuard is looking for when - obfuscating. -

-

- The convention for annotation classes that yGuard understands as - obfuscation controlling annotations requires two attributes: -

- -
-

Attributes

- - - - - - - - - - - - - - - - - - - -
AttributeDescriptionDefault value
exclude - Specifies whether the annotated element should be excluded from the - obfuscation. Note, that when retaining a class, the hierarchy of - that class, i.e. the chain of outer class names and the package - name, is also retained. - true
applyToMembers - Specifies whether the child elements of the annotated element, if - not otherwise specified, should be excluded from the obfuscation. - For example, when annotating a class with - exclude = true and this attribute set to - true, inner classes, fields and methods of this - class will be excluded from obfuscation. Annotating a child element - of an element that has this attribute set to true will - override the parents annotation configuration. - true
-
-
- - - -

Generating Patch Jars

- -
-

- The true power of the map element lies in its - use together with the patch element, which - itself is a child element of the rename top - level element. -

- -
-

Attributes

-

- The patch element has no attributes. -

-
- -
-

Child Elements

- -
- -

- Using the patch element one can generate - jars, that can be used to serve as patches for versions of an application - that have already been deployed in obfuscated form. - During the main obfuscation run, yGuard produces an xml-logfile, in which - the mapping between the unobfuscated and obfuscated names is contained. - The patch element is used to declare a set of - classes, that need to be patched. During the obfuscation, yGuard will - include those files in the obfuscated jars only, that are declared inside - this element. -

- -
-

- For example: -

- - 
<patch>
-  <class name="com.mycompany.myapp.MainClass"/>
-  <class>
-    <patternset>
-      <include name="com.mycompany.myapp.bugs.*"/>
-    </patternset>
-  </class>
-</patch>
-<map logfile="yguardlog.xml"/>
-

- This will only include the MainClass class and all classes that belong - to the bugs package in a patch jar. - In order to work with the previously delivered obfuscated version, it is - important to use the map element to specify - the mapping of the elements from the previous run. - This can most conveniently be achieved by specifying the log file from - the corresponding run in the map element's - logfile attribute. -

-
-
- - - -

Complete Examples

- -
-

- Examples that represent common use cases. -

- - -

Example 1: Getting started with Ant and yGuard (for Ant newbies)

- -

- Following are the contents of a complete build.xml file. - Just copy the following lines to a new document named - build.xml, put the file into your project's root directory - and edit the file to suit your needs. -

- - 
<?xml version="1.0" encoding="UTF-8"?>
-<!-- file build.xml in your project root directory -->
-<!-- Ant build script for yfiles -->
-<!-- The java based Ant tool is available from -->
-<!-- http://jakarta.apache.org/ant -->
-<!-- This file demonstrates the use of the yGuard byte -->
-<!-- code obfuscator from yWorks Gmbh -->
-<!-- yGuard can be downloaded from -->
-<!--- https://www.yworks.com/products/yguard -->
-
-<project name="project" default="yguard" basedir=".">
-
-  <!-- edit the following lines to your needs -->
-  <target name="init">
-  <property name="project_name" value="DemoProject"/>
-  <property name="srcDir" value="."/>
-  <property name="classDir" value="classes"/>
-  <property name="jar" value="${project_name}.jar"/>
-  <property name="obfjar" value="${project_name}_obf.jar"/>
-  <property name="renamelog" value="${project_name}_renamelog.xml"/>
-  <property name="shrinklog" value="${project_name}_shrinklog.xml"/>
-  <property name="mainclass" value="com.mycompany.myapp.Main"/>
-  <mkdir dir="${classDir}" />
-  </target>
-
-
-  <target depends="jar" name="yguard">
-    <taskdef name="yguard" classname="com.yworks.yguard.YGuardTask"
-    classpath="yguard.jar"/>
-    <!-- the following can be adjusted to your needs -->
-    <yguard>
-
-      <inoutpair in="${jar}" out="${obfjar}"/>
-
-      <shrink logfile="${shrinklog}">
-
-        <keep>
-          <class classes="protected"
-          methods="protected" fields="protected">
-            <patternset>
-              <include name="com.mycompany.publicapi.**.*"/>
-              <exclude name="com.mycompany.publicapi.private.*"/>
-              <include name="com.mycompany.menu.reflection.**.*"/>
-            </patternset>
-          </class>
-        </keep>
-      </shrink>
-
-      <rename mainclass="${mainclass}" logfile="${renamelog}">
-        <property name="error-checking" value="pedantic"/>
-
-        <keep>
-          <class classes="protected"
-          methods="protected" fields="protected">
-            <patternset>
-              <include name="com.mycompany.publicapi.**.*"/>
-              <exclude name="com.mycompany.publicapi.private.*"/>
-            </patternset>
-          </class>
-        </keep>
-      </rename>
-
-    </yguard>
-
-  </target>
-
-  <!-- compile -->
-  <target name="compile" depends="init">
-    <javac srcdir="${srcDir}" includes="com/mycompany/**/*.java"
-      destdir="${classDir}">
-    </javac>
-  </target>
-
-  <!-- create .jar -->
-  <target name="jar" depends="compile">
-    <jar jarfile="${jar}"
-      basedir="${classDir}"
-      includes="com/mycompany/**">
-      <fileset dir="${srcDir}">
-        <include name="com/mycompany/resources/*.properties"/>
-      </fileset>
-    </jar>
-  </target>
-
-  <!-- run project -->
-  <target name="run" depends="yguard">
-    <java classname="${mainclass}" fork="true">
-    <classpath>
-      <pathelement location="${obfjar}"/>
-    </classpath>
-    </java>
-  </target>
-
-  <!-- removes all that has been built -->
-  <target name="clean" depends="init">
-    <delete dir="${classDir}" includeEmptyDirs="true" />
-  </target>
-</project>
-
-<!-- end file build.xml -->
- - - -

Example 2: A Public API

- -

- An alternative yguard section could look - like this: -

- - 
<yguard>
-
-  <inoutpair in="classes.jar" out="classes_obf.jar"/>
-  <inoutpair in="utils.jar" out="utils_obf.jar"/>
-
-  <!-- don't let the obfuscator remove the "Deprecated" -->
-  <!-- attributes from the .class file entries -->
-  <attribute name="Deprecated"/>
-
-  <shrink
-    logfile="shrinklog.xml">
-    <keep>
-      <class classes="protected"
-      methods="protected"
-      fields="protected"/>
-    </keep>
-  </shrink>
-
-  <rename mainclass="com.mycompany.myapp.Main"
-    logfile="obflog.xml">
-    <keep>
-      <class classes="protected"
-      methods="protected"
-      fields="protected"/>
-    </keep>
-  </rename>
-
-</yguard>
- -

- This case is especially useful when you want to provide and expose a - public API. - All the classes, methods and fields, that can be seen in a javadoc - generated API will be excluded from the shrinking and renaming tasks. - Package friendly and private classes, methods and fields will be shrinked - or obfuscated whenever possible. -
- This example also displays the use of the - attribute element. In this case it prevents - the yguard task from removing the - Deprecated flag from the entities in the - .class files. -

- - - -

Example 3: A Demo Program

- - 
<yguard>
-
-  <inoutpair in="demo.jar" out="demo_obf.jar"/>
-
-  <shrink logfile="shrinklog.xml">
-
-    <keep>
-
-      <!-- main method -->
-      <method name="void main(java.lang.String[])" class="com.mycompany.myapp.Main" />
-
-      <!-- needed for reflection -->
-      <class name="com.mycompany.myapp.data.DataObject"
-      methods="public" fields="none"/>
-      <!-- needed for reflection (name only) -->
-      <class name="com.mycompany.myapp.data.InnerDataObject"/>
-      <!-- needed for serialization -->
-      <method name="void writeObject(java.io.ObjectOutputStream)">
-        <patternset id="datapatternset">
-          <include name="com.mycompany.myapp.data.*"/>
-        </patternset>
-      </method>
-      <method name="void readObject(java.io.ObjectInputStream)">
-        <patternset refid="datapatternset"/>
-      </method>
-      <field name="serialVersionUID">
-        <patternset refid="datapatternset"/>
-      </field>
-    </keep>
-  </shrink>
-
-  <rename mainclass="com.mycompany.myapp.Main" logfile="renamelog.xml">
-
-    <property name="language-conformity" value="illegal"/>
-    <property name="naming-scheme" value="mix"/>
-    <keep>
-      <class name="com.mycompany.myapp.data.DataObject"
-      methods="public" fields="none"/>
-      <class name="com.mycompany.myapp.data.InnerDataObject"/>
-      <method name="void writeObject(java.io.ObjectOutputStream)">
-        <patternset refid="datapatternset" />
-      </method>
-      <method name="void readObject(java.io.ObjectInputStream)">
-        <patternset refid="datapatternset"/>
-      </method>
-      <field name="serialVersionUID">
-        <patternset refid="datapatternset"/>
-      </field>
-    </keep>
-  </rename>
-
-</yguard>
- -

- This example demonstrates the common use case of a demo program. - The keep sections of both the - shrink and - rename elements contain code entities that - will often have to be excluded from the shrinking and renaming process. - These are the main code entrypoints (the main method), - classes that are loaded per reflection and fields and methods needed for - serialization. Note how the same patternsets can be reused using the - id and refid - attributes. -

- - - -

Example 4: A Program Using an External Library

- - 
<yguard>
-
-  <inoutpair in="mydemo.jar" out="mydemo_obf.jar"/>
-
-  <externalclasses>
-    <pathelement location="lib/external.jar"/>
-    <pathelement location="lib/additional/classes/"/>
-  </externalclasses>
-
-  <shrink logfile="shrinklog.xml">
-    <property name="error-checking" value="pedantic"/>
-    <keep>
-      <method name="void main(java.lang.String[])" class="com.mycompany.myapp.Main" />
-      <class classes="public"/>
-    </keep>
-  </shrink>
-
-  <rename mainclass="com.mycompany.myapp.Main" logfile="renamelog.xml">
-    <property name="error-checking" value="pedantic"/>
-    <keep>
-      <class classes="public"/>
-    </keep>
-  </rename>
-
-</yguard>
- -

- This example demonstrates full method and field obfuscation for a program, - that has external dependencies. The dependencies are specified in the - externalclasses element using standard Ant - path specification mechanisms. Classes residing in - lib/external.jar and underneath the - lib/additional/classes/ directory (note the trailing slash), - will be used to resolve external dependencies during the obfuscation run. - This is necessary if external classes want to access obfuscated classes - directly using an externally defined interface or superclass. yGuard - automatically detects externally declared methods and prevents renaming - and shrinking of these items. As a result, the shrinked and obfuscated jar - file can be used together with unmodified versions of external libraries - without causing any problems. -
- This example also demonstrates the use of the - error-checking property. In this case the - Ant target fails if any problem is detected during the obfuscation run. -

- - - -

Example 5: A Program with .properties Files and Other Resource Files

- - 
<yguard>
-
-  <inoutpair in="myapp.jar" out="myapp_obf.jar"/>
-
-  <shrink logfile="shrinklog.xml">
-    <keep>
-      <!-- single entrypoint: main method -->
-      <method name="void main(java.lang.String[])" class="com.mycompany.myapp.Main" />
-    </keep>
-  </shrink>
-
-  <rename mainclass="com.mycompany.myapp.Main" logfile="renamelog.xml">
-
-    <adjust replaceContent="true">
-      <!-- plain-text class names in the config files will -->
-      <!-- be replaced with the obfuscated name versions -->
-      <include name="**/*.config"/>
-      <include name="com/mycompany/myapp/init/Main.properties"/>
-    </adjust>
-    <adjust replacePath="false">
-      <!-- keep the complete path to the resources, (gifs...) even if -->
-      <!-- package com.mycompany.myapp gets obfuscated by name -->
-      <include name="com/mycompany/myapp/resources/*"/>
-    </adjust>
-    <adjust replaceName="true">
-      <!-- Replace the .properties files' names with the obfuscated -->
-      <!-- versions if the corresponding .class files get obfuscated -->
-      <include name="**/*.properties"/>
-      </adjust>
-  </rename>
-
-</yguard>
- -

- This example, too, demonstrates full method and field obfuscation for a - program, that uses .properties files and other resources files. Some - configuration files are used that contain fully qualified classnames for - plugins that are going to be obfuscated. Therefore yGuard is instructed - to automatically replace the plain-text entries in those files with the - obfuscated name versions. -
- Additionally some resources are hardcoded into the classes (image - locations and html files, e.g.). yGuard gets instructed not to move these - resource files even if they reside in a package structure that is - obfuscated. -
- Since the property files have been created with the same name as the - classes that make use of them and they are being loaded using - this.getClass().getName(), yGuard is configured to rename - the .properties files according to the obfuscated names of the - corresponding .class files. -

- - - -

Example 6: A Program Linked Against a Library That Needs to be Obfuscated

- - 
<yguard>
-
-  <inoutpair in="myapp.jar" out="myapp_obf.jar"/>
-  <inoutpair in="lib/thirdpartylib.jar" out="lib/thirdpartylib_obf.jar"/>
-
-  <externalclasses>
-    <pathelement location="lib/external.jar"/>
-  </externalclasses>
-
-  <!-- Keep all of the attributes for debugging, e.g. -->
-  <attribute name="Deprecated, SourceFile, LineNumberTable, LocalVariableTable>
-    <patternset refid="myopenapp"/>
-  </attribute>
-
-  <rename mainclass="org.myorg.myapp.Main" logfile="renamelog.xml">
-
-    <property name="error-checking" value="pedantic"/>
-
-    <keep>
-    <!-- Tell the obfuscator to only adjust my classes -->
-    <!-- to work with the obfuscated 3rd party library -->
-    <!-- but leave them virtually unmodified otherwise -->
-    <!-- The libconnector package however will be -->
-    <!-- obfuscated as much as possible -->
-    <class classes="private" methods="private" fields="private">
-      <patternset id="myopenapp">
-        <include name="org.myorg.myapp.**"/>
-        <exclude name="org.myorg.myapp.mylibconnector.**"/>
-      </patternset>
-    </class>
-
-    </keep>
-  </rename>
-
-</yguard>
- -

- This example demonstrates almost no method, class, and field obfuscation - for a program, that has external dependencies and additionally depends on - a third party library jar which has to be obfuscated before deployment. - Only those parts that actually interface with the third party jar in the - mylibconnector package are being obfuscated. - Nothing in the third party library jar will be exposed in the final - application, everything will be obfuscated and the code in the open - application that makes use of the third party jar will be adjusted. - Note that the public part of the application will still be debuggable - since all of the crucial attributes will be exposed for the open - application part. -
- The dependencies are specified in the - externalclasses element using standard Ant - path specification mechanisms. Classes residing in - lib/external.jarwill be used to resolve external dependencies - during the obfuscation run. This is not strictly necessary in this case - since the public API will be fully exposed, i.e. no methods which have - been declared by interfaces or super class in external classes will be - renamed. -

- - - -

- Example 7: Using the extends and - implements Attributes (Serializable - Exclusion) -

- - 
<yguard>
-
-  <inoutpair in="myapp.jar" out="myapp_obf.jar"/>
-
-  <shrink>
-    <keep>
-      <!-- main method -->
-      <method name="void main(java.lang.String[])" class="org.myorg.myapp.Main" />
-      <!-- serializable classes -->
-      <class implements="java.io.Serializable" classes="private" methods="private" fields="private" />
-      <!-- menu items loaded per reflection -->
-      <class extends="org.myorg.myapp.MyMenuItem" classes="friendly" methods="public" fields="public" />
-    </keep>
-  </shrink>
-
-  <rename mainclass="org.myorg.myapp.Main" logfile="renamelog.xml">
-
-    <keep>
-      <method name="void readObject(java.io.ObjectInputStream)" />
-      <method name="void writeObject(java.io.ObjectOutputStream)" />
-      <field name="serialVersionUID" />
-      <class extends="org.myorg.myapp.MyMenuItem" classes="friendly" methods="public" fields="public" />
-    </keep>
-  </rename>
-
-</yguard>
- -

- This example demonstrates the usage of the new - implements and - extends attributes - of theclass element. - All Serializable classes are excluded from shrinking by using - the implements - attribute of the class - element. - Additionally, all classes that extend the base class for menu items, - org.myorg.myapp.MyMenuItem, are defined as entrypoints for - the shrinking engine using the - extends attribute - of the class element. - The readObject and writeObject methods and the - field serialVersionUID needed for serialization are excluded - from name obfuscation as well. -

- - - -

Example 8: Annotations in Source Code to Control Obfuscation Exclusion

- -

- This section gives examples on how to use annotations to control which - elements should be excluded from the obfuscation process (i.e., keep their - names). The following assumes that there is an annotation class named - com.yworks.util.annotation.Obfuscation in the classpath that - follows the convention as described above. -

- -

Example 8.a: Obfuscation Exclusion per Item

- - 
@com.yworks.util.annotation.Obfuscation( exclude = true, applyToMembers = false)
-public class Person {
-
-  public String name;
-
-  public String occupation;
-
-  @com.yworks.util.annotation.Obfuscation( exclude = true )
-  public int age;
-}
-
- -
-

Obfuscation

- - - - - - - - - - - - - - - - - - - - - - - -
ElementObfuscated?
class PersonNo
field nameYes
field occupationYes
field ageNo
-
- -

- The table above shows the result of the obfuscation of this example. - The Person class is annotated to be excluded from the - obfuscation, but the applyToMembers - attribute is set to false, which means that the child - elements of the class (the String and int - fields) do not inherit this setting from its parent. - The name and occupation fields are not annotated - and do not inherit the annotation configuration from their parent, so they - are obfuscated. Theage field however is also annotated to be - excluded from obfuscation and thus keeps its name. -

- - -

- Example 8.b: Obfuscation Exclusion for Members Using - applyToMembers -

- - 
@com.yworks.util.annotation.Obfuscation( exclude = true, applyToMembers = true)
-public class Person {
-
-  @com.yworks.util.annotation.Obfuscation( exclude = false )
-  public String name;
-
-  public String occupation;
-
-  public int age;
-}
-
- -
-

Obfuscation

- - - - - - - - - - - - - - - - - - - - - - - -
ElementObfuscated?
class PersonNo
field nameYes
field occupationNo
field ageNo
-
- -

- Again, the class Person keeps its name, but the configuration - is inherited by its members, too. The fields occupation and - age have no annotation set and inherit the configuration - of its parent, which is exclude = true, so they keep their - names. The field name however specifies its own annotation - and thus overrides the configuration of its parent and sets its own - exclusion to false, so it is obfuscated. -

- - -

- Example 8.c: Obfuscation Exclusion for Members using - applyToMembers in the Case of Nested - Classes -

- - 
@Obfuscation ( exclude = true, applyToMembers = true )
-public class Person {
-
-  public String name;
-
-  public String occupation;
-
-  public int age;
-
-  @Obfuscation ( exclude = false, applyToMembers = true )
-  class BirthInfo {
-
-    String birthPlace;
-
-    class Date {
-
-      int year;
-
-      int month;
-
-      int day;
-    }
-  }
-}
-
- -
-

Obfuscation

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ElementObfuscated?
class PersonNo
field nameNo
field occupationNo
field ageNo
class BirthInfoYes
field birthPlaceYes
class DateYes
field yearYes
field monthYes
field dayYes
-
- -

- The applyToMembers configuration is also - applicable to inner classes: - In the above example, the top level class Person is annotated - so that itself and all its members should be excluded from obfuscation. - But, the inner class - BirthInfo overrides this configuration by setting - exclude to false for itself - and all of its members. When yGuard has to decide whether to keep or - obfuscate a non-annotated element, then it will look for annotations by - going up the nesting-hierarchy until the top level class is reached or a - parent has the applyToMembers configuration - set to true. In this case, when deciding whether to keep the - inner classDate, yGuard goes up the hierarchy and finds the - annotation atBirthInfo, which is annotated - exclude = false. This results in Date being - obfuscated. The same applies to the members of Date. -

- - -

- Example 8.d: Obfuscation Exclusion Using - applyToMembers in the Case of Nested - Classes II -

- - 
@Obfuscation ( exclude = true, applyToMembers = true )
-public class Person {
-
-  public String name;
-
-  public String occupation;
-
-  public int age;
-
-  @Obfuscation ( exclude = false, applyToMembers = false )
-  class BirthInfo {
-
-    String birthPlace;
-
-    class Date {
-
-      int year;
-
-      int month;
-
-      int day;
-    }
-  }
-}
-
- -
-

Obfuscation

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ElementObfuscated?
class PersonNo
field nameNo
field occupationNo
field ageNo
class BirthInfoNo
field birthPlaceNo
class DateNo
field yearNo
field monthNo
field dayNo
-
- -

- The above example shows almost the same code as in Example 8.c, but this - time the class BirthInfo has the - applyToMembers annotation set to - false. One might expect that, as a result, all members of - BirthInfo are kept and only BirthInfo is - obfuscated, but instead, all elements in this example are kept. - The explanation: when reaching Date, yGuard is looking up its - parent's configuration, BirthInfo, which has - applyToMembers = false. yGuard then proceeds to the next - parent class in the nesting-hierarchy, Person, which has - applyToMembers = true and exclude = true set. - This causes Date to be kept. - But keeping a class also means that its fully qualified name and thus its - nesting-hierarchy needs to be kept. Although the annotation of - BirthInfo does not explicitly retain the the name of the - class, the retention of Date and its nesting-hierarchy causes - BirthInfo to be kept. -

- - -

Example 8.e: Default Behavior

- - 
public class Person {
-
-  public String name;
-
-  public String occupation;
-
-  @com.yworks.util.annotation.Obfuscation
-  public int age;
-
-}
-
- -
-

Obfuscation

- - - - - - - - - - - - - - - - - - - - - - - -
ElementObfuscated?
class PersonYes
field nameYes
field occupationYes
field ageNo
-
- -

- This example shows the default behavior of yGuard without specifying an - annotation and when not assigning the attributes of the annotation. - Person, name and occupation - are obfuscated, while age is annotated. The default value for - exclude is true, so the field - age is not obfuscated. -

- -
- - - -

Deobfuscating Stacktraces Etc.

- -
-

- yGuard provides a simple tool that makes it easy for the obfuscating party - to deobfuscate stacktraces which have been obfuscated using yGuard. - During the obfuscation yGuard produces an xml logfile which can - automatically be gzipped for convenient storage. You should always keep - those logfiles in order to be able to deobfuscate fully qualified - classnames or methods or fields for debugging purposes e.g. -
- In order to run the yGuard deobfuscation tool do the following: -

- 
Console> java -jar yguard.jar mylogfile.xml
-

- A tiny GUI will popup that will enable you to easily deobfuscate - stacktraces and fully qualified classnames as well as provide a - convenient way to browse the mapping generated by yGuard. -
- In the main window a tree view displays the package, class, and - classmember hierarchy using the unobfuscated names. For each entry that - has been obfuscated (classes, packages, methods, and fields that have not - been obfuscated at all may not always be shown in the tree) the - corresponding mapped/obfuscated name is displayed. -
- The two buttons at the top of the window allow to change the sorting of - the items in the tree structure, so that they are either sorted according - to their names before or after the obfuscation. Items will always be - sorted by type first: - packages, classes, innerclasses, methods, and fields. Small icons provide - a convenient way to quickly find the corresponding items. -

- -

- The lower part of the window contains an editable text area that can be - used to enter text or paste stacktraces in. - Pressing the button at the bottom of the window labelled "Deobfuscate" - will trigger the deobfuscation of the contents in the text area. The tool - will try to identify fully qualified class names (separated by dots) and - use the mapping information to reconstruct the original names. If the tool - identifies a stack trace element, it will try to deobfuscate scrambled - line numbers, too, if they have been scrambled during the obfuscation - process. -

-
- - - -

Problems and Bug Reports

- -
-

- If you experience any problems or think you have found a bug feel free to - send an email to yguard@yworks.com - but please make sure you have read the documentation thoroughly before. We - will do our best and try to answer your questions. -

-
- - - -

DTD used for Ant <yguard>

- -
-

- The obfuscation and shrinking process can be completely configured inside - your Ant script. - The yguard task and nested elements should be - used according to the following DTD. Note that this is for information - purposes only, i.e. you do not have to include the following lines - anywhere. This DTD should just provide a quick overview of the yGuard - syntax. Due to restrictions of the DTD specification, the given DTD does - not describe all available yGuard options. Please browse through the - documentation above for complete documentation of the yGuard Ant task - elements. -

- - 
<!ELEMENT yguard (inoutpair+,externalclasses?,attribute*,(shrink|rename)+)>
-
-<!ELEMENT inoutpair EMPTY>
-<!ATTLIST inoutpair
-in CDATA #REQUIRED
-out CDATA #REQUIRED
-resources CDATA #IMPLIED>
-<!--
-NOTE: the resources attribute only has an effect if a shrink element is present inside the yguard element.
--->
-
-<!ELEMENT externalclasses ANY>
-<!-- the externalclasses element is used just like Ant's classpath
-element. See the Ant documentation for further details-->
-
-<!ELEMENT attribute (patternset)*>
-name CDATA #REQUIRED>
-
-<!ELEMENT shrink (entrypointjar*,keep?)>
-<!ATTLIST shrink
-logfile CDATA #IMPLIED
-createStubs CDATA #IMPLIED>
-
-<!ELEMENT entrypointjar>
-<!ATTLIST entrypointjar
-name CDATA #REQUIRED>
-
-<!ELEMENT rename (property*,patch?,adjust*,map?,keep?)>
-<!ATTLIST rename
-mainclass CDATA #IMPLIED
-logfile CDATA #IMPLIED
-conservemanifest CDATA #IMPLIED
-replaceClassNameStrings CDATA #IMPLIED>
-
-<!ELEMENT property EMPTY>
-<!ATTLIST property
-name CDATA #REQUIRED
-value CDATA #REQUIRED>
-
-<!ELEMENT patch (class)*>
-
-<!ELEMENT adjust (#PCDATA)>
-<!ATTLIST adjust
-replaceName CDATA #REQUIRED
-replaceContent CDATA #REQUIRED
-replacePath CDATA #REQUIRED>
-
-<!ELEMENT map (class|method|field|package)*>
-
-<!ELEMENT package (patternset)*>
-<!ATTLIST package
-name CDATA #REQUIRED
-map CDATA #REQUIRED>
-<!--
-NOTE: the map attribute is only supported
-if the <package> element is nested inside a <map> element, whereas the patternset is
-only supported inside the <keep>/<expose> sections.
--->
-
-<!ELEMENT keep (package|class|method|field|sourcefile|linenumbertable)*>
-<!--
-NOTE: the nested <package>,<sourcefile>,<linenumbertable> and <attribute> sections are only
-supported in the <rename> element.
--->
-<!ATTLIST keep
-linenumbertable CDATA #IMPLIED
-localvariabletable CDATA #IMPLIED
-localvariabletypetable CDATA #IMPLIED
-runtimeinvisibleannotations CDATA #IMPLIED
-runtimeinvisibletypeannotations CDATA #IMPLIED
-runtimevisibleannotations CDATA #IMPLIED
-runtimevisibletypeannotations CDATA #IMPLIED
-sourcefile CDATA #IMPLIED>
-
-<!ELEMENT class (patternset)*>
-<!ATTLIST class
-classes CDATA #IMPLIED
-fields CDATA #IMPLIED
-map CDATA #IMPLIED
-methods CDATA #IMPLIED
-name CDATA #IMPLIED>
-<!--
-NOTE: the map attribute is only supported
-if the <class> element is nested inside an <rename> element.
--->
-
-<!ELEMENT method (patternset)*>
-<!ATTLIST method
-class CDATA #IMPLIED
-map CDATA #IMPLIED
-name CDATA #IMPLIED>
-<!--
-NOTE: the map attribute is only supported
-if the <method> element is nested inside an <rename> element.
--->
-
-<!ELEMENT field (patternset)*>
-<!ATTLIST field
-class CDATA #IMPLIED
-map CDATA #IMPLIED
-name CDATA #IMPLIED>
-<!--
-NOTE: the field attribute is only supported
-if the <method> element is nested inside an <rename> element.
--->
- -

- Attention users of IDEs that "support" the creation of Ant files - (e.g. IDEA's IntelliJ): - Your IDE may indicate some errors inside your ANT file when you use yGuard - specific elements. This is because the IDE does not know about the DTD - used by yGuard. However this is not a real problem, since the Ant file - should nevertheless work as expected. -

-
-
- - - - From a0ced95478a42b8259a2a48aabded7c6e0ac719e Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 4 Nov 2019 17:30:12 +0100 Subject: [PATCH 17/38] Add table of contents to task documentation. --- docs/task_documentation.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/task_documentation.md b/docs/task_documentation.md index f032d4a5..77645dde 100644 --- a/docs/task_documentation.md +++ b/docs/task_documentation.md @@ -13,6 +13,29 @@ The `yguard` task contains two nested elements that perform the name obfuscation - The [shrink](#the-shrink-element) element removes all code elements that are not reachable from the entrypoints given in the nested [keep](#the-keep-element) element. - The [rename](#the-rename-element) element performs name-obfuscation, renaming all packages, classes, methods and fields according to a selectable name-mapping scheme. Elements can be excluded from the renaming process by annotating them with a certain annotation class in the source code or using a nested [keep](#the-keep-element) element. +## Table of contents + +- [`yguard` element](#the-yguard-element) + - [`inoutpair` element](#the-inoutpair-element) + - [`externalclasses` element](#the-externalclasses-element) + - [`attribute` element](#the-attribute-element) + - [`rename` element](#the-rename-element) + - [`property` element](#the-property-element) + - [`patch` element](#generating-patch-jars) + - [`adjust` element](#the-adjust-element) + - [`map` element](#the-map-element) + - [`package` element](#the-package-element) + - [`class` element](#the-class-element) + - [`method` element](#the-method-element) + - [`field` element](#the-field-element) + - [`shrink` element](#the-shrink-element) + - [`entrypointjar` element](#the-entrypointjar-element) + - [`keep` element](#the-keep-element) +- [Controlling obfuscation exclusion with annotations](#controlling-obfuscation-exclusion-with-annotations) +- [Generating patch JARs](#generating-patch-jars) +- [Deobfuscating stacktraces](#deobfuscating-stacktraces) +- [DTD used for Ant ``](#dtd-used-for-ant-yguard) + ## The yguard Element The yguard task contains elements that define basic properties common to the nested `rename` and `shrink` tasks. @@ -880,7 +903,7 @@ The last example shows how to keep the `public` methods of certain classes only, ``` -## The `method` Element +## The `method` Element Using the `method` element you can specify methods by signature which should be excluded from shrinking or name obfuscation. #### Attributes @@ -1335,7 +1358,7 @@ Using the `patch` element one can generate jars, that can be used to serve as pa ``` This will only include the MainClass class and all classes that belong to the bugs package in a patch jar. In order to work with the previously delivered obfuscated version, it is important to use the map element to specify the mapping of the elements from the previous run. This can most conveniently be achieved by specifying the log file from the corresponding run in the map element's logfile attribute. -## Deobfuscating Stacktraces Etc. +## Deobfuscating stacktraces yGuard provides a simple tool that makes it easy for the obfuscating party to deobfuscate stacktraces which have been obfuscated using yGuard. During the obfuscation yGuard produces an xml logfile which can automatically be gzipped for convenient storage. You should always keep those logfiles in order to be able to deobfuscate fully qualified classnames or methods or fields for debugging purposes e.g. In order to run the yGuard deobfuscation tool do the following: From 3a8db1ea057756ad476a3a815cc44f3f29c8e0b0 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 4 Nov 2019 17:31:55 +0100 Subject: [PATCH 18/38] Replace old span elements with . --- docs/task_documentation.md | 206 ++++++++++++++++++------------------- 1 file changed, 103 insertions(+), 103 deletions(-) diff --git a/docs/task_documentation.md b/docs/task_documentation.md index 77645dde..1a42730a 100644 --- a/docs/task_documentation.md +++ b/docs/task_documentation.md @@ -135,31 +135,31 @@ Additionally or alternatively to `inoutpair` elements this element can be specif - resources + resources Will only be considered if the - yguard element + yguard element contains a nested - shrink element. + shrink element.
Determines how the shrinking engine handles all non-.class files.
Currently the following three resource policies are supported:
    -
  • copy
    +
  • copy
    the default, simply copies all resource files to the output jar.
    • -
  • auto
    +
  • auto
    copies only those resource files that reside in a directory that still contains one or more .class files after shrinking.
    • -
  • none
    +
  • none
    discards all resource files.
- No, defaults to copy. + No, defaults to copy. @@ -212,7 +212,7 @@ See [linked example] for an example of when to use this element. - name + name A comma-separated list of attribute names that are to be retained in the shrinked and/or obfuscated class @@ -253,7 +253,7 @@ See the [examples]() explenation of some common use cases. If your code uses ref - logfile + logfile Determines the name of the logfile that is generated during the shrinking process. The logfile contains information about the entrypoints the shrinking engine uses, the removed classes, @@ -269,16 +269,16 @@ See the [examples]() explenation of some common use cases. If your code uses ref - createStubs + createStubs Instead of removing methods completely, this attribute causes the - shrink task to insert a method + shrink task to insert a method stub that throws a java.lang.InternalError if it is called. This attribute is very useful if the shrinking process causes your application to break and you are uncertain about which additional code entities you have to include in the - keepelement.
+ keepelement.
Note that classes considered as completely obsolete by the shrinking engine are still removed completely - this attribute only affects obsolete methods of non-obsolete classes. @@ -310,7 +310,7 @@ The `entrypointjar` element can be used for convenience if your application uses - name + name Path to to the jar file to use as entrypointjar. Yes @@ -344,20 +344,20 @@ The basic idea is, that all elements will be renamed by this task. There are dif - mainclass + mainclass Can be used as a shortcut to specify the mainclass of your application. Both the class name and the main method will be excluded from name obfuscation. Alternatively you may want to consider to exclude the main method only. If your jar contains a Main-Class attribute, the - rename task will automatically adjust + rename task will automatically adjust the value to the obfuscated name. No - logfile + logfile Determines the name of the logfile that is generated during the renaming process. The logfile contains information about the mappings the name obfuscator generates as well as any warnings. @@ -370,7 +370,7 @@ The basic idea is, that all elements will be renamed by this task. There are dif No, defaults toyguardlog.xml - conservemanifest + conservemanifest A boolean attribute (valid values: true/false) that determines whether the @@ -384,7 +384,7 @@ The basic idea is, that all elements will be renamed by this task. There are dif - replaceClassNameStrings + replaceClassNameStrings A boolean attribute (valid values: @@ -415,7 +415,7 @@ The basic idea is, that all elements will be renamed by this task. There are dif - annotationClass + annotationClass Specifies the name of the annotation class that can be used to exclude elements by annotating them in the source code. The @@ -452,14 +452,14 @@ The basic idea is, that all elements will be renamed by this task. There are dif - name + name Specifies a key which may be interpreted by the obfuscation task. Yes - value + value Specifies the corresponding value of the property. @@ -480,15 +480,15 @@ The basic idea is, that all elements will be renamed by this task. There are dif - error-checking + error-checking Can be used to tell yGuard to bail out if it detects any problems. Currently this property can be set to the following value:
  • - pedantic
    + pedantic
    Will make the obfuscation run fail, i.e. the target which uses - the renameelement will fail, if + the renameelement will fail, if yGuard detects any problems.
@@ -496,19 +496,19 @@ The basic idea is, that all elements will be renamed by this task. There are dif - naming-scheme + naming-scheme Can be used to tell the renaming engine to use a different naming scheme during the obfuscation. Currently this property can be set to one of the following values:
  • - small
    + small
    Will produce very short names, i.e. the resulting jar file will be as small as possible.
  • - best
    + best
    Will produce names, that are very likely to be misunderstood by decompilers and disassemblers. Using this naming-scheme it is even impossible on most filesystems to successfully unjar or @@ -519,7 +519,7 @@ The basic idea is, that all elements will be renamed by this task. There are dif size).
  • - mix
    + mix
    Is a mixture of both the other two values, which leads to reasonable small but still hard to decompile jar files.
    • @@ -528,7 +528,7 @@ The basic idea is, that all elements will be renamed by this task. There are dif - language-conformity + language-conformity Can be used to advise the renaming engine to produce names, that should be decompilable by most decompilers. On the other hand, @@ -540,17 +540,17 @@ The basic idea is, that all elements will be renamed by this task. There are dif Currently this property can be set to one of the following values:
    • - compatible
      + compatible
      Will produce names, that are ok for (most) decompilers, java, jar and manifest files and can be unzipped to most filesystems.
    • - legal
      + legal
      Will produce names, that are ok for (some) decompilers, java, jar and manifest files.
    • - illegal
      + illegal
      Will produce names, that will crash some tools but usually not the jvm, but JBuilder7 in many occasions for example.
      • @@ -559,7 +559,7 @@ The basic idea is, that all elements will be renamed by this task. There are dif - overload-enabled + overload-enabled Determines whether the renaming engine tries to use the same names for methods with different signatures or whether it always generates @@ -570,7 +570,7 @@ The basic idea is, that all elements will be renamed by this task. There are dif - obfuscation-prefix + obfuscation-prefix Can be used to instruct the renaming engine to prefix packages, that are fully obfuscated with a given package prefix, e.g. @@ -579,18 +579,18 @@ The basic idea is, that all elements will be renamed by this task. There are dif - digests + digests Can be used to tell yGuard which digest algorithms should be used for the digest generation in the manifest file. Valid values are - either none, or a comma-separated + either none, or a comma-separated list of digest-algorithm identifiers, e.g. - SHA-1, MD5 (which is the default). + SHA-1, MD5 (which is the default). - expose-attributes + expose-attributes Can be used to give yGuard a list of attributes yGuard should expose in addition to the standard attributes. @@ -628,94 +628,94 @@ Note that a more fine-grained control over which attributes to keep for which cl Attribute Description - Default (rename) - Default (shrink) + Default (rename) + Default (shrink) - sourcefile + sourcefile Determines whether the name of the original source code file should be included in the output class files. - remove - remove + remove + remove - linenumbertable + linenumbertable Determines whether the line number table, that contains a mapping from each opcode in the class file to the line number in the original source code file should be included in the output class files. - remove - remove + remove + remove - localvariabletable + localvariabletable Determines whether the local variable table, that contains a mapping from each local variable in the class file to the name that has been used in the original source code file should be included in the output class files. - remove - remove + remove + remove - localvariabletypetable + localvariabletypetable Determines whether the local variable type table, that contains a mapping from each local variable in the class file to the name and its generic type signature that has been used in the original source code file should be included in the output class files. - remove - remove + remove + remove - runtimevisibleannotations + runtimevisibleannotations Determines whether annotations with the retention policy RetentionPolicy.RUNTIMEshould be included in the output class files. - keep - keep + keep + keep - runtimevisibleparameterannotations + runtimevisibleparameterannotations Determines whether method paramater annotations with the retention policy RetentionPolicy.RUNTIME should be included in the output class files. - keep - keep + keep + keep - runtimeinvisibleannotations + runtimeinvisibleannotations Determines whether annotations with the retention policy RetentionPolicy.CLASSshould be included in the output class files. - keep - remove + keep + remove - runtimeinvisibleparameterannotations + runtimeinvisibleparameterannotations Determines whether method paramater annotations with the retention policy RetentionPolicy.CLASS should be included in the output class files. - keep - remove + keep + remove @@ -730,41 +730,41 @@ The `classes`, `methods` and `fields` attributes tell the shrinking and renaming - - - - + + + + - + - + - + - + - + @@ -785,32 +785,32 @@ The `classes`, `methods` and `fields` attributes tell the shrinking and renaming - + - + + No, defaults to none - + + No, defaults to none - + + No, defaults to none - + - + - + - + - + - + - + @@ -1100,24 +1100,24 @@ Using nested `property` elements, the mapping of `linenumbertable` attributes in - + - + @@ -1192,7 +1192,7 @@ Using the `adjust` element one can specify resource files whose names and/or con - + - + - + - + - + @@ -826,7 +826,7 @@ The `classes`, `methods` and `fields` attributes tell the shrinking and renaming all classes that equal or implement the class defined by the given fully qualified classname.
      - See example 7 for an example usage of this + See serializable_example for an example usage of this attribute. diff --git a/examples/README.md b/examples/README.md index 08342609..c393ca29 100644 --- a/examples/README.md +++ b/examples/README.md @@ -4,7 +4,12 @@ examples This folder contains various examples for setting up `yGuard` in different scenarios. - [application](application/) (a very basic setup. Simple program with one main method and no other exposed functionality.) -- [library](library/) (library example, illustrating how to expose specific parts of a library.) +- [library](library/) (library example, illustrating how to expose specific parts of a library) +- [external_library](external_library/) (shows how to embed an external program into obfuscation) +- [resources](resources/) (shows how to embed resources, such a `.properties` files) +- [linked_library](linked_library/) (shows how to obfuscate a third party library) +- [serializable_exclusion](serializable_exclusion/) (shows how to exclude serializable elements using `implements` and `extends`) +- [annotation](annotation/) (shows how to use annotations to exlude items from obfuscation) ## Building a example diff --git a/examples/annotation/README.md b/examples/annotation/README.md new file mode 100644 index 00000000..eb8baf39 --- /dev/null +++ b/examples/annotation/README.md @@ -0,0 +1,298 @@ +annotation +---------- + +This section gives examples on how to use annotations to control which elements should be excluded from the obfuscation process (i.e., keep their names). The following assumes that there is an annotation class named `com.yworks.util.annotation.Obfuscation` in the classpath that follows the convention as described above. + +## Obfuscation Exclusion per Item + +```java +@com.yworks.util.annotation.Obfuscation( exclude = true, applyToMembers = false) +public class Person { + + public String name; + + public String occupation; + + @com.yworks.util.annotation.Obfuscation( exclude = true ) + public int age; +} +``` + +#### Obfuscation + +
      Value/Visibilitypublicprotectedfriendlyprivatepublicprotectedfriendlyprivate
      nonenone - - - -
      publicpublic * - - -
      protectedprotected * * - -
      friendlyfriendly * * * -
      privateprivate * * *
      namename The name of the class to be kept. No
      classesclasses The visibility of the classes to be kept. - No, defaults to none
      methodsmethods The visibility of the methods to be kept. - No, defaults to none
      fieldsfields The visibility of the fields to be kept. - No, defaults to none
      extendsextends - If no name attribute is given, keeps + If no name attribute is given, keeps all classes that equal or extend the class defined by the given fully qualified classname.
      @@ -820,9 +820,9 @@ The `classes`, `methods` and `fields` attributes tell the shrinking and renaming       		No
      implementsimplements - If no name attribute is given, keeps + If no name attribute is given, keeps all classes that equal or implement the class defined by the given fully qualified classname.
      @@ -917,7 +917,7 @@ Using the `method` element you can specify methods by signature which should be
      namename Specifies the method to keep. Use the complete signature using fully qualified class names and the return type! @@ -925,7 +925,7 @@ Using the `method` element you can specify methods by signature which should be Yes
      classclass Specifies the class which contains the method. Use the normal java syntax, i.e. the fully qualified name. @@ -978,7 +978,7 @@ Using the `field` element you can specify fields by name which should be exclude
      namename Specifies the field to keep. Use the name of the field only, do not include its type! @@ -986,12 +986,12 @@ Using the `field` element you can specify fields by name which should be exclude Yes
      classclass Specifies the class which contains the field. Use the normal java syntax, i.e. the fully qualified name. This attribute can be omitted, if the - patternset element is used as + patternset element is used as a child element, in which case the all classes matching the patternset will be searched and their corresponding fields will be kept. @@ -1054,11 +1054,11 @@ Using nested property elements, the mapping of sourceFile attributes in obfuscat
      mappingmapping The value of this property determines the name all - sourceFile attributes matched by the - sourcefile element are mapped to. + sourceFile attributes matched by the + sourcefile element are mapped to.
      mapping-schememapping-scheme Can be used with the following two values:
      • - scramble
        + scramble
        This will use a non-trivial algorithm to scramble the line numbers in the existing file. The algorithm implemented uses a different scrambling scheme for each class. The optional - scrambling-salt property can be + scrambling-salt property can be used to provide an integer value that will be used to "salt" the algorithm's random seed for the scrambling. The size of the (uncompressed) .class file will not change using this mapping scheme.
      • - squeeze
        + squeeze
        This will use a simple algorithm that virtually puts all of a method's code into the first line of code of the method. It will appear as if each method had been written in a single line of @@ -1131,10 +1131,10 @@ Using nested `property` elements, the mapping of `linenumbertable` attributes in
      scrambling-saltscrambling-salt Can be used in conjunction with - mapping-scheme to provide an integer + mapping-scheme to provide an integer value that will be used to "salt" the algorithm's random seed for the scrambling.
      replaceNamereplaceName Specifies whether or not the names of the specified resources should be adjusted. @@ -1201,7 +1201,7 @@ Using the `adjust` element one can specify resource files whose names and/or con
      replaceContentreplaceContent Specifies whether or not the contents of resource files should be adjusted. @@ -1210,7 +1210,7 @@ Using the `adjust` element one can specify resource files whose names and/or con
      replacePathreplacePath Specifies whether or not the paths to the resource files should be adjusted. @@ -1304,7 +1304,7 @@ The convention for annotation classes that yGuard understands as obfuscation con
      excludeexclude Specifies whether the annotated element should be excluded from the obfuscation. Note, that when retaining a class, the hierarchy of @@ -1314,7 +1314,7 @@ The convention for annotation classes that yGuard understands as obfuscation con true
      applyToMembersapplyToMembers Specifies whether the child elements of the annotated element, if not otherwise specified, should be excluded from the obfuscation. From 418d7358ee44f977c2efb1cdceb19cb0deb56030 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 4 Nov 2019 17:35:24 +0100 Subject: [PATCH 19/38] Add license. --- docs/index.md | 1 + docs/license.md | 9 +++++++++ 2 files changed, 10 insertions(+) create mode 100644 docs/license.md diff --git a/docs/index.md b/docs/index.md index 3a107393..a874642a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,6 +20,7 @@ yGuard is brought to you by [yWorks GmbH](https://www.yworks.com/), creator of t - [Task documentation](/task) - [Examples](https://github.com/yWorks/yguard/tree/master/examples) - [Troubleshooting](/troubleshooting) +- [License](/license) ### Problems and Bug Reports diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000..253018e7 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,9 @@ +--- +layout: default +title: License +permalink: /license/ +--- + +`yGuard` is licensed under the `MIT` license. Legacy parts of the software are retained under `LGPL` and released in the `retroguard` archive. + +All 3rd party licenses can be found in the `3rdPartyLicenses` folder. From 0c6a455568277a7a1138a8834d3c9b039441d306 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 4 Nov 2019 17:41:42 +0100 Subject: [PATCH 20/38] Update README with more recent information. --- README.md | 23 +- docs/3rdPartyLicenses/ant-license.txt | 204 +++++++++ docs/3rdPartyLicenses/asm-license.txt | 30 ++ docs/3rdPartyLicenses/guava-license.txt | 203 +++++++++ docs/3rdPartyLicenses/retroguard-LGPL.txt | 504 ++++++++++++++++++++++ 5 files changed, 953 insertions(+), 11 deletions(-) create mode 100644 docs/3rdPartyLicenses/ant-license.txt create mode 100644 docs/3rdPartyLicenses/asm-license.txt create mode 100644 docs/3rdPartyLicenses/guava-license.txt create mode 100644 docs/3rdPartyLicenses/retroguard-LGPL.txt diff --git a/README.md b/README.md index 0cb1fb0a..7b678c28 100644 --- a/README.md +++ b/README.md @@ -9,29 +9,30 @@ yGuard is brought to you by [yWorks GmbH](https://www.yworks.com/), creator of t ## Obtaining yGuard -Starting with the `2.8` release `yGuard` is MIT-licensed. Releases can be downloaded directly from GitHub. +Recent `yGuard` releases can be downloaded from GitHub, or used from `Maven` central directly. -Legacy code ported from `retroguard` under `LGPL` is statically linked at compile time via `yGuard-lgpl.jar`. +Legacy code ported from `retroguard` under `LGPL` is compiled into a seperate archive called `retroguard-${VERSION}.jar`. Previous releases _may_ still be downloaded from the [yWorks download center](https://www.yworks.com/downloads#yGuard). ## Usage -`yGuard` is distributed with usage instructions. In your distribution, `docs/index.html` contains documentation about the bundled `ant` task. +An online version of this documentation [is available](https://yworks.github.io/yguard/). + +Additionally, `yGuard` is distributed with usage instructions. In your distribution, the `docs` folder contains informtion about `yGuard`. +In order to properly view the offline documentation, a web server is needed. A quick way to accomplish this is using: + +``` +cd docs/ +python3 -m http.server 4000 +``` -An online version of this documentation [is available as well](https://yworks.github.io/yguard/). ## Building To build `yGuard` you will need `Java >= 7` and [Gradle](https://gradle.org/). -Once installed you can build `yGuard` like so: -``` -gradle build -gradle obfuscate # if you would like to obfuscate the library as well -``` - -The built files can be found in `build/libs/`. +Once installed you can build `yGuard` using `gradle build`. ### Using IntellIJ with yGuard diff --git a/docs/3rdPartyLicenses/ant-license.txt b/docs/3rdPartyLicenses/ant-license.txt new file mode 100644 index 00000000..1c572e31 --- /dev/null +++ b/docs/3rdPartyLicenses/ant-license.txt @@ -0,0 +1,204 @@ +/* + * Apache License + * Version 2.0, January 2004 + * http://www.apache.org/licenses/ + * + * TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + * + * 1. Definitions. + * + * "License" shall mean the terms and conditions for use, reproduction, + * and distribution as defined by Sections 1 through 9 of this document. + * + * "Licensor" shall mean the copyright owner or entity authorized by + * the copyright owner that is granting the License. + * + * "Legal Entity" shall mean the union of the acting entity and all + * other entities that control, are controlled by, or are under common + * control with that entity. For the purposes of this definition, + * "control" means (i) the power, direct or indirect, to cause the + * direction or management of such entity, whether by contract or + * otherwise, or (ii) ownership of fifty percent (50%) or more of the + * outstanding shares, or (iii) beneficial ownership of such entity. + * + * "You" (or "Your") shall mean an individual or Legal Entity + * exercising permissions granted by this License. + * + * "Source" form shall mean the preferred form for making modifications, + * including but not limited to software source code, documentation + * source, and configuration files. + * + * "Object" form shall mean any form resulting from mechanical + * transformation or translation of a Source form, including but + * not limited to compiled object code, generated documentation, + * and conversions to other media types. + * + * "Work" shall mean the work of authorship, whether in Source or + * Object form, made available under the License, as indicated by a + * copyright notice that is included in or attached to the work + * (an example is provided in the Appendix below). + * + * "Derivative Works" shall mean any work, whether in Source or Object + * form, that is based on (or derived from) the Work and for which the + * editorial revisions, annotations, elaborations, or other modifications + * represent, as a whole, an original work of authorship. For the purposes + * of this License, Derivative Works shall not include works that remain + * separable from, or merely link (or bind by name) to the interfaces of, + * the Work and Derivative Works thereof. + * + * "Contribution" shall mean any work of authorship, including + * the original version of the Work and any modifications or additions + * to that Work or Derivative Works thereof, that is intentionally + * submitted to Licensor for inclusion in the Work by the copyright owner + * or by an individual or Legal Entity authorized to submit on behalf of + * the copyright owner. For the purposes of this definition, "submitted" + * means any form of electronic, verbal, or written communication sent + * to the Licensor or its representatives, including but not limited to + * communication on electronic mailing lists, source code control systems, + * and issue tracking systems that are managed by, or on behalf of, the + * Licensor for the purpose of discussing and improving the Work, but + * excluding communication that is conspicuously marked or otherwise + * designated in writing by the copyright owner as "Not a Contribution." + * + * "Contributor" shall mean Licensor and any individual or Legal Entity + * on behalf of whom a Contribution has been received by Licensor and + * subsequently incorporated within the Work. + * + * 2. Grant of Copyright License. Subject to the terms and conditions of + * this License, each Contributor hereby grants to You a perpetual, + * worldwide, non-exclusive, no-charge, royalty-free, irrevocable + * copyright license to reproduce, prepare Derivative Works of, + * publicly display, publicly perform, sublicense, and distribute the + * Work and such Derivative Works in Source or Object form. + * + * 3. Grant of Patent License. Subject to the terms and conditions of + * this License, each Contributor hereby grants to You a perpetual, + * worldwide, non-exclusive, no-charge, royalty-free, irrevocable + * (except as stated in this section) patent license to make, have made, + * use, offer to sell, sell, import, and otherwise transfer the Work, + * where such license applies only to those patent claims licensable + * by such Contributor that are necessarily infringed by their + * Contribution(s) alone or by combination of their Contribution(s) + * with the Work to which such Contribution(s) was submitted. If You + * institute patent litigation against any entity (including a + * cross-claim or counterclaim in a lawsuit) alleging that the Work + * or a Contribution incorporated within the Work constitutes direct + * or contributory patent infringement, then any patent licenses + * granted to You under this License for that Work shall terminate + * as of the date such litigation is filed. + * + * 4. Redistribution. You may reproduce and distribute copies of the + * Work or Derivative Works thereof in any medium, with or without + * modifications, and in Source or Object form, provided that You + * meet the following conditions: + * + * (a) You must give any other recipients of the Work or + * Derivative Works a copy of this License; and + * + * (b) You must cause any modified files to carry prominent notices + * stating that You changed the files; and + * + * (c) You must retain, in the Source form of any Derivative Works + * that You distribute, all copyright, patent, trademark, and + * attribution notices from the Source form of the Work, + * excluding those notices that do not pertain to any part of + * the Derivative Works; and + * + * (d) If the Work includes a "NOTICE" text file as part of its + * distribution, then any Derivative Works that You distribute must + * include a readable copy of the attribution notices contained + * within such NOTICE file, excluding those notices that do not + * pertain to any part of the Derivative Works, in at least one + * of the following places: within a NOTICE text file distributed + * as part of the Derivative Works; within the Source form or + * documentation, if provided along with the Derivative Works; or, + * within a display generated by the Derivative Works, if and + * wherever such third-party notices normally appear. The contents + * of the NOTICE file are for informational purposes only and + * do not modify the License. You may add Your own attribution + * notices within Derivative Works that You distribute, alongside + * or as an addendum to the NOTICE text from the Work, provided + * that such additional attribution notices cannot be construed + * as modifying the License. + * + * You may add Your own copyright statement to Your modifications and + * may provide additional or different license terms and conditions + * for use, reproduction, or distribution of Your modifications, or + * for any such Derivative Works as a whole, provided Your use, + * reproduction, and distribution of the Work otherwise complies with + * the conditions stated in this License. + * + * 5. Submission of Contributions. Unless You explicitly state otherwise, + * any Contribution intentionally submitted for inclusion in the Work + * by You to the Licensor shall be under the terms and conditions of + * this License, without any additional terms or conditions. + * Notwithstanding the above, nothing herein shall supersede or modify + * the terms of any separate license agreement you may have executed + * with Licensor regarding such Contributions. + * + * 6. Trademarks. This License does not grant permission to use the trade + * names, trademarks, service marks, or product names of the Licensor, + * except as required for reasonable and customary use in describing the + * origin of the Work and reproducing the content of the NOTICE file. + * + * 7. Disclaimer of Warranty. Unless required by applicable law or + * agreed to in writing, Licensor provides the Work (and each + * Contributor provides its Contributions) on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + * implied, including, without limitation, any warranties or conditions + * of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + * PARTICULAR PURPOSE. You are solely responsible for determining the + * appropriateness of using or redistributing the Work and assume any + * risks associated with Your exercise of permissions under this License. + * + * 8. Limitation of Liability. In no event and under no legal theory, + * whether in tort (including negligence), contract, or otherwise, + * unless required by applicable law (such as deliberate and grossly + * negligent acts) or agreed to in writing, shall any Contributor be + * liable to You for damages, including any direct, indirect, special, + * incidental, or consequential damages of any character arising as a + * result of this License or out of the use or inability to use the + * Work (including but not limited to damages for loss of goodwill, + * work stoppage, computer failure or malfunction, or any and all + * other commercial damages or losses), even if such Contributor + * has been advised of the possibility of such damages. + * + * 9. Accepting Warranty or Additional Liability. While redistributing + * the Work or Derivative Works thereof, You may choose to offer, + * and charge a fee for, acceptance of support, warranty, indemnity, + * or other liability obligations and/or rights consistent with this + * License. However, in accepting such obligations, You may act only + * on Your own behalf and on Your sole responsibility, not on behalf + * of any other Contributor, and only if You agree to indemnify, + * defend, and hold each Contributor harmless for any liability + * incurred by, or claims asserted against, such Contributor by reason + * of your accepting any such warranty or additional liability. + * + * END OF TERMS AND CONDITIONS + * + * APPENDIX: How to apply the Apache License to your work. + * + * To apply the Apache License to your work, attach the following + * boilerplate notice, with the fields enclosed by brackets "[]" + * replaced with your own identifying information. (Don't include + * the brackets!) The text should be enclosed in the appropriate + * comment syntax for the file format. We also recommend that a + * file or class name and description of purpose be included on the + * same "printed page" as the copyright notice for easier + * identification within third-party archives. + * + * Copyright [yyyy] [name of copyright owner] + * + * 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. + */ + diff --git a/docs/3rdPartyLicenses/asm-license.txt b/docs/3rdPartyLicenses/asm-license.txt new file mode 100644 index 00000000..75284b46 --- /dev/null +++ b/docs/3rdPartyLicenses/asm-license.txt @@ -0,0 +1,30 @@ +ASM: a very small and fast Java bytecode manipulation framework +Copyright (c) 2000-2011 INRIA, France Telecom +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. Neither the name of the copyright holders nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +THE POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/3rdPartyLicenses/guava-license.txt b/docs/3rdPartyLicenses/guava-license.txt new file mode 100644 index 00000000..6b0b1270 --- /dev/null +++ b/docs/3rdPartyLicenses/guava-license.txt @@ -0,0 +1,203 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + 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. + diff --git a/docs/3rdPartyLicenses/retroguard-LGPL.txt b/docs/3rdPartyLicenses/retroguard-LGPL.txt new file mode 100644 index 00000000..6b0b7977 --- /dev/null +++ b/docs/3rdPartyLicenses/retroguard-LGPL.txt @@ -0,0 +1,504 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 2.1, February 1999 + + Copyright (C) 1991, 1999 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +[This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence + the version number 2.1.] + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software--to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software packages--typically libraries--of the +Free Software Foundation and other authors who decide to use it. You +can use it too, but we suggest you first think carefully about whether +this license or the ordinary General Public License is the better +strategy to use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of +it in new free programs; and that you are informed that you can do +these things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the "Lesser" General Public License because it +does Less to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +"work based on the library" and a "work that uses the library". The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + + GNU LESSER GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License Agreement applies to any software library or other +program which contains a notice placed by the copyright holder or +other authorized party saying it may be distributed under the terms of +this Lesser General Public License (also called "this License"). +Each licensee is addressed as "you". + + A "library" means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + + The "Library", below, refers to any such software library or work +which has been distributed under these terms. A "work based on the +Library" means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term "modification".) + + "Source code" for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + + Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + + 1. You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + + You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + + 2. You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) The modified work must itself be a software library. + + b) You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c) You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. + + d) If a facility in the modified Library refers to a function or a + table of data to be supplied by an application program that uses + the facility, other than as an argument passed when the facility + is invoked, then you must make a good faith effort to ensure that, + in the event an application does not supply such function or + table, the facility still operates, and performs whatever part of + its purpose remains meaningful. + + (For example, a function in a library to compute square roots has + a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function must + be optional: if the application does not supply it, the square + root function must still compute square roots.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + + Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + + 4. You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + + If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + + 5. A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a "work that uses the Library". Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + + However, linking a "work that uses the Library" with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a "work that uses the +library". The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + + When a "work that uses the Library" uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + + 6. As an exception to the Sections above, you may also combine or +link a "work that uses the Library" with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + + a) Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable "work that + uses the Library", as object code and/or source code, so that the + user can modify the Library and then relink to produce a modified + executable containing the modified Library. (It is understood + that the user who changes the contents of definitions files in the + Library will not necessarily be able to recompile the application + to use the modified definitions.) + + b) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run time a + copy of the library already present on the user's computer system, + rather than copying library functions into the executable, and (2) + will operate properly with a modified version of the library, if + the user installs one, as long as the modified version is + interface-compatible with the version that the work was made with. + + c) Accompany the work with a written offer, valid for at + least three years, to give the same user the materials + specified in Subsection 6a, above, for a charge no more + than the cost of performing this distribution. + + d) If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above + specified materials from the same place. + + e) Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the "work that uses the +Library" must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the materials to be distributed need not include anything that is +normally distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies +the executable. + + It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + + 7. You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + + a) Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library + facilities. This must be distributed under the terms of the + Sections above. + + b) Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining + where to find the accompanying uncombined form of the same work. + + 8. You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + + 9. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + + 10. Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + + 11. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 12. If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + + 13. The Free Software Foundation may publish revised and/or new +versions of the Lesser General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +"any later version", you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + + 14. If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + + NO WARRANTY + + 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Libraries + + If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + + To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the library, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the + library `Frob' (a library for tweaking knobs) written by James Random Hacker. + + , 1 April 1990 + Ty Coon, President of Vice + +That's all there is to it! + + From 5d17eb80063921e55ca2c424b2cb070ad7129d43 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Wed, 6 Nov 2019 16:09:17 +0100 Subject: [PATCH 21/38] Add library example. --- examples/library/build.gradle | 61 ++++++++++++++ examples/library/build.xml | 75 +++++++++++++++++ examples/library/pom.xml | 81 +++++++++++++++++++ examples/library/settings.gradle | 1 + .../java/com/yworks/example/Functional.java | 30 +++++++ .../java/com/yworks/example/HelloWorld.java | 15 ++++ .../java/com/yworks/example/Reducible.java | 12 +++ 7 files changed, 275 insertions(+) create mode 100644 examples/library/build.gradle create mode 100644 examples/library/build.xml create mode 100644 examples/library/pom.xml create mode 100644 examples/library/settings.gradle create mode 100644 examples/library/src/main/java/com/yworks/example/Functional.java create mode 100644 examples/library/src/main/java/com/yworks/example/HelloWorld.java create mode 100644 examples/library/src/main/java/com/yworks/example/Reducible.java diff --git a/examples/library/build.gradle b/examples/library/build.gradle new file mode 100644 index 00000000..4e87c449 --- /dev/null +++ b/examples/library/build.gradle @@ -0,0 +1,61 @@ +plugins { + // Apply the java and library plugin to add support for Java + id 'application' +} + +application { + mainClassName = 'com.yworks.example.HelloWorld' +} + +compileJava { + sourceCompatibility '1.7' + targetCompatibility '1.7' +} + +jar { + manifest { + attributes( + 'Main-Class': application.mainClassName + ) + } +} + +repositories { + mavenLocal() + mavenCentral() +} + +dependencies { + compile 'com.yworks:yguard:2.9.x' +} + +task yguard { + dependsOn jar + group 'yGuard' + description 'Obfuscates and shrinks the java archive.' + + doLast { + ant.taskdef( + name: 'yguard', + classname: 'com.yworks.yguard.YGuardTask', + classpath: sourceSets.main.runtimeClasspath.asPath + ) + + def archivePath = jar.archiveFile.get().asFile.path + ant.yguard { + inoutpair(in: archivePath, out: archivePath.replace(".jar", "_obf.jar")) + // don't let the obfuscator remove the "Deprecated" attributes from the .class file entries + attribute(name: "Deprecated") + shrink(logfile: "${buildDir}/yshrink.log.xml") { + keep { + 'class'(classes: 'protected', methods: 'protected', fields: 'protected') + } + } + rename(mainclass: application.mainClassName, logfile: "${buildDir}/yguard.log.xml") { + keep { + 'class'(classes: 'protected', methods: 'protected', fields: 'protected') + } + } + } + } +} diff --git a/examples/library/build.xml b/examples/library/build.xml new file mode 100644 index 00000000..5556412f --- /dev/null +++ b/examples/library/build.xml @@ -0,0 +1,75 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/library/pom.xml b/examples/library/pom.xml new file mode 100644 index 00000000..94987a9a --- /dev/null +++ b/examples/library/pom.xml @@ -0,0 +1,81 @@ + + 4.0.0 + com.yworks.example + HelloWorld + jar + 1.0-SNAPSHOT + HelloWorld + http://maven.apache.org + + 1.7 + 1.7 + com.yworks.example.HelloWorld + + + + com.yworks + yguard + 2.9.x + compile + + + + + + maven-antrun-plugin + 1.8 + + + package + + run + + obfuscate + + + + + + + + + + + + + + + + + + + + + + + + + + + + org.apache.maven.plugins + maven-jar-plugin + 2.4 + + + + com.yworks.example.HelloWorld + + + + + + + diff --git a/examples/library/settings.gradle b/examples/library/settings.gradle new file mode 100644 index 00000000..835224ae --- /dev/null +++ b/examples/library/settings.gradle @@ -0,0 +1 @@ +rootProject.name = 'library' diff --git a/examples/library/src/main/java/com/yworks/example/Functional.java b/examples/library/src/main/java/com/yworks/example/Functional.java new file mode 100644 index 00000000..eca8a513 --- /dev/null +++ b/examples/library/src/main/java/com/yworks/example/Functional.java @@ -0,0 +1,30 @@ +package com.yworks.example; + +import java.util.List; + +/** + * Offers functional utilities based on list folding + * @param - a number type to fold + * @deprecated You should use java.util.functional and stream.reduce in Java 8 + */ +@Deprecated +public class Functional { + protected T fold( Reducible func, List list) { + if (list.size() > 1) { + return func.call(list.get(0), fold(func, list.subList(1, list.size() - 1))); + } else { + return list.get(0); + } + } + + protected T sum(List list) { + class SumReducible implements Reducible { + public T call(T a, T b) { + Double sum = a.doubleValue() + b.doubleValue(); + return (T) sum; + } + } + + return fold(new SumReducible(), list); + } +} diff --git a/examples/library/src/main/java/com/yworks/example/HelloWorld.java b/examples/library/src/main/java/com/yworks/example/HelloWorld.java new file mode 100644 index 00000000..51893934 --- /dev/null +++ b/examples/library/src/main/java/com/yworks/example/HelloWorld.java @@ -0,0 +1,15 @@ +package com.yworks.example; + +import java.util.ArrayList; +import java.util.List; + +public class HelloWorld { + public static void main(String[] args) { + List integers = new ArrayList<>(); + integers.add(1); + integers.add(2); + integers.add(3); + Functional functional = new Functional<>(); + assert(functional.sum(integers) == 6); + } +} diff --git a/examples/library/src/main/java/com/yworks/example/Reducible.java b/examples/library/src/main/java/com/yworks/example/Reducible.java new file mode 100644 index 00000000..91412e1c --- /dev/null +++ b/examples/library/src/main/java/com/yworks/example/Reducible.java @@ -0,0 +1,12 @@ +package com.yworks.example; + + +/** + * A Callable of type T that takes two T as an argument and reduces them + * @param - the type to apply callable to + * @deprecated java.util.function should be used instead if Java 8 is available + */ +@Deprecated +public interface Reducible { + public T call(T a, T b); +} From 1f4f04c7e9de76c1fa62ea47a83bccecbdc32dbe Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Wed, 6 Nov 2019 16:38:15 +0100 Subject: [PATCH 22/38] Add README for examples. --- examples/README.md | 40 +++++++++++++++++++++++++++++++ examples/application/README.md | 4 ++++ examples/application/build.gradle | 2 +- examples/library/README.md | 7 ++++++ examples/library/build.gradle | 2 +- 5 files changed, 53 insertions(+), 2 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/application/README.md create mode 100644 examples/library/README.md diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..08342609 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,40 @@ +examples +-------- + +This folder contains various examples for setting up `yGuard` in different scenarios. + +- [application](application/) (a very basic setup. Simple program with one main method and no other exposed functionality.) +- [library](library/) (library example, illustrating how to expose specific parts of a library.) + +## Building a example + +All examples can be built using all major build systems. Build instructions cane be found below, depending on your build system of choice. + +### Compiling with `Gradle` + +``` +gradle build obfuscate +cd build/libs/ +java -jar example.jar +java -jar example_obf.jar # behaves identically +``` + +### Compiling with `Maven` + +``` +mvn compile package +cd target/ +java -jar HelloWorld-1.0-SNAPSHOT.jar +java -jar HelloWorld-1.0-SNAPSHOT_obfuscated.jar # behaves identically +``` + +### Compiling with `Ant` + + +``` +cd ../../ +gradle assembleBundleDist # this is a prerequisite for running the ant task and will produce a yguard-bundle-2.9.x.zip + +cd examples/example +ant run # will directly run the obfuscated version +``` diff --git a/examples/application/README.md b/examples/application/README.md new file mode 100644 index 00000000..8913867b --- /dev/null +++ b/examples/application/README.md @@ -0,0 +1,4 @@ +application +----------- + +This example demonstrates how to create a program that can be ran from a `JAR` archive using `java -jar HelloWorld.jar`. diff --git a/examples/application/build.gradle b/examples/application/build.gradle index cb01cd34..527fb2b1 100644 --- a/examples/application/build.gradle +++ b/examples/application/build.gradle @@ -24,7 +24,7 @@ dependencies { compile 'com.yworks:yguard:2.9.x' } -task yguard { +task obfuscate { dependsOn jar group 'yGuard' description 'Obfuscates and shrinks the java archive.' diff --git a/examples/library/README.md b/examples/library/README.md new file mode 100644 index 00000000..e680cf8d --- /dev/null +++ b/examples/library/README.md @@ -0,0 +1,7 @@ +library +------- + +This case is especially useful if you'd like to provide and expose a public API. + +All the classes, methods and fields, that can be seen in a javadoc generated API will be excluded from the shrinking and renaming tasks. Package friendly and private classes, methods and fields will be shrinked or obfuscated whenever possible. +This example also displays the use of the `attribute` element. In this case it prevents the yguard task from removing the `Deprecated` flag from the entities in the `.class` files. diff --git a/examples/library/build.gradle b/examples/library/build.gradle index 4e87c449..d84283ea 100644 --- a/examples/library/build.gradle +++ b/examples/library/build.gradle @@ -29,7 +29,7 @@ dependencies { compile 'com.yworks:yguard:2.9.x' } -task yguard { +task obfuscate { dependsOn jar group 'yGuard' description 'Obfuscates and shrinks the java archive.' From c6407653a6fe466ad9c07877269005fd913a346f Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Wed, 6 Nov 2019 17:42:23 +0100 Subject: [PATCH 23/38] Add external_library example. --- examples/external_library/README.md | 24 ++++ examples/external_library/build.gradle | 73 ++++++++++++ examples/external_library/build.xml | 94 +++++++++++++++ examples/external_library/pom.xml | 109 ++++++++++++++++++ examples/external_library/settings.gradle | 1 + .../java/com/yworks/example/HelloWorld.java | 14 +++ 6 files changed, 315 insertions(+) create mode 100644 examples/external_library/README.md create mode 100644 examples/external_library/build.gradle create mode 100644 examples/external_library/build.xml create mode 100644 examples/external_library/pom.xml create mode 100644 examples/external_library/settings.gradle create mode 100644 examples/external_library/src/main/java/com/yworks/example/HelloWorld.java diff --git a/examples/external_library/README.md b/examples/external_library/README.md new file mode 100644 index 00000000..e5832433 --- /dev/null +++ b/examples/external_library/README.md @@ -0,0 +1,24 @@ +external_library +---------------- + +This example demonstrates full method and field obfuscation for a program, that has external dependencies. + +The dependencies are specified in the externalclasses element using standard Ant path specification mechanisms. Classes residing in `lib/gson.jar` will be used to resolve external dependencies during the obfuscation run. + +This is necessary if external classes want to access obfuscated classes directly using an externally defined interface or superclass. + +yGuard automatically detects externally declared methods and prevents renaming and shrinking of these items. + +As a result, the shrinked and obfuscated jar file can be used together with unmodified versions of external libraries without causing any problems. + +This example also demonstrates the use of the `error-checking` property. In this case the Ant target fails if any problem is detected during the obfuscation run. + +### Executing the archive with `mvn` + +For `mvn`, in order to make the resulting archives work you need to additionally: + +- enable the `addClasspath` in the `maven-jar-plugin` +- enable the `maven-dependency-plugin` +- execute the library with additional classpath like so: `java -cp "HelloWorld-1.0-SNAPSHOT_obfuscated.jar:alternateLocation/*" com.yworks.example.HelloWorld` + +This will add the `gson.jar` to the execution path. If you handle this differently in your setup (e.g compiling a _fat_ JAR), you can safely ignore this code. diff --git a/examples/external_library/build.gradle b/examples/external_library/build.gradle new file mode 100644 index 00000000..93c0b2e3 --- /dev/null +++ b/examples/external_library/build.gradle @@ -0,0 +1,73 @@ +plugins { + // Apply the java and library plugin to add support for Java + id 'application' +} + +application { + mainClassName = 'com.yworks.example.HelloWorld' +} + +compileJava { + sourceCompatibility '1.7' + targetCompatibility '1.7' +} + +jar { + manifest { + attributes( + 'Main-Class': application.mainClassName + ) + } +} + +repositories { + mavenLocal() + mavenCentral() +} + +configurations { + gson +} + +dependencies { + compile 'com.yworks:yguard:2.9.x' + gson 'com.google.code.gson:gson:2.8.6' + implementation configurations.gson.dependencies +} + +task obfuscate { + dependsOn jar + group 'yGuard' + description 'Obfuscates and shrinks the java archive.' + + doLast { + ant.taskdef( + name: 'yguard', + classname: 'com.yworks.yguard.YGuardTask', + classpath: sourceSets.main.runtimeClasspath.asPath + ) + + def archivePath = jar.archiveFile.get().asFile.path + ant.yguard { + inoutpair(in: archivePath, out: archivePath.replace(".jar", "_obf.jar")) + + externalclasses { + pathelement(location: configurations.gson.asPath) + } + shrink(logfile: "${buildDir}/yshrink.log.xml") { + property(name: "error-checking", value: "pedantic") + keep { + method(name: "void main(java.lang.String[])", "class": "com.yworks.example.HelloWorld") + 'class'(classes: 'public') + } + } + rename(mainclass: application.mainClassName, logfile: "${buildDir}/yguard.log.xml") { + property(name: "error-checking", value: "pedantic") + + keep { + 'class'(classes: 'public') + } + } + } + } +} diff --git a/examples/external_library/build.xml b/examples/external_library/build.xml new file mode 100644 index 00000000..6b67800c --- /dev/null +++ b/examples/external_library/build.xml @@ -0,0 +1,94 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/external_library/pom.xml b/examples/external_library/pom.xml new file mode 100644 index 00000000..23bd3aed --- /dev/null +++ b/examples/external_library/pom.xml @@ -0,0 +1,109 @@ + + 4.0.0 + com.yworks.example + HelloWorld + jar + 1.0-SNAPSHOT + HelloWorld + http://maven.apache.org + + 1.7 + 1.7 + com.yworks.example.HelloWorld + + + + com.yworks + yguard + 2.9.x + compile + + + + com.google.code.gson + gson + 2.8.6 + compile + + + + + + maven-antrun-plugin + 1.8 + + + package + + run + + obfuscate + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + org.apache.maven.plugins + maven-jar-plugin + 2.4 + + + + com.yworks.example.HelloWorld + + + + + + + + + diff --git a/examples/external_library/settings.gradle b/examples/external_library/settings.gradle new file mode 100644 index 00000000..23f31d99 --- /dev/null +++ b/examples/external_library/settings.gradle @@ -0,0 +1 @@ +rootProject.name = 'external_library' diff --git a/examples/external_library/src/main/java/com/yworks/example/HelloWorld.java b/examples/external_library/src/main/java/com/yworks/example/HelloWorld.java new file mode 100644 index 00000000..92e47f2b --- /dev/null +++ b/examples/external_library/src/main/java/com/yworks/example/HelloWorld.java @@ -0,0 +1,14 @@ +package com.yworks.example; + +import com.google.gson.Gson; + +import java.util.Arrays; + +public class HelloWorld { + public static void main(String[] args) { + String document = "[\"hello\",\"world\",\"using\",\"a\",\"JSON\",\"deserializer\"]"; + Gson gson = new Gson(); + String[] elements = gson.fromJson(document, String[].class); + System.out.println(Arrays.asList(elements)); + } +} From bf44bba6243d2692e16807e245d0273cdf6f5ff2 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 11 Nov 2019 14:14:04 +0100 Subject: [PATCH 24/38] Add resources example. --- examples/resources/README.md | 10 +++ examples/resources/build.gradle | 66 ++++++++++++++ examples/resources/build.xml | 83 ++++++++++++++++++ examples/resources/pom.xml | 86 +++++++++++++++++++ examples/resources/settings.gradle | 1 + .../java/com/yworks/example/HelloWorld.java | 26 ++++++ .../com/yworks/example/HelloWorld.properties | 1 + 7 files changed, 273 insertions(+) create mode 100644 examples/resources/README.md create mode 100644 examples/resources/build.gradle create mode 100644 examples/resources/build.xml create mode 100644 examples/resources/pom.xml create mode 100644 examples/resources/settings.gradle create mode 100644 examples/resources/src/main/java/com/yworks/example/HelloWorld.java create mode 100644 examples/resources/src/main/resources/com/yworks/example/HelloWorld.properties diff --git a/examples/resources/README.md b/examples/resources/README.md new file mode 100644 index 00000000..7f849542 --- /dev/null +++ b/examples/resources/README.md @@ -0,0 +1,10 @@ +resources +--------- + +This example, demonstrates full method and field obfuscation for a program, that uses `.properties` files and other resources files. + +Some configuration files are used that contain fully qualified classnames for plugins that are going to be obfuscated. Therefore yGuard is instructed to automatically replace the plain-text entries in those files with the obfuscated name versions. + +Additionally some resources are hardcoded into the classes (image locations and html files, e.g.). yGuard gets instructed not to move these resource files even if they reside in a package structure that is obfuscated. + +Since the property files have been created with the same name as the classes that make use of them and they are being loaded using `this.getClass().getName()`, yGuard is configured to rename the `.properties` files according to the obfuscated names of the corresponding `.class` files. diff --git a/examples/resources/build.gradle b/examples/resources/build.gradle new file mode 100644 index 00000000..16e50489 --- /dev/null +++ b/examples/resources/build.gradle @@ -0,0 +1,66 @@ +plugins { + // Apply the java and library plugin to add support for Java + id 'application' +} + +application { + mainClassName = 'com.yworks.example.HelloWorld' +} + +jar { + manifest { + attributes( + 'Main-Class': application.mainClassName + ) + } +} + +repositories { + mavenLocal() + mavenCentral() +} + +dependencies { + compile 'com.yworks:yguard:2.9.x' +} + +task obfuscate { + dependsOn jar + group 'yGuard' + description 'Obfuscates and shrinks the java archive.' + + doLast { + ant.taskdef( + name: 'yguard', + classname: 'com.yworks.yguard.YGuardTask', + classpath: sourceSets.main.runtimeClasspath.asPath + ) + + def archivePath = jar.archiveFile.get().asFile.path + ant.yguard { + inoutpair(in: archivePath, out: archivePath.replace(".jar", "_obf.jar")) + shrink(logfile: "${buildDir}/yshrink.log.xml") { + keep { + method(name: "void main(java.lang.String[])", "class": application.mainClassName) + } + } + rename(mainclass: application.mainClassName, logfile: "${buildDir}/yguard.log.xml") { + adjust(replaceContent: true) { + // plain-text class names in the config files will + // be replaced with the obfuscated name versions + include(name: "**/*.properties") + } + adjust(replacePath: true) { + // keep the complete path to the resources even if + // package com.yworks.example gets obfuscated by name + include(name: "com/yworks/example/resources/*") + } + adjust(replaceName: true) { + // Replace the .properties files' names with the obfuscated + // versions if the corresponding .class files get obfuscated + include(name: "**/*.properties") + } + } + } + } +} diff --git a/examples/resources/build.xml b/examples/resources/build.xml new file mode 100644 index 00000000..d4e3044e --- /dev/null +++ b/examples/resources/build.xml @@ -0,0 +1,83 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/resources/pom.xml b/examples/resources/pom.xml new file mode 100644 index 00000000..0e54dafd --- /dev/null +++ b/examples/resources/pom.xml @@ -0,0 +1,86 @@ + + 4.0.0 + com.yworks.example + HelloWorld + jar + 1.0-SNAPSHOT + HelloWorld + http://maven.apache.org + + 1.7 + 1.7 + com.yworks.example.HelloWorld + + + + com.yworks + yguard + 2.9.x + compile + + + + + + maven-antrun-plugin + 1.8 + + + package + + run + + obfuscate + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + org.apache.maven.plugins + maven-jar-plugin + 2.4 + + + + com.yworks.example.HelloWorld + + + + + + + diff --git a/examples/resources/settings.gradle b/examples/resources/settings.gradle new file mode 100644 index 00000000..99f225e5 --- /dev/null +++ b/examples/resources/settings.gradle @@ -0,0 +1 @@ +rootProject.name = 'resources' diff --git a/examples/resources/src/main/java/com/yworks/example/HelloWorld.java b/examples/resources/src/main/java/com/yworks/example/HelloWorld.java new file mode 100644 index 00000000..e7bdb38c --- /dev/null +++ b/examples/resources/src/main/java/com/yworks/example/HelloWorld.java @@ -0,0 +1,26 @@ +package com.yworks.example; + +import java.io.FileNotFoundException; +import java.io.IOException; +import java.io.InputStream; +import java.util.Properties; + +public class HelloWorld { + public static void main(String args[]) { + HelloWorld helloWorld = new HelloWorld(); + String propertiesFileName = String.format("%s.properties", helloWorld.getClass().getSimpleName()); + + InputStream inputStream = helloWorld.getClass().getResourceAsStream(propertiesFileName); + if (inputStream != null) { + Properties properties = new Properties(); + try { + properties.load(inputStream); + System.out.println(String.format("Printing MESSAGE from properties: %s", properties.getProperty("MESSAGE"))); + } catch (IOException exception) { + System.err.println(exception.toString()); + } + } else { + System.err.println(String.format("Could not load file %s", propertiesFileName)); + } + } +} diff --git a/examples/resources/src/main/resources/com/yworks/example/HelloWorld.properties b/examples/resources/src/main/resources/com/yworks/example/HelloWorld.properties new file mode 100644 index 00000000..41721f58 --- /dev/null +++ b/examples/resources/src/main/resources/com/yworks/example/HelloWorld.properties @@ -0,0 +1 @@ +MESSAGE=Hello World From bfc81789fa784b8c7b9a1694a53039e2e9f57725 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 11 Nov 2019 15:10:37 +0100 Subject: [PATCH 25/38] Import remaining example markdown. --- docs/task_documentation.md | 8 +- examples/README.md | 7 +- examples/annotation/README.md | 298 ++++++++++++++++++++++ examples/demo_program/build.xml | 52 ++++ examples/linked_library/README.md | 47 ++++ examples/serializable_exclusion/README.md | 35 +++ 6 files changed, 442 insertions(+), 5 deletions(-) create mode 100644 examples/annotation/README.md create mode 100644 examples/demo_program/build.xml create mode 100644 examples/linked_library/README.md create mode 100644 examples/serializable_exclusion/README.md diff --git a/docs/task_documentation.md b/docs/task_documentation.md index 1a42730a..18128231 100644 --- a/docs/task_documentation.md +++ b/docs/task_documentation.md @@ -191,7 +191,7 @@ Additionally or alternatively to `inoutpair` elements this element can be specif ``` ## The `externalclasses` Element -If the jar to be processed by `yGuard` depends on external classes or libraries, this element can be used to specify classpaths to these entities. These libraries will neither be shrinked nor obfuscated. Use the `inoutpair` element for this purpose! See [external-example] for an example of when to use this element. +If the jar to be processed by `yGuard` depends on external classes or libraries, this element can be used to specify classpaths to these entities. These libraries will neither be shrinked nor obfuscated. Use the `inoutpair` element for this purpose! See the `external_library` example for an example of when to use this element. In order to achieve a maximum shrinking effect by the `shrink` task, all external dependencies should be declared in the `externalclasses` element. Otherwise, all non-private methods of classes that inherit from unresolvable classes will not be shrinked. The elements attributes and child elements can be seen on the [Ant documentation page about using path elements](http://ant.apache.org/manual/using.html#path). @@ -199,7 +199,7 @@ The elements attributes and child elements can be seen on the [Ant documentation ## The attribute Element Using the `attribute` element, you can specify which attributes present in the input classes should be kept in the obfuscated output classes. -See [linked example] for an example of when to use this element. +See the `linked_example` for an example of when to use this element. #### Attributes @@ -814,7 +814,7 @@ The `classes`, `methods` and `fields` attributes tell the shrinking and renaming all classes that equal or extend the class defined by the given fully qualified classname.
      - See example 7 for an example usage of this + See serializable_example for an example usage of this attribute.       		No No
      + + + + + + + + + + + + + + + + + + + + + + +
      ElementObfuscated?
      class PersonNo
      field nameYes
      field occupationYes
      field ageNo
      + +The table above shows the result of the obfuscation of this example. The _Person_ class is annotated to be excluded from the obfuscation, but the _applyToMembers_ attribute is set to false, which means that the child elements of the class (the String and int fields) do not inherit this setting from its parent. The _name_ and _occupation_ fields are not annotated and do not inherit the annotation configuration from their parent, so they are obfuscated. The _age_ field however is also annotated to be excluded from obfuscation and thus keeps its name. + +## Obfuscation Exclusion for Members Using applyToMembers + +```java +@com.yworks.util.annotation.Obfuscation( exclude = true, applyToMembers = true) +public class Person { + + @com.yworks.util.annotation.Obfuscation( exclude = false ) + public String name; + + public String occupation; + + public int age; +} +``` + +#### Obfuscation + + + + + + + + + + + + + + + + + + + + + + + + +
      ElementObfuscated?
      class PersonNo
      field nameYes
      field occupationNo
      field ageNo
      + +Again, the class _Person_ keeps its name, but the configuration is inherited by its members, too. The fields _occupation_ and _age_ have no annotation set and inherit the configuration of its parent, which is exclude = true, so they keep their names. The field _name_ however specifies its own annotation and thus overrides the configuration of its parent and sets its own exclusion to false, so it is obfuscated. + +## Obfuscation Exclusion for Members using applyToMembers in the Case of Nested Classes + +```java +@Obfuscation ( exclude = true, applyToMembers = true ) +public class Person { + + public String name; + + public String occupation; + + public int age; + + @Obfuscation ( exclude = false, applyToMembers = true ) + class BirthInfo { + + String birthPlace; + + class Date { + + int year; + + int month; + + int day; + } + } +} +``` + +#### Obfuscation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ElementObfuscated?
      class PersonNo
      field nameNo
      field occupationNo
      field ageNo
      class BirthInfoYes
      field birthPlaceYes
      class DateYes
      field yearYes
      field monthYes
      field dayYes
      + +The `applyToMembers` configuration is also applicable to inner classes: In the above example, the top level class `Person` is annotated so that itself and all its members should be excluded from obfuscation. But, the inner class `BirthInfo` overrides this configuration by setting exclude to false for itself and all of its members. When yGuard has to decide whether to keep or obfuscate a non-annotated element, then it will look for annotations by going up the nesting-hierarchy until the top level class is reached or a parent has the `applyToMembers` configuration set to true. In this case, when deciding whether to keep the inner class `Date`, yGuard goes up the hierarchy and finds the annotation at `BirthInfo`, which is annotated `exclude = false`. This results in `Date` being obfuscated. The same applies to the members of `Date`. + +## Obfuscation Exclusion Using applyToMembers in the Case of Nested Classes II + +```java +@Obfuscation ( exclude = true, applyToMembers = true ) +public class Person { + + public String name; + + public String occupation; + + public int age; + + @Obfuscation ( exclude = false, applyToMembers = false ) + class BirthInfo { + + String birthPlace; + + class Date { + + int year; + + int month; + + int day; + } + } +} +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ElementObfuscated?
      class PersonNo
      field nameNo
      field occupationNo
      field ageNo
      class BirthInfoNo
      field birthPlaceNo
      class DateNo
      field yearNo
      field monthNo
      field dayNo
      + +The above example shows almost the same code as in Example 8.c, but this time the class BirthInfo has the applyToMembers annotation set to false. One might expect that, as a result, all members of BirthInfo are kept and only BirthInfo is obfuscated, but instead, all elements in this example are kept. The explanation: when reaching Date, yGuard is looking up its parent's configuration, BirthInfo, which has applyToMembers = false. yGuard then proceeds to the next parent class in the nesting-hierarchy, Person, which has applyToMembers = true and exclude = true set. This causes Date to be kept. But keeping a class also means that its fully qualified name and thus its nesting-hierarchy needs to be kept. Although the annotation of BirthInfo does not explicitly retain the the name of the class, the retention of Date and its nesting-hierarchy causes BirthInfo to be kept. + +## Default Behavior + +```java +public class Person { + + public String name; + + public String occupation; + + @com.yworks.util.annotation.Obfuscation + public int age; + +} +``` + +#### Annotation + + + + + + + + + + + + + + + + + + + + + + + + +
      ElementObfuscated?
      class PersonYes
      field nameYes
      field occupationYes
      field ageNo
      + +This example shows the default behavior of yGuard without specifying an annotation and when not assigning the attributes of the annotation. Person, name and occupation are obfuscated, while age is annotated. The default value for exclude is true, so the field age is not obfuscated. diff --git a/examples/demo_program/build.xml b/examples/demo_program/build.xml new file mode 100644 index 00000000..cdad6d71 --- /dev/null +++ b/examples/demo_program/build.xml @@ -0,0 +1,52 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/examples/linked_library/README.md b/examples/linked_library/README.md new file mode 100644 index 00000000..678c4863 --- /dev/null +++ b/examples/linked_library/README.md @@ -0,0 +1,47 @@ +linked_library +-------------- + +``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +This example demonstrates almost no _method_, _class_, and _field_ obfuscation for a program, that has external dependencies and additionally depends on a third party library jar which has to be obfuscated before deployment. + +Only those parts that actually interface with the third party _jar_ in the `mylibconnector` package are being obfuscated. Nothing in the third party library jar will be exposed in the final application, everything will be obfuscated and the code in the open application that makes use of the third party jar will be adjusted. + +Note that the public part of the application will still be debuggable since all of the crucial attributes will be exposed for the open application part. +The dependencies are specified in the `externalclasses` element using standard [Ant path](http://ant.apache.org/manual/using.html#path) specification mechanisms. Classes residing in `lib/external.jar` will be used to resolve external dependencies during the obfuscation run. This is not strictly necessary in this case since the public API will be fully exposed, i.e. no methods which have been declared by interfaces or super class in external classes will be renamed. diff --git a/examples/serializable_exclusion/README.md b/examples/serializable_exclusion/README.md new file mode 100644 index 00000000..1e27a617 --- /dev/null +++ b/examples/serializable_exclusion/README.md @@ -0,0 +1,35 @@ +serializable_exclusion +---------------------- + +``` + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +This example demonstrates the usage of the *implements* and *extends* attributes of the *class* element. All Serializable classes are excluded from shrinking by using the implements attribute of the class element. + +Additionally, all classes that extend the base class for menu items, `org.myorg.myapp.MyMenuItem`, are defined as entrypoints for the shrinking engine using the extends attribute of the class element. The `readObject` and `writeObject` methods and the field `serialVersionUID` needed for serialization are excluded from name obfuscation as well. From 2b2bf202e339a069d543bf0ab18d27afbf981c4c Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Wed, 13 Nov 2019 20:42:34 +0100 Subject: [PATCH 26/38] Add continous integration workflow. --- .github/workflows/continous-integration.yml | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .github/workflows/continous-integration.yml diff --git a/.github/workflows/continous-integration.yml b/.github/workflows/continous-integration.yml new file mode 100644 index 00000000..ff46c753 --- /dev/null +++ b/.github/workflows/continous-integration.yml @@ -0,0 +1,9 @@ +name: Continous Integration + +on: [push, pull_request] +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@master + - uses: MrRamych/gradle-actions/openjdk-11@3.1 From db0de8a9783342267dde47d21296f66d7d01f0e9 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 11 Nov 2019 15:41:13 +0100 Subject: [PATCH 27/38] Add required fields for maven publication. --- build.gradle | 71 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 63 insertions(+), 8 deletions(-) diff --git a/build.gradle b/build.gradle index 31ebe4e6..6f78ce5a 100644 --- a/build.gradle +++ b/build.gradle @@ -64,14 +64,6 @@ distributions { from configurations.annotation from jar } - into("docs") { - from "$projectDir/docs" - filter { - line -> line - .replaceAll('@VERSION@', version) - .replaceAll('@VERSION_MAJOR@', project.findProperty('VERSION_MAJOR')) - } - } } } } @@ -88,18 +80,81 @@ publishing { maven(MavenPublication) { artifactId = 'yguard' + pom { + developers { + developer { + id = 'berger' + name = 'Lennard Berger' + email = 'lennard.berger@yworks.com' + } + } + scm { + connection = 'scm:git:git://github.com/yWorks/yguard.git' + developerConnection = 'scm:git:ssh://github.com/yWorks/yguard.git' + url = 'https://github.com/yWorks/yguard' + } + licenses { + license { + name = 'The MIT License' + url = 'https://choosealicense.com/licenses/mit/' + } + } + } + from project.components.java } annotation(MavenPublication) { artifactId = 'annotation' + pom { + developers { + developer { + id = 'berger' + name = 'Lennard Berger' + email = 'lennard.berger@yworks.com' + } + } + scm { + connection = 'scm:git:git://github.com/yWorks/yguard.git' + developerConnection = 'scm:git:ssh://github.com/yWorks/yguard.git' + url = 'https://github.com/yWorks/yguard' + } + licenses { + license { + name = 'The MIT License' + url = 'https://choosealicense.com/licenses/mit/' + } + } + } + from project(':annotation').components.java } retroguard(MavenPublication) { artifactId = 'retroguard' + pom { + developers { + developer { + id = 'berger' + name = 'Lennard Berger' + email = 'lennard.berger@yworks.com' + } + } + scm { + connection = 'scm:git:git://github.com/yWorks/yguard.git' + developerConnection = 'scm:git:ssh://github.com/yWorks/yguard.git' + url = 'https://github.com/yWorks/yguard' + } + licenses { + license { + name = 'GNU LESSER GENERAL PUBLIC LICENSE' + url = 'https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html' + } + } + } + from project('retroguard').components.java } } From cf59a6752593e2e9956aea6c88a40109c701ff91 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 11 Nov 2019 16:15:54 +0100 Subject: [PATCH 28/38] Add signing to publications. --- build.gradle | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/build.gradle b/build.gradle index 6f78ce5a..bc352999 100644 --- a/build.gradle +++ b/build.gradle @@ -3,8 +3,10 @@ plugins { id 'java-library-distribution' // Apply the maven plugin to add support for publications id 'maven-publish' + // Sign packages before sending them to Maven central + id 'signing' - // Apply yWorks coding style with editorconfig + // Apply yWorks coding style with editorconfig id 'org.ec4j.editorconfig' version '0.0.3' } @@ -77,7 +79,7 @@ check.dependsOn editorconfigCheck publishing { publications { - maven(MavenPublication) { + yguard(MavenPublication) { artifactId = 'yguard' pom { @@ -159,3 +161,9 @@ publishing { } } } + +signing { + sign publishing.publications.yguard + sign publishing.publications.annotation + sign publishing.publications.retroguard +} From 525d764f295d2ebe1a77a22a1fc5ba9324b3cdef Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 11 Nov 2019 16:20:17 +0100 Subject: [PATCH 29/38] Add name, description and url metadata. --- build.gradle | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/build.gradle b/build.gradle index bc352999..2d4a6b9f 100644 --- a/build.gradle +++ b/build.gradle @@ -83,6 +83,9 @@ publishing { artifactId = 'yguard' pom { + name = 'yguard' + description = 'The open-source Java obfuscation tool working with Ant and Gradle by yWorks - the diagramming experts' + url = 'https://github.com/yWorks/yGuard' developers { developer { id = 'berger' @@ -110,6 +113,9 @@ publishing { artifactId = 'annotation' pom { + name = 'annotation' + description = 'The open-source Java obfuscation tool working with Ant and Gradle by yWorks - the diagramming experts' + url = 'https://github.com/yWorks/yGuard' developers { developer { id = 'berger' @@ -137,6 +143,9 @@ publishing { artifactId = 'retroguard' pom { + name = 'retroguard' + description = 'The open-source Java obfuscation tool working with Ant and Gradle by yWorks - the diagramming experts' + url = 'https://github.com/yWorks/yGuard' developers { developer { id = 'berger' From d5cef3dde44647fed2599ad8013f7e10256dee8f Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 11 Nov 2019 16:29:16 +0100 Subject: [PATCH 30/38] Add sources and javadoc to com.yworks.yguard. --- build.gradle | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/build.gradle b/build.gradle index 2d4a6b9f..378cd00c 100644 --- a/build.gradle +++ b/build.gradle @@ -77,6 +77,21 @@ editorconfig { check.dependsOn editorconfigCheck +javadoc { + source = sourceSets.main.allJava + classpath = configurations.compileClasspath +} + +task yguardSourceJar(type: Jar) { + archiveClassifier = 'sources' + from sourceSets.main.allJava +} + +task yguardJavaDoc(type: Jar) { + archiveClassifier = 'javadoc' + from javadoc +} + publishing { publications { yguard(MavenPublication) { @@ -107,6 +122,8 @@ publishing { } from project.components.java + artifact yguardSourceJar + artifact yguardJavaDoc } annotation(MavenPublication) { From b244d704c3acd9b2ac84dbf90175c9281c128cd2 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 11 Nov 2019 16:52:43 +0100 Subject: [PATCH 31/38] Properly replace @VERSION@ string when building retroguard. Closes #33. --- retroguard/build.gradle | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/retroguard/build.gradle b/retroguard/build.gradle index 7c5f5df5..f64ff7ab 100644 --- a/retroguard/build.gradle +++ b/retroguard/build.gradle @@ -5,4 +5,16 @@ plugins { compileJava { sourceCompatibility = 1.7 targetCompatibility = 1.7 + source = "$buildDir/generated-src" } + +task generateSources(type: Copy) { + from 'src/main/java' + into "$buildDir/generated-src" + filter { + line -> line.replaceAll('@VERSION@', version) + } +} + +// Use generated sources +compileJava.dependsOn generateSources From 2ed709b8a6b36968f3195b797f0579f12aee53d8 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 18 Nov 2019 12:02:18 +0100 Subject: [PATCH 32/38] Add workflow to upload release assets with documentation. --- .github/workflows/bundle.yml | 52 ++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 .github/workflows/bundle.yml diff --git a/.github/workflows/bundle.yml b/.github/workflows/bundle.yml new file mode 100644 index 00000000..2a829bb2 --- /dev/null +++ b/.github/workflows/bundle.yml @@ -0,0 +1,52 @@ +name: Release bundle + +on: + push: + tags: + - '*' + +jobs: + bundle: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@master + - name: Get minor version + id: get_minor + run: echo ::set-output name=minor::$(echo ${GITHUB_REF:14}) # refs/tags/2.9. + - uses: MrRamych/gradle-actions/openjdk-11@3.1 + id: build_bundle + env: + ORG_GRADLE_PROJECT_VERSION_MINOR=${{ steps.outputs.get_minor.minor }} + with: + args: assembleBundleDist + - uses: actions/setup-ruby@v1 + id: build_docs + working-directory: ./docs + run: | + gem install jekyll bundler + bundle exec jekyll build + - name: Concat bundle and documentation + id: concat_bundle + working-directory: ./build/distributions + run: | + mkdir -p ${{ format('yguard-bundle-2.9.{0}', steps.outputs.get_minor.minor ) }} + cp -r ../../docs/_site ${{ format('yguard-bundle-2.9.{0}/docs', steps.outputs.get_minor.minor ) }} # copies generated documentation + zip -ur ${{ format('yguard-bundle-2.9.{0}.zip', steps.outputs.get_minor.minor ) }} ${{ format('yguard-bundle-2.9.{0}', steps.outputs.get_minor.minor ) }} # add generated documentation to existing bundle + - uses: actions/create-release@v1.0.0 + id: create_release + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ github.ref }} + release_name: Release ${{ github.ref }} + draft: true + prerelease: false + - uses: actions/upload-release-asset@v1.0.1 + id: upload-release_asset + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: ${{ format('./build/distributions/yguard-bundle-2.9.{0}.zip', steps.outputs.get_minor.minor ) }} + asset_name: ${{ format('yguard-bundle-2.9.{0}.zip', steps.outputs.get_minor.minor ) }} + asset_content_type: application/zip From 7b9fe2c449369a1c28e719c30c8a88dde013b536 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 18 Nov 2019 13:02:48 +0100 Subject: [PATCH 33/38] Disable GitHub actions for now. --- .github/workflows/{bundle.yml => bundle.yml.disabled} | 0 ...ntinous-integration.yml => continous-integration.yml.disabled} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{bundle.yml => bundle.yml.disabled} (100%) rename .github/workflows/{continous-integration.yml => continous-integration.yml.disabled} (100%) diff --git a/.github/workflows/bundle.yml b/.github/workflows/bundle.yml.disabled similarity index 100% rename from .github/workflows/bundle.yml rename to .github/workflows/bundle.yml.disabled diff --git a/.github/workflows/continous-integration.yml b/.github/workflows/continous-integration.yml.disabled similarity index 100% rename from .github/workflows/continous-integration.yml rename to .github/workflows/continous-integration.yml.disabled From 38c78bee638e84fe41df3826f98819387604a1f0 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 18 Nov 2019 13:40:33 +0100 Subject: [PATCH 34/38] Refactor gradle properties and add javadoc+sources for all publications. --- annotation/build.gradle | 16 ++++++++++ build.gradle | 69 +++++++++++++++++++++++------------------ gradle.properties | 15 +++++++++ retroguard/build.gradle | 15 +++++++++ 4 files changed, 84 insertions(+), 31 deletions(-) diff --git a/annotation/build.gradle b/annotation/build.gradle index 3e110f6e..0d3c5965 100644 --- a/annotation/build.gradle +++ b/annotation/build.gradle @@ -10,3 +10,19 @@ compileJava { jar { setArchivesBaseName('ObfuscationAnnotation') } + +javadoc { + source = sourceSets.main.allJava + classpath = configurations.compileClasspath +} + +task annotationSourceJar(type: Jar) { + archiveClassifier = 'sources' + from sourceSets.main.allJava +} + +task annotationJavaDoc(type: Jar) { + archiveClassifier = 'javadoc' + from javadoc +} + diff --git a/build.gradle b/build.gradle index 378cd00c..882938c3 100644 --- a/build.gradle +++ b/build.gradle @@ -98,25 +98,24 @@ publishing { artifactId = 'yguard' pom { - name = 'yguard' - description = 'The open-source Java obfuscation tool working with Ant and Gradle by yWorks - the diagramming experts' - url = 'https://github.com/yWorks/yGuard' + description = POM_DESCRIPTION + url = POM_URL developers { developer { - id = 'berger' - name = 'Lennard Berger' - email = 'lennard.berger@yworks.com' + id = POM_DEVELOPER_ID + name = POM_DEVELOPER_NAME + email = POM_DEVELOPER_EMAIL } } scm { - connection = 'scm:git:git://github.com/yWorks/yguard.git' - developerConnection = 'scm:git:ssh://github.com/yWorks/yguard.git' - url = 'https://github.com/yWorks/yguard' + connection = POM_SCM_CONNECTION + developerConnection = POM_SCM_DEV_CONNECTION + url = POM_SCM_URL } licenses { license { - name = 'The MIT License' - url = 'https://choosealicense.com/licenses/mit/' + name = POM_LICENCE_NAME + url = POM_LICENCE_URL } } } @@ -130,50 +129,56 @@ publishing { artifactId = 'annotation' pom { - name = 'annotation' - description = 'The open-source Java obfuscation tool working with Ant and Gradle by yWorks - the diagramming experts' - url = 'https://github.com/yWorks/yGuard' + description = POM_DESCRIPTION + url = POM_URL developers { developer { - id = 'berger' - name = 'Lennard Berger' - email = 'lennard.berger@yworks.com' + id = POM_DEVELOPER_ID + name = POM_DEVELOPER_NAME + email = POM_DEVELOPER_EMAIL } } scm { - connection = 'scm:git:git://github.com/yWorks/yguard.git' - developerConnection = 'scm:git:ssh://github.com/yWorks/yguard.git' - url = 'https://github.com/yWorks/yguard' + connection = POM_SCM_CONNECTION + developerConnection = POM_SCM_DEV_CONNECTION + url = POM_SCM_URL } licenses { license { - name = 'The MIT License' - url = 'https://choosealicense.com/licenses/mit/' + name = POM_LICENCE_NAME + url = POM_LICENCE_URL } } } from project(':annotation').components.java + artifact project(':annotation').annotationSourceJar + artifact project(':annotation').annotationJavaDoc } retroguard(MavenPublication) { artifactId = 'retroguard' pom { - name = 'retroguard' - description = 'The open-source Java obfuscation tool working with Ant and Gradle by yWorks - the diagramming experts' - url = 'https://github.com/yWorks/yGuard' + description = POM_DESCRIPTION + url = POM_URL developers { developer { - id = 'berger' - name = 'Lennard Berger' - email = 'lennard.berger@yworks.com' + id = POM_DEVELOPER_ID + name = POM_DEVELOPER_NAME + email = POM_DEVELOPER_EMAIL } } scm { - connection = 'scm:git:git://github.com/yWorks/yguard.git' - developerConnection = 'scm:git:ssh://github.com/yWorks/yguard.git' - url = 'https://github.com/yWorks/yguard' + connection = POM_SCM_CONNECTION + developerConnection = POM_SCM_DEV_CONNECTION + url = POM_SCM_URL + } + licenses { + license { + name = POM_LICENCE_NAME + url = POM_LICENCE_URL + } } licenses { license { @@ -184,6 +189,8 @@ publishing { } from project('retroguard').components.java + artifact project(':retroguard').retroguardSourceJar + artifact project(':retroguard').retroguardJavaDoc } } } diff --git a/gradle.properties b/gradle.properties index 8a50d96a..acada216 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,2 +1,17 @@ VERSION_MAJOR=2.9 VERSION_MINOR=x + +POM_DESCRIPTION=The open-source Java obfuscation tool working with Ant and Gradle by yWorks - the diagramming experts +POM_URL=https://github.com/yWorks/yGuard + +POM_SCM_CONNECTION=scm:git:git://github.com/yWorks/yGuard.git +POM_SCM_DEV_CONNECTION=scm:git:ssh://github.com/yWorks/yGuard.git +POM_SCM_URL=https://github.com/yWorks/yGuard + +POM_DEVELOPER_ID=berger +POM_DEVELOPER_NAME=Lennard Berger +POM_DEVELOPER_EMAIL=lennard.berger@yworks.com + +POM_LICENCE_NAME=MIT +POM_LICENCE_URL=https://opensource.org/licenses/mit-license.php +POM_LICENCE_DIST=repo diff --git a/retroguard/build.gradle b/retroguard/build.gradle index f64ff7ab..6b7ca0ea 100644 --- a/retroguard/build.gradle +++ b/retroguard/build.gradle @@ -18,3 +18,18 @@ task generateSources(type: Copy) { // Use generated sources compileJava.dependsOn generateSources + +javadoc { + source = sourceSets.main.allJava + classpath = configurations.compileClasspath +} + +task retroguardSourceJar(type: Jar) { + archiveClassifier = 'sources' + from sourceSets.main.allJava +} + +task retroguardJavaDoc(type: Jar) { + archiveClassifier = 'javadoc' + from javadoc +} From bd75d622cd399b979a9eaeacb0dace3d23773ce2 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 18 Nov 2019 14:16:41 +0100 Subject: [PATCH 35/38] Refactor Travis to deploy bundle and docs seperately. --- .travis.yml | 83 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 51 insertions(+), 32 deletions(-) diff --git a/.travis.yml b/.travis.yml index 80e3d7b8..19821390 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,32 +1,51 @@ -language: java -dist: bionic - -before_cache: -- rm -f $HOME/.gradle/caches/modules-2/modules-2.lock -- rm -fr $HOME/.gradle/caches/*/plugin-resolution/ - -cache: - directories: - - "$HOME/.gradle/caches/" - - "$HOME/.gradle/wrapper/" - -script: -- gradle clean check - -before_deploy: - - major=`echo $TRAVIS_TAG | cut -d. -f1` - - minor=`echo $TRAVIS_TAG | cut -d. -f2` - - revision=`echo $TRAVIS_TAG | cut -d. -f3` - - version_major=`echo ${major}.${minor}` - - gradle build - - gradle assembleBundleDist -PVERSION_MAJOR=${version_major} -PVERSION_MINOR=${revision} - -deploy: - provider: releases - draft: true - skip_cleanup: true - api_key: - secure: YxeU5GzokMXdEJqE0xpQGoOxBmJyhJA6O3y8Fl1uTGxvLCupIyTNv7AcBptCnK3YE7SHolFY9hmv9xSXVOJz+k6YqhP6k/7NAJ8TlKRatface5VDJ1zB463rGiaYdyYhJYz0jjO1j3aTHCapSGJuaBONvEQYuKh8yuR6i/GHKM1xo1hsrmU0GvSMFcMZmFN1r24JYBHFRupvEBeyo47qFNnP69XLN85lRRNy1YBVVWKPsUp/4KgU977gyxIjK1j0LlSXk/IfMh9aCQ6hly6kUa6azkKsEg6LGlc0UgHOdG6NIgsJlLT99f/YJczq2qxLPwZTT1P60A9Dp16CrVechNtiF9UulIJCXaiL9DENYB9HxmCwa+s4GtaGi/5xOcupnGgPhRYXiTM9N8J8Q5GpAKGc0yLh7dGNURi9YviJmo6uZ9YuYXB1mm+oieLi6vVoadLbGPpziX8H+j4fHKkru2QU4V73NegqAmzyOK9GdkzCT9Nqv2O55le80q16ubBrfYoyLdzOKmNo+6fY0w+pUTioZVXNovnz9vpuUR45ZBOD/3fn0kcd5YrFglpknyiJ0nLlA7TET4rDtmRqMULd23mXaNrNJf2WuCIh2AI9z3zoSeKjIFJ9YjOQzfSijM+amvVvfGNSphwGtlJhgcPOMZWSgIYuMLGLdqqnE9loQUc= - file: build/distributions/yguard-bundle-${TRAVIS_TAG}.zip - on: - tags: true +matrix: + include: + - stage: Unit tests + language: java + cache: bundler + script: gradle clean check + before_cache: + - rm -f $HOME/.gradle/caches/modules-2/modules-2.lock + - rm -fr $HOME/.gradle/caches/*/plugin-resolution/ + cache: + directories: + - "$HOME/.gradle/caches/" + - "$HOME/.gradle/wrapper/" + #- stage: documentation + # if: tag IS present + # language: ruby + # before_deploy: + # - gem install jekyll bundler + # - cd ./docs + # - bundle install + # - bundle exec jekyll build + # - cp -r _site yguard-docs-${TRAVIS_TAG} + # - zip -r yguard-docs-${TRAVIS_TAG}.zip yguard-docs-${TRAVIS_TAG} + # deploy: + # provider: releases + # skip_cleanup: true + # draft: true + # api_key: + # secure: YxeU5GzokMXdEJqE0xpQGoOxBmJyhJA6O3y8Fl1uTGxvLCupIyTNv7AcBptCnK3YE7SHolFY9hmv9xSXVOJz+k6YqhP6k/7NAJ8TlKRatface5VDJ1zB463rGiaYdyYhJYz0jjO1j3aTHCapSGJuaBONvEQYuKh8yuR6i/GHKM1xo1hsrmU0GvSMFcMZmFN1r24JYBHFRupvEBeyo47qFNnP69XLN85lRRNy1YBVVWKPsUp/4KgU977gyxIjK1j0LlSXk/IfMh9aCQ6hly6kUa6azkKsEg6LGlc0UgHOdG6NIgsJlLT99f/YJczq2qxLPwZTT1P60A9Dp16CrVechNtiF9UulIJCXaiL9DENYB9HxmCwa+s4GtaGi/5xOcupnGgPhRYXiTM9N8J8Q5GpAKGc0yLh7dGNURi9YviJmo6uZ9YuYXB1mm+oieLi6vVoadLbGPpziX8H+j4fHKkru2QU4V73NegqAmzyOK9GdkzCT9Nqv2O55le80q16ubBrfYoyLdzOKmNo+6fY0w+pUTioZVXNovnz9vpuUR45ZBOD/3fn0kcd5YrFglpknyiJ0nLlA7TET4rDtmRqMULd23mXaNrNJf2WuCIh2AI9z3zoSeKjIFJ9YjOQzfSijM+amvVvfGNSphwGtlJhgcPOMZWSgIYuMLGLdqqnE9loQUc= + # file: ./docs/yguard-docs-${TRAVIS_TAG}.zip + # on: + # tags: true + #- stage: bundle + # if: tag IS present + # language: java + # cache: bundler + # before_deploy: + # - major=`echo $TRAVIS_TAG | cut -d. -f1` + # - minor=`echo $TRAVIS_TAG | cut -d. -f2` + # - revision=`echo $TRAVIS_TAG | cut -d. -f3` + # - version_major=`echo ${major}.${minor}` + # - gradle clean assembleBundleDist -PVERSION_MAJOR=${version_major} -PVERSION_MINOR=${revision} + # deploy: + # provider: releases + # skip_cleanup: true + # draft: true + # api_key: + # secure: YxeU5GzokMXdEJqE0xpQGoOxBmJyhJA6O3y8Fl1uTGxvLCupIyTNv7AcBptCnK3YE7SHolFY9hmv9xSXVOJz+k6YqhP6k/7NAJ8TlKRatface5VDJ1zB463rGiaYdyYhJYz0jjO1j3aTHCapSGJuaBONvEQYuKh8yuR6i/GHKM1xo1hsrmU0GvSMFcMZmFN1r24JYBHFRupvEBeyo47qFNnP69XLN85lRRNy1YBVVWKPsUp/4KgU977gyxIjK1j0LlSXk/IfMh9aCQ6hly6kUa6azkKsEg6LGlc0UgHOdG6NIgsJlLT99f/YJczq2qxLPwZTT1P60A9Dp16CrVechNtiF9UulIJCXaiL9DENYB9HxmCwa+s4GtaGi/5xOcupnGgPhRYXiTM9N8J8Q5GpAKGc0yLh7dGNURi9YviJmo6uZ9YuYXB1mm+oieLi6vVoadLbGPpziX8H+j4fHKkru2QU4V73NegqAmzyOK9GdkzCT9Nqv2O55le80q16ubBrfYoyLdzOKmNo+6fY0w+pUTioZVXNovnz9vpuUR45ZBOD/3fn0kcd5YrFglpknyiJ0nLlA7TET4rDtmRqMULd23mXaNrNJf2WuCIh2AI9z3zoSeKjIFJ9YjOQzfSijM+amvVvfGNSphwGtlJhgcPOMZWSgIYuMLGLdqqnE9loQUc= + # file: ./build/distributions/yguard-bundle-${TRAVIS_TAG}.zip + # on: + # tags: true From cd69c41e3b63a3486820054a89eb0b0873a7f604 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 18 Nov 2019 15:29:43 +0100 Subject: [PATCH 36/38] Add missing name attribute to POM and update CHANGELOG. --- CHANGELOG.md | 9 +++++++++ build.gradle | 3 +++ 2 files changed, 12 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f6f2f2f6..75bce845 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.9.1] - 2019-11-18 +## Changed +- Use a Jekyll-based documentation instead of our own HTML + +## Added +- Added example projects for Gradle, Maven and Ant +- Added installation instructions for Gradle, Maven and Ant +- Published packages on Maven Central + ## [2.9.0] - 2019-10-17 ### Changed - Replaced legacy build system with Gradle. diff --git a/build.gradle b/build.gradle index 882938c3..035616ab 100644 --- a/build.gradle +++ b/build.gradle @@ -98,6 +98,7 @@ publishing { artifactId = 'yguard' pom { + name = 'yguard' description = POM_DESCRIPTION url = POM_URL developers { @@ -129,6 +130,7 @@ publishing { artifactId = 'annotation' pom { + name = 'annotation' description = POM_DESCRIPTION url = POM_URL developers { @@ -160,6 +162,7 @@ publishing { artifactId = 'retroguard' pom { + name = 'retroguard' description = POM_DESCRIPTION url = POM_URL developers { From 807daf93c2c63b25a47e76b556c9425ce760d3db Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 18 Nov 2019 15:44:55 +0100 Subject: [PATCH 37/38] Add Sonatype OSSRH repository. --- build.gradle | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/build.gradle b/build.gradle index 035616ab..aac150bd 100644 --- a/build.gradle +++ b/build.gradle @@ -93,6 +93,15 @@ task yguardJavaDoc(type: Jar) { } publishing { + repositories { + maven { + url 'https://oss.sonatype.org/service/local/staging/deploy/maven2' + credentials { + username SONATYPE_NEXUS_USERNAME + password SONATYPE_NEXUS_PASSWORD + } + } + } publications { yguard(MavenPublication) { artifactId = 'yguard' From 1c0f43a2a78e6ae04c829615ee362e07a9f781b1 Mon Sep 17 00:00:00 2001 From: Lennard Berger Date: Mon, 18 Nov 2019 15:50:14 +0100 Subject: [PATCH 38/38] Add default properties for sonatype. --- gradle.properties | 3 +++ 1 file changed, 3 insertions(+) diff --git a/gradle.properties b/gradle.properties index acada216..81940d86 100644 --- a/gradle.properties +++ b/gradle.properties @@ -15,3 +15,6 @@ POM_DEVELOPER_EMAIL=lennard.berger@yworks.com POM_LICENCE_NAME=MIT POM_LICENCE_URL=https://opensource.org/licenses/mit-license.php POM_LICENCE_DIST=repo + +SONATYPE_NEXUS_USERNAME= +SONATYPE_NEXUS_PASSWORD=