diff --git a/docs/index.md b/docs/index.md index dcd637d..77f0054 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,16 +9,16 @@ yGuard is brought to you by [yWorks GmbH](https://www.yworks.com/), creator of t ## Table of contents -- [Setup](setup.html) - - [Using `Ant`](setup.html#setup-using-ant) - - [Using `Maven`](setup.html#setup-using-maven) - - [Using `Gradle`](setup.html#setup-using-gradle) -- [Task documentation](task_documentation.html) +- [Setup](setup.md) + - [Using `Ant`](setup.md#setup-using-ant) + - [Using `Maven`](setup.md#setup-using-maven) + - [Using `Gradle`](setup.md#setup-using-gradle) +- [Task documentation](task_documentation.md) - [Examples](https://github.com/yWorks/yguard/tree/master/examples) -- [Troubleshooting](troubleshooting.html) -- [Compatibility](compatibility.html) -- [License](license.html) +- [Troubleshooting](troubleshooting.md) +- [Compatibility](compatibility.md) +- [License](license.md) ## 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_documentation.html) thoroughly before. We will do our best and try to answer your questions. +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_documentation.md) thoroughly before. We will do our best and try to answer your questions. diff --git a/docs/task_documentation.md b/docs/task_documentation.md index 08c8088..a6bc053 100644 --- a/docs/task_documentation.md +++ b/docs/task_documentation.md @@ -37,7 +37,7 @@ The `yguard` task contains two nested elements that perform the name obfuscation The `yguard` task is a container element for the `rename` and `shrink` task elements as well as configuration elements that are common to `rename` and `shrink`. Being a container element only, the `yguard` task does not perform any actions on its own, but needs a `rename` and/or `shrink` child element for name obfuscating and/or code shrinking. -Please see the [troubleshooting section](troubleshooting) to learn about common pitfalls when using name obfuscation and shrinking software. +Please see the [troubleshooting section](troubleshooting.md) to learn about common pitfalls when using name obfuscation and shrinking software. #### Attributes @@ -240,7 +240,7 @@ This will retain the attributes named _"SourceFile"_, _"LineNumberTable"_, and _ ## 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]() explanation of some common use cases. If your code uses reflection, please read the [troubleshooting](troubleshooting) section for information on this topic. +See the [examples]() explanation of some common use cases. If your code uses reflection, please read the [troubleshooting](troubleshooting.md) section for information on this topic. #### Attributes @@ -332,7 +332,7 @@ The `entrypointjar` element has no child elements. ``` ## 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. +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.md) 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. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 2d1b9c6..9bd94e2 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -4,10 +4,10 @@ There are a couple of things you should be aware of when obfuscating and shrinki 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_documentation.html#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](task_documentation.html#the-keep-element) element. -If your application is broken after using the `shrink` task, consider using the [createStubs](task_documentation.html#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_documentation.html#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. +- 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_documentation.md#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](task_documentation.md#the-keep-element) element. +If your application is broken after using the `shrink` task, consider using the [createStubs](task_documentation.md#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_documentation.md#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`.