Update manual (#321)

* Update manual

* Delete  and

---------

Co-authored-by: James Hamilton <[email protected]>

Author: tvoc-gs

README.md

@@ -57,9 +57,7 @@ bytecode:
 * It renames the remaining classes, fields, and methods using short
   meaningless names.
 
-The resulting applications and libraries are smaller, faster, and a bit better
-hardened against reverse engineering. ProGuard is very popular for Android
-development, but it also works for Java code in general.
+The resulting applications and libraries are smaller and faster.
 
 ## ❓ Getting Help
 If you have **usage or general questions** please ask them in the <a href="https://community.guardsquare.com/?utm_source=github&utm_medium=site-link&utm_campaign=github-community">**Guardsquare Community**.</a>  
@@ -69,129 +67,79 @@ Please use <a href="https://github.com/guardsquare/proguard/issues">**the issue
 
 ## 🚀 Quick Start
 
-ProGuard has its own Gradle plugin, allowing you to shrink, optimize and obfuscate Android projects. 
+### Command line
 
-### ProGuard Gradle Plugin
+First, download the latest release from [GitHub releases](https://github.com/Guardsquare/proguard/releases).
 
-You can apply the ProGuard Gradle plugin in AGP 4+ projects by following these steps:
+To run ProGuard, on Linux/MacOS, just type:
 
-1. Add a `classpath` dependency in your root level `build.gradle` file:
-
-```Groovy
-buildscript {
-    repositories {
-        google()       // For the Android Gradle plugin.
-        mavenCentral() // For the ProGuard Gradle Plugin and anything else.
-    }
-    dependencies {
-        classpath 'com.android.tools.build:gradle:x.y.z'    // The Android Gradle plugin.
-        classpath 'com.guardsquare:proguard-gradle:7.3.0'  // The ProGuard Gradle plugin.
-    }
-}
+```bash
+bin/proguard.sh <options...>
 ```
 
-2. Apply the `proguard` plugin after applying the Android Gradle plugin as shown below:
+or on Windows:
 
-```Groovy
- apply plugin: 'com.android.application'
- apply plugin: 'com.guardsquare.proguard'
 ```
-
-3. ProGuard expects unobfuscated class files as input. Therefore, other obfuscators such as R8 have to be disabled.
-
-```Groovy
-android {
-    ...
-    buildTypes {
-       release {
-          // Deactivate R8.
-          minifyEnabled false
-       }
-    }
-}
+bin\proguard <options...>
 ```
 
-4. Configure variants to be processed with ProGuard using the `proguard` block:
-
-```Groovy
-android {
-    ...
-}
+Typically, you'll put most options in a configuration file (say,
+`myconfig.pro`), and just call
 
-proguard {
-   configurations {
-      release {
-         defaultConfiguration 'proguard-android-optimize.txt'
-         configuration 'proguard-project.txt'
-      }
-   }
-}
+```bash
+bin/proguard.sh @myconfig.pro
 ```
+or on Windows:
 
-You can then build your application as usual:
-
-```shell
-gradle assembleRelease
+```
+bin\proguard @myconfig.pro
 ```
 
-The repository contains some sample configurations in the [examples](examples)
-directory. Notably, [examples/android](examples/android-plugin) has a small working
-Android project that applies the ProGuard Gradle plugin.
-
-### Integrated ProGuard (AGP < 7.0)
-
-If you have an older Android Gradle project you can enable ProGuard instead of the default R8 compiler:
-
-1. Disable R8 in your `gradle.properties`:
+All available options are described in the [Configuration section](../configuration/usage.md).
 
-```gradle
-android.enableR8=false
-android.enableR8.libraries=false
-```
+### Gradle Task
 
-2. Override the default version of ProGuard with the most recent one in your
-   main `build.gradle`:
+ProGuard can be run as a task in Gradle. Before you can use the proguard task, you have to make sure Gradle can
+find it in its class path at build time. One way is to add the following
+line to your **`build.gradle`** file which will download ProGuard from Maven Central:
 
-```gradle
+```Groovy
 buildscript {
-    //...
-    configurations.all {
-        resolutionStrategy {
-            dependencySubstitution {
-                substitute module('net.sf.proguard:proguard-gradle') with module('com.guardsquare:proguard-gradle:7.3.0')
-            }
-        }
+    repositories {
+        mavenCentral()
     }
-}
-```
-
-3. Enable minification as usual in your `build.gradle`:
-
-```gradle
-android {
-    //...
-    buildTypes {
-        release {
-            minifyEnabled   true
-            shrinkResources true
-            proguardFile getDefaultProguardFile('proguard-android-optimize.txt')
-            proguardFile 'proguard-project.txt'
-        }
+    dependencies {
+        classpath 'com.guardsquare:proguard-gradle:7.1.0'
     }
 }
 ```
 
-4. Add any necessary configuration to your `proguard-project.txt`.
+You can then define a task with configuration:
 
-You can then build your application as usual:
+```Groovy
+tasks.register('proguard', ProGuardTask) {
+    configuration file('proguard.pro')
+
+    injars(tasks.named('jar', Jar).flatMap { it.archiveFile })
+
+    // Automatically handle the Java version of this build.
+    if (System.getProperty('java.version').startsWith('1.')) {
+        // Before Java 9, the runtime classes were packaged in a single jar file.
+        libraryjars "${System.getProperty('java.home')}/lib/rt.jar"
+    } else {
+        // As of Java 9, the runtime classes are packaged in modular jmod files.
+        libraryjars "${System.getProperty('java.home')}/jmods/java.base.jmod", jarfilter: '!**.jar', filter: '!module-info.class'
+        //libraryjars "${System.getProperty('java.home')}/jmods/....."
+    }
 
-```shell
-gradle assembleRelease
+    verbose
+
+    outjars(layout.buildDirectory.file("libs/${baseCoordinates}-minified.jar"))
+}
 ```
 
-The repository contains some sample configurations in the [examples](examples)
-directory. Notably, [examples/android-agp3-agp4](examples/android-agp3-agp4) has a small working
-Android project that uses the old integration.
+The embedded configuration is much like a standard ProGuard
+configuration. You can find more details on the [Gradle setup page](setup/gradle.md#proguard).
 
 ## ✨ Features
 
@@ -205,8 +153,7 @@ inlining methods, propagating constants, removing unused parameters, etc.
 
 * The optimizations may also improve the performance of the application, by up
   to 20%. For Java virtual machines on servers and desktops, the difference
-  generally isn't noticeable. For the Dalvik virtual machine and ART on
-  Android devices, the difference can be worth it.
+  generally isn't noticeable.
 
 * ProGuard can also remove logging code, from applications and their
   libraries, without needing to change the source code &mdash; in fact,

docs/md/index.md

@@ -7,7 +7,7 @@ hardened against reverse engineering.
 
 Typical applications:
 
-- Reducing the size of Android apps for faster downloads, shorter startup
+- Reducing the size of apps for faster downloads, shorter startup
   times, and smaller memory footprints.
 - Optimizing code for better performance on mobile devices.
 

docs/md/FAQ.md renamed to docs/md/manual/FAQ.md

@@ -7,16 +7,15 @@ Shrinking programs such as **ProGuard** can analyze bytecode and remove unused
 classes, fields, and methods. The program remains functionally equivalent,
 including the information given in exception stack traces.
 
-## What is obfuscation? {: #obfuscation}
+## What is name obfuscation? {: #obfuscation}
 
 By default, compiled bytecode still contains a lot of debugging information:
 source file names, line numbers, field names, method names, argument names,
 variable names, etc. This information makes it straightforward to decompile
 the bytecode and reverse-engineer entire programs. Sometimes, this is not
-desirable. Obfuscators such as **ProGuard** can remove the debugging
+desirable. Shrinkers such as **ProGuard** can remove the debugging
 information and replace all names by meaningless character sequences, making
-it much harder to reverse-engineer the code. It further compacts the code as a
-bonus. The program remains functionally equivalent, except for the class
+apps smaller. The program remains functionally equivalent, except for the class
 names, method names, and line numbers given in exception stack traces.
 
 ## What is preverification? {: #preverification}
@@ -71,7 +70,7 @@ license can remain the same.
 
 ## Does ProGuard work with Java 2, 5,..., 15? {: #jdk1.4}
 
-Yes, **ProGuard** supports all JDKs from 1.1 up to and including 15. Java 2
+Yes, **ProGuard** supports all JDKs from 1.1 up to and including 19. Java 2
 introduced some small differences in the class file format. Java 5 added
 attributes for generics and for annotations. Java 6 introduced optional
 preverification attributes. Java 7 made preverification obligatory and
@@ -89,18 +88,21 @@ including Java Micro Edition. **ProGuard** then also performs the required
 preverification, producing more compact results than the traditional external
 preverifier.
 
-**ProGuard** also comes with an obfuscator plug-in for the JME Wireless
-Toolkit.
+## Does ProGuard Support Android Apps?
 
-## Does ProGuard work for Android apps?
+ProGuard no longer supports Android apps, and for shrinking & optimization
+we recommend using the default shrinker R8.
+R8 is distributed as part of the Android SDK, it's fast, and can shrink & optimize apps well.
 
-Yes. Google's dx and D8 compilers convert Java bytecode into the Dalvik
-bytecode that runs on Android devices. By preprocessing the original bytecode,
-**ProGuard** can significantly reduce the file sizes and boost the run-time
-performance of the code. It is distributed as part of the Android SDK.
+However, R8 is only a shrinker & optimizer and does not provide any security features.
+To protect your app we recommend using
 [**DexGuard**](http://www.guardsquare.com/dexguard), **ProGuard**'s
-closed-source sibling for Android, offers additional optimizations and more
-application protection.
+closed-source sibling for Android, which offers
+multiple levels of code hardening and RASP (runtime application self-protection) for mobile apps and SDKs.
+
+The **ProGuard** [keep rules configuration format](configuration/usage.md) is supported by R8,
+so you can use your R8, ProGuard and DexGuard keep rules interchangeably. 
+You can also make use of the [ProGuard Playground](https://playground.proguard.com) to visualize R8 rules.
 
 ## Does ProGuard have support for Ant? {: #ant}
 
@@ -109,21 +111,26 @@ your Ant build process. You can still use configurations in **ProGuard**'s own
 readable format. Alternatively, if you prefer XML, you can specify the
 equivalent XML configuration.
 
+See [Ant setup](manual/setup/ant.md) page for more information.
+
 ## Does ProGuard have support for Gradle? {: #gradle}
 
 Yes. **ProGuard** also provides a Gradle task, so that it integrates into your
 Gradle build process. You can specify configurations in **ProGuard**'s own
 format or embedded in the Groovy configuration.
 
+See [Gradle setup](manual/setup/gradle.md) page for more information.
+
 ## Does ProGuard have support for Maven? {: #maven}
 
-**ProGuard**'s jar files are also distributed as artefacts from the [Maven
-Central](http://search.maven.org/#search%7Cga%7C1%7Cg:%22com.guardsquare%22)
-repository. There are some third-party plugins that support **ProGuard**, such
-as the [android-maven-plugin](http://code.google.com/p/maven-android-plugin/)
-and the [IDFC Maven ProGuard Plug-in](http://mavenproguard.sourceforge.net/).
-[**DexGuard**](http://www.guardsquare.com/dexguard) also comes with a Maven
-plugin.
+While we don't officially provide a Maven integration and
+we cannot provide support there are solutions available,
+their offered functionality is not guaranteed by Guardsquare.
+
+Some open-source implementations:
+
+- [https://github.com/wvengen/proguard-maven-plugin](https://github.com/wvengen/proguard-maven-plugin)
+- [https://github.com/dingxin/proguard-maven-plugin](https://github.com/dingxin/proguard-maven-plugin)
 
 ## Does ProGuard come with a GUI? {: #gui}
 
@@ -195,9 +202,6 @@ is presented for each obfuscated method name that has an ambiguous reverse
 mapping. Please refer to the [ProGuard User Manual](manual/index.md) for more
 details.
 
-Erik André at Badoo has written a [tool to de-obfuscate HPROF memory
-dumps](https://techblog.badoo.com/blog/2014/10/08/deobfuscating-hprof-memory-dumps/).
-
 ## How is DexGuard different from ProGuard?
 
 [**DexGuard**](http://www.guardsquare.com/dexguard) is a commercial extension