Add initial decompilation test proof of concept

.github/workflows/maven.yml

@@ -10,16 +10,27 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up JDK 1.8
-      uses: actions/setup-java@v1
+    - name: Check out Git repository
+      uses: actions/checkout@v2
       with:
-        java-version: 1.8
-    - name: Cache local Maven repository
-      uses: actions/cache@v1
+        # Clone decompilation test data submodule
+        submodules: true
+
+    - name: Set up Java
+      uses: actions/setup-java@v2
       with:
-        path: ~/.m2
-        key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
-        restore-keys: ${{ runner.os }}-m2
-    - name: Build with Maven
+        distribution: temurin
+        java-version: 8
+        cache: maven
+
+    - id: maven-build
+      name: Build with Maven
       run: mvn --batch-mode --update-snapshots -Dgpg.skip=true clean verify
+
+    - name: Upload decompilation test failures artifact
+      # Only run when Maven build failed, see https://github.community/t/run-step-only-if-previous-step-failed/127124/3
+      if: failure() && steps.maven-build.outcome == 'failure'
+      uses: actions/upload-artifact@v2
+      with:
+        name: decompilation-test-failures-diff
+        path: target/cfr-test-failures-diff

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "decompilation-test/test-data"]
+	path = decompilation-test/test-data
+	url = https://github.com/Marcono1234/cfr_tests.git
+	branch = marcono1234/decompilation-test-poc

README.md

@@ -21,3 +21,28 @@ You can also download CFR from your favourite <a href="https://mvnrepository.com
 
 If you have an issue, please **_DO NOT_** include copyright materials.  I will have to delete your issue.
 
+# Building CFR
+
+Dead easy!
+
+Just ensure you have [Maven](https://maven.apache.org/) installed. Then `mvn compile` in the root directory of this project will get you what you need.
+
+Note: If you encounter a `maven-compiler-plugin...: Compilation failure` error while trying to compile the project then your `JAVA_HOME` environment variable is probably pointing to a JDK version that doesn't support `6` for the `source` or `target` compile options.
+Fix this by pointing `JAVA_HOME` to a JDK version that still supports compiling to Java 1.6 such as JDK 11. Also note, the version of Java on your `JAVA` may need to be greater than 1.6 if you are using Maven version `>=3.3.1` which requires Java 1.7. The best solution is to use JDK 8, 9, 10 or 11 for both your `PATH` and `JAVA_HOME`.
+
+The main class is `org.benf.cfr.reader.Main`, so once you've built, you can test it out (from `target/classes`)
+```
+java org.benf.cfr.reader.Main java.lang.Object
+```
+to get CFR to decompile `java.lang.Object`.
+
+
+## Decompilation tests
+
+As part of the Maven build automatic decompilation tests are performed, they verify that the current decompiled output of CFR matches the expected previous output. The test data (Java class and JAR files) are part of a separate Git repository; it is therefore necessary to clone this repository with `git clone --recurse-submodules`. The expected output and CFR test configuration is however part of this repository to allow altering it without having to modify the corresponding test data. The test data is in the `decompilation-test/test-data` directory, and the respective expected data is in the `decompilation-test/test-data-expected-output` directory (with a similar directory structure).
+
+The decompilation test is also performed by the GitHub workflow and in case of test failures the unified diff is available in a workflow artifact called "decompilation-test-failures-diff".
+
+The expected output is not the gold standard, it merely describes the currently expected output. There is nothing wrong with adjusting the expected output, if the changes to the decompilation results are reasonable.
+
+When adding new test data the system property `cfr.decompilation-test.create-missing` can be used (with `-D...` from command line) to automatically generate all missing expected test data based on the current CFR output. The tests will still fail then (to indicate that no previous expected data existed), but afterwards the generated data can be reviewed to verify that the CFR output is reasonable, and the tests will then pass.