Documentation effort and various polishing fixes (#140)

* Restructure documentation layout

* Update readme formatting

* Update

* Fix links to images

* Update README

* Add note

* Layout the 'run' doc

* Refactor command line build instructions into their own doc

* fix subtitle

* Add documentation on how to run

* Update doc: build libgdx client

* Update build instructions

* New doc layout glsl-fuzz glsl-reduce

* Minor style fix

* Add note

* Brief intro to glsl-reduce.

* Fixed name of reducer class.

* Changed _ to - for reducer command line options, and replaced --reduce-everywhere with opposite --preserve-semantics option.

* Work on docs/glsl-fuzz-walkthrough.md.

* Small changes to glsl-fuzz-walkthrough.md

* Work on glsl-reduce-intro.md

* A different approach to the README. We should review it tomorrow.

* Update file hierarchy doc

* Various changes.

* Revert small tweak.

* More changes.

* A few more tweaks.

* Small change.

* Small fix.

* Made reduction-kind an optional argument, defaulting to CUSTOM.

* Changes to how reducer is invoked.

* Document shader family results in file system

* Start documentation of reducing shaders from command line.

* Document reduction results in file system

* Added files to be used for glsl-reduce walkthrough.

* Small tweaks

* glsl-fuzz-walkthrough: fix Vulkan shaders generate command.

* Ignore license headers for command wrappers in:

graphicsfuzz/src/main/scripts/examples/glsl-reduce/

* glsl-reduce walkthrough.

* Added license header.

* Added note so we do not forget comment.

* Append command-line build doc to developer doc

* WebUI: preserve-semantics on reference reduction and don't use network to communicate with the fuzzer service manager.

* check_headers.py: fix glsl-reduce-walkthrough

...ignore rules and add ./temp

* Rename token to worker

* Changes to docs from meeting.

* glsl-reduce documentation.

* Tweak to glsl-reduce manual.

* glsl-reduce documentation ready for others to try out.

* Working on glsl-reduce command line example.

* Layout of glsl-generate doc

* Edits to glsl-fuzz intro.

* Edits to glsl-fuzz walkthrough.

* Add doc for glsl-generate

* Fix python indentation: 4 spaces everywhere

* Hide the metric field from the WebUI. Remove "manageAPI" from the server URL args.

* More work on glsl-fuzz-walkthrough.md.

* Fix python indentation: 4 spaces everywhere

* Make example scripts executable. Remove lines in docs about making them executable.

* Typo.

* Tweaks to glsl-reduce-walkthrough.md

* More work on glsl-fuzz-walkthrough.md

* Work on glsl-fuzz-reduce.md

* Hyphenise generate-shader-family

* Fix python indentation

* Hyphenise reduce-spirv-opt-flags.py

* Hyphenise run-browser*

* Hyphenise run-shader-family*

* Remove run_spv_local.sh which is now superseded by vkrun.py

* Hyphenise worker-vk

* Remove depreciated deqp worker

* Rename worker-vk to glsl-to-spv-worker

* Adjust developer documentation so command line build instructions are one click away.

README.md

@@ -1,65 +1,46 @@
-
-Warning: this repository is a work-in-progress. Things may break while we transition this project to open source. This is not an officially supported Google product.
-
 # GraphicsFuzz
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Build Status](https://travis-ci.org/google/graphicsfuzz.svg?branch=master)](https://travis-ci.org/google/graphicsfuzz)
 
+## GraphicsFuzz is a testing framework for shader compilers
 
-## Introduction
-
-GraphicsFuzz is a testing framework for automatically finding and simplifying bugs in graphics shader compilers. Our tools currently manipulate GLSL shaders, but we can indirectly test other targets such as SPIR-V, HLSL and Metal. Our current priority is testing Vulkan drivers.
-
-* [Getting started](docs/getting_started.md)
-* [Developer getting started](docs/development.md)
-* [Contributing (requires Google CLA)](CONTRIBUTING.md)
-* [License (Apache 2.0)](LICENSE)
-
-## The problem
-
-A graphics driver takes a *shader program* as input and executes it on a GPU (graphics processing unit) to render an image.
-
-![shader program, to GPU, to image](docs/images/shader-gpu-image.png)
-
-Compiling and executing shaders is complex, and many graphics drivers are unreliable: a valid shader can lead to wrong images, driver errors or even security issues.
+GraphicsFuzz provides tools to automatically find and simplify bugs in graphics
+shader compilers. It operates on GLSL shaders, and uses
+glslangValidator and spirv-tools to additionally target SPIR-V.
 
-![shader program, to GPU, to crash](docs/images/shader-gpu-crash.png)
+## Tools
 
-## Automatically finding bugs
+* **glsl-reduce**: a stand-alone GLSL shader reducer
+* **glsl-fuzz**: a family of tools for testing GLSL shader compilers using randomized metamorphic testing
 
-We start with a *reference shader* that renders an image. The reference shader can be any shader you like, such as a high-value shader from a game or existing test suite.
+### glsl-reduce
 
-![reference, to GPU, to image](docs/images/reference-gpu-image.png)
+* [Introduction: my shader is being weird, now what?](docs/glsl-reduce-intro.md)
+* [glsl-reduce walkthrough](docs/glsl-reduce-walkthrough.md)
+* [glsl-reduce manual](docs/glsl-reduce.md)
+* [Developer documentation](docs/glsl-fuzz-develop.md)
 
-Shaders are programs, so by applying *semantics-preserving* source code transformations, we can obtain a shader with significantly different source code that still has the same effect.
+### glsl-fuzz
 
-![transformation example: wrapping a statement in a do-while-false loop](docs/images/transformation-example.png)
+* [How it works (high-level): metamorphic testing using glsl-fuzz](docs/glsl-fuzz-intro.md)
+* [glsl-fuzz walkthrough](docs/glsl-fuzz-walkthrough.md)
+* [glsl-generate manual](docs/glsl-fuzz-generate.md)
+* [glsl-reduce manual (for reducing fuzzed shaders)](docs/glsl-fuzz-reduce.md)
+* [Developer documentation](docs/glsl-fuzz-develop.md)
 
-For example, wrapping code in a single-iteration loop does not change the meaning (semantics) of a program. By applying various semantics-preserving transformations to the reference shader, we generate a family of *variant shaders*, where each variant must render the same image as the reference.
+## Get the GraphicsFuzz tools
 
-![reference and variants, to GPU, to many equivalent images](docs/images/variant-same.png)
 
-If a variant shader leads to a seriously different image (or a driver error), then we have found a graphics driver bug!
+* **Pre-built binaries** are available on the [GitHub releases page](docs/glsl-fuzz-releases.md)
+* [**Build instructions**](docs/glsl-fuzz-develop.md)
 
-![reference and one variant, to GPU, to two different images](docs/images/variant-bug-wrongimg.png)
 
-This approach is known as *metamorphic testing*.
+## Contribute
 
-## Reduction
-
-Finding bugs is not the end of the story: a variant shader that exposes a bug is typically very large (thousands of lines), full of code coming from the semantics-preserving transformations. Typically only a fraction of this code is needed to expose the bug.
-
-![Source code, the majority of which is highlighted in yellow, but parts of one statement are not highlighted.](docs/images/variant-haystack.png)
-
-Fortunately, our reducer is able to selectively reverse those transformations that are not relevant to the bug. After reduction, we obtain a small difference sufficient to expose the driver issue.
-
-![The same source code, the majority of which is highlighted in yellow and striked out, but parts of one statement remain.](docs/images/variant-reduced.png)
-
-The reduced variant *still exposes the bug*, and differs from the reference only slightly: this is a great starting point to isolate the root cause of the bug in the graphics driver.
-
-## Summary
-
-GraphicsFuzz finds bugs in graphics drivers by rendering families of semantically equivalent shaders, and looking for output discrepancies. This approach is known as *metamorphic testing*. For each bug, the reducer saves a lot of debugging time by producing a simpler *minimal-difference test case* that still exposes the bug.
+* [Contributing (requires Google CLA)](CONTRIBUTING.md)
+* [License (Apache 2.0)](LICENSE)
+* [Developer documentation](docs/glsl-fuzz-develop.md)
 
 ## Further reading
 
@@ -89,3 +70,5 @@ GraphicsFuzz finds bugs in graphics drivers by rendering families of semanticall
 
 * OOPSLA 2017: [Automated Testing of Graphics Shader Compilers](http://multicore.doc.ic.ac.uk/publications/oopsla-17.html)
 * Metamorphic [Testing Workshop at ICSE 2016: Metamorphic Testing for (Graphics) Compilers](http://multicore.doc.ic.ac.uk/publications/met-16.html)
+
+This is not an officially supported Google product.

build/travis/1-install-deps-travis.sh

@@ -47,7 +47,7 @@ tar xf "github-release_${GITHUB_RELEASE_TOOL_VERSION}_${GITHUB_RELEASE_TOOL_ARCH
 popd
 
 
-# Android SDK (host platform is linux, darwin, or windows).
+# Android SDK (ANDROID_HOST_PLATFORM must be set to linux, darwin, or windows).
 
 ANDROID_TOOLS_FILENAME="sdk-tools-${ANDROID_HOST_PLATFORM}-4333796.zip"
 ANDROID_NDK_FILENAME="android-ndk-r18b-${ANDROID_HOST_PLATFORM}-x86_64.zip"

build/travis/check_headers.py

@@ -49,7 +49,7 @@ def exclude_dirpath(f: str):
             "./gles-worker/gradle/wrapper",
             "./build/licenses",
             "./vulkan-worker/src/android/build",
-
+            "./temp"
         ]
 
 
@@ -74,6 +74,7 @@ def is_command_wrapper(f: str):
 def exclude_filepath(f: str):
     return \
         f.startswith("./python/src/main/python/drivers/") and is_command_wrapper(f) or \
+        f.startswith("./graphicsfuzz/src/main/scripts/examples/glsl-reduce-walkthrough/") and is_command_wrapper(f) or \
         f in [
             "./graphicsfuzz/src/main/scripts/server-static/shaders/shader.vert",
             "./server-static-public/src/main/files/server-static/runner_multi_template.html",

docs/android_networking_guide.md → docs/android-networking-guide.md

@@ -28,7 +28,7 @@ E.g. `192.168.0.4:8080`
 You may alternatively connect the device using a USB cable.
 In this case,
 you should install the Android platform tools,
-as described in the [Android notes section](development.md#Android_notes)
+as described in the [Android notes](android-notes.md)
 of the developer documentation, so that you have access to the `adb` tool.
 Then:
 

docs/android-notes.md

@@ -0,0 +1,56 @@
+# Android notes
+
+The Android SDK is needed for building and developing the
+OpenGL worker (gles-worker).
+
+The Android SDK and NDK are needed for building and developing the
+Vulkan worker (vulkan-worker).
+
+## Installing the Android SDK and NDK
+
+You can download and install the Android SDK
+(with Android Studio or stand-alone)
+from [https://developer.android.com/studio/#downloads](https://developer.android.com/studio/#downloads).
+You can then use Android Studio or the SDK manager
+to install missing packages and the Android NDK.
+
+**Alternatively**, you can install the exact configuration
+of the Android SDK and NDK that we use from the command line
+by following our
+[continuous integration script](../build/travis/1-install-deps-travis.sh);
+the download of the Android SDK starts about halfway down.
+You may need to set some environment variables as specified in the comments.
+
+Ensure that the `ANDROID_HOME=/path/to/android-sdk` and `ANDROID_NDK_HOME=$ANDROID_HOME/ndk-bundle` environment variables are set;
+you may need to open IntelliJ IDEA from the terminal depending on how
+you set the environment variables.
+
+You should also add the `android-sdk/platform-tools` directory 
+to your path so that you can use tools like `adb`.
+
+## Android networking
+
+See [Android networking guide](android-networking-guide.md).
+
+## Installing apps via `adb`
+
+Once you have `adb` on your path,
+you can install apps using:
+
+`adb install the-app.apk`
+
+## Other notes
+
+* On an Android device,
+open `Settings`, `About device`, and keep tapping build number until developer settings are enabled.
+The build number might be under a further `Software information` option.
+* In developer settings, enable `USB debugging` and `Stay awake`.
+* In security settings (which might be under `Lock screen and security`), enable installing apps from unknown sources.
+* You can download the android worker directly on the phone from the [releases page](glsl-fuzz-releases.md).
+* In IntelliJ, open `Android Monitor` to view log output.
+Enter `com.graphicsfuzz.` in the search text box and select `No filters` in the drop down.
+This will ensure you see output from all processes; our worker uses three processes on Android.
+* Press the back button on the device to exit the OpenGL worker app on Android. Pressing home or
+other buttons won't work, as the app tries to stay in the foreground.
+
+