Skip to content

Commit

Permalink
Update manual (#321)
Browse files Browse the repository at this point in the history 
* Update manual

* Delete  and

---------

Co-authored-by: James Hamilton <james.hamilton@guardsquare.com>
  • Loading branch information
@tvoc-gs @mrjameshamilton
tvoc-gs and mrjameshamilton committed Mar 2, 2023
1 parent 745a681 commit 764d35e
Show file tree
Hide file tree
Showing 43 changed files with 101 additions and 2,291 deletions.
149 changes: 48 additions & 101 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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

Expand All @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion docs/md/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
52 changes: 28 additions & 24 deletions docs/md/FAQ.md → docs/md/manual/FAQ.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down Expand Up @@ -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
Expand All @@ -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}

Expand All @@ -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}

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 764d35e

Please sign in to comment.