Document build and test instructions.

CMakeLists.txt

@@ -81,6 +81,19 @@ endif()
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 
 ###########################################################
+# Initialize submodules
+###########################################################
+
+if(NOT EXISTS ${CMAKE_SOURCE_DIR}/third_party/googletest)
+    message(WARNING "
+  third_party/googletest submodule missing.
+  Running 'git submodule update --init' to download it:
+    ")
+
+    execute_process(COMMAND git submodule update --init)
+endif()
+
+###########################################################
 # Convenience macros
 ###########################################################
 

README.md

@@ -2,8 +2,29 @@
 
 [![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/swiftshader.svg?branch=master)](https://travis-ci.org/google/swiftshader) [![Build status](https://ci.appveyor.com/api/projects/status/yrmyvb34j22jg1uj?svg=true)](https://ci.appveyor.com/project/c0d1f1ed/swiftshader)
 
+Introduction
+------------
+
 SwiftShader is a high-performance CPU-based implementation of the OpenGL ES and Direct3D 9 graphics APIs<sup>1</sup><sup>2</sup>. Its goal is to provide hardware independence for advanced 3D graphics.
 
+Building
+--------
+
+SwiftShader libraries can be built for Windows, Linux, and Mac OS X.  
+Android and Chrome (OS) build environments are also supported.
+
+* **Visual Studio**
+  
+  On Windows, open the [SwiftShader.sln](SwiftShader.sln) file using [Visual Studio Community](https://visualstudio.microsoft.com/vs/community/) or compatible version, and build the solution. Output DLLs will be placed in the _lib_ subfolder. Sample executables such as _OGLES3ColourGrading_ can be found under the Tests solution folder and can be run from the IDE.
+
+* **CMake**
+
+  [Install CMake](https://cmake.org/download/) for Linux, Mac OS X, or Windows and use either [the IDE](https://cmake.org/runningcmake/) or run the following terminal commands:
+
+      mkdir build && cd build
+      cmake ..
+      make --jobs=8
+
 Usage
 -----
 
@@ -11,8 +32,6 @@ The SwiftShader libraries act as drop-in replacements for graphics drivers.
 
 On Windows, most applications can be made to use SwiftShader's DLLs by placing them in the same folder as the executable. On Linux, the LD\_LIBRARY\_PATH environment variable or -rpath linker option can be used to direct applications to search for shared libraries in the indicated directory first.
 
-Prebuilt binaries can be found at: https://goo.gl/5MOcdb
-
 Contributing
 ------------
 
@@ -32,10 +51,17 @@ https://gerrit-review.googlesource.com/tools/hooks/commit-msg. To clone the repo
 
     git clone https://swiftshader.googlesource.com/SwiftShader && (cd SwiftShader && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x `git rev-parse --git-dir`/hooks/commit-msg)
 
-Changes are uploaded to Gerrit by performing:
+Changes are uploaded to Gerrit by executing:
 
     git push origin HEAD:refs/for/master
 
+Testing
+-------
+
+SwiftShader's OpenGL ES implementation can be tested using the [dEQP](https://source.android.com/devices/graphics/testing) test suite.
+
+See [docs/dEQP.md](docs/dEQP.md) for details.
+
 Third-Party Dependencies
 ------------------------
 
@@ -61,7 +87,7 @@ Contact
 
 Public mailing list: [swiftshader@googlegroups.com](https://groups.google.com/forum/#!forum/swiftshader)
 
-General bug tracker:  https://issuetracker.google.com/issues?q=componentid:408190
+General bug tracker:  https://issuetracker.google.com/issues?q=componentid:408190  
 Chrome specific bugs: https://bugs.chromium.org/p/swiftshader
 
 License

docs/dEQP.md

+dEQP
+====
+
+These steps are specifically for testing SwiftShader's OpenGL ES 3.0 implementation using dEQP on Windows (Linux differences at the bottom).
+
+Prerequisites
+-------------
+
+1. Install the latest [Python 2.X](https://www.python.org/downloads/
+)
+2. Install [Visual Studio](https://visualstudio.microsoft.com/vs/community/)
+3. Install [CMake](https://cmake.org/download/)
+4. Install [Go](https://golang.org/doc/install
+) 32-bit (Important: must be 32 bit)
+5. Install [MinGW](http://www.mingw.org/)
+6. Install [Git](https://git-scm.com/download/win)
+7. Install [Android Studio](https://developer.android.com/studio/index.html)
+8. Run Android Studio and install Android SDK.
+9. Set environment variables: Config Panel -> System and Security -> System -> Advanced system settigns -> Environment Variables
+  * Add `<path to python>` to your PATH environment variable
+  * Add `<path to MinGW>\bin` to your PATH environment variable
+  * Add `<path to adb>` to your PATH environment variable 
+
+    Note: abd is in the Android SDK, typically in `C:\Users\<username>\AppData\Local\Android\sdk\platform-tools`
+
+10. Install GCC. In 'cmd', run:
+
+    `mingw-get install gcc`
+
+    Note: Using Cygwin GCC currently doesn't work.
+
+11. (Optional) Install [TortoiseGit](https://tortoisegit.org/)
+
+Getting the Code
+----------------
+
+12. Get dEQP (either in 'cmd' or by using TortoiseGit):
+
+    `git clone https://android.googlesource.com/platform/external/deqp`
+
+13. Get dEQP's dependencies. In your dEQP root directory, open 'cmd' and run:
+
+    `python external\fetch_sources.py`
+
+14. Get Cherry (either in 'cmd' or by using TortoiseGit):
+
+    `git clone https://android.googlesource.com/platform/external/cherry`
+
+15. Set environment variable (see point 9):
+
+    Add new variable GOPATH='`<path to cherry>`'
+
+Building the code
+-----------------
+
+16. Build dEQP's Visual Studio files using the CMake GUI, or, in the dEQP root dir, run:
+    ```
+    mkdir build 
+    cd build
+    cmake ..
+    ```
+    Note: If you have multiple versions of Visual Studio installed and you want to make sure cmake is using the correct version of Visual Studio, you can specify it by calling, for example:
+
+    `cmake .. -G "Visual Studio 15 2017 Win64"`
+
+    Also note: don't call 'cmake .' directly in the root directory. It will make things fails later on. If you do, simply erase the files created by CMake and follow the steps above.
+
+17. Build dEQP:
+
+    Open `<path to dEQP>\build\dEQP-Core-default.sln` in Visual Studio and Build Solution
+
+    Note: Choose a 'Release' build, unless you really mean to debug dEQP
+
+18. Generate test cases:
+    ```
+    mkdir <path to cherry>\data
+    cd <path to dEQP>
+    python scripts\build_caselists.py <path to cherry>\data
+    ```
+
+Preparing the server
+--------------------
+
+19. Edit `<path to cherry>\cherry\data.go`
+*  Search for `../candy-build/deqp-wgl` and replace that by `<path to deqp>/build`
+* Just above, add an option to CommandLine: `--deqp-gl-context-type=egl`
+* Just below, modify the BinaryPath from 'Debug' to 'Release' if you did a Release build at step 17
+
+Testing OpenGL ES
+-----------------
+
+20) Assuming you already built SwiftShader, copy these two files:
+
+    libEGL.dll  
+    libGLESv2.dll
+
+    From:
+
+    `<path to SwiftShader>\lib\Release_x64` or  
+    `<path to SwiftShader>\lib\Debug_x64`
+
+    To:
+
+    `<path to dEQP>\build\modules\gles3\Release` (Again, assuming you did a Release build at step 17)
+
+Running the tests
+-----------------
+
+21. Start the test server. Go to `<path to cherry>` and run:
+
+    `go run server.go`
+
+22. Open your favorite browser and navigate to `localhost:8080`
+
+    Get Started -> Choose Device 'localhost' -> Select Tests 'dEQP-GLES3' -> Execute tests!
+
+Mustpass sets
+-------------
+
+dEQP contains more tests than what is expected to pass by a conformant implementation (e.g. some tests are considered too strict, or assume certain undefined behavior). The [android\cts\master\gles3-master.txt](https://android.googlesource.com/platform/external/deqp/+/master/android/cts/master/gles3-master.txt) text file which can be loaded in Cherry's 'Test sets' tab to only run the latest tests expected to pass by certified Android devices.
+
+Running dEQP on Linux
+---------------------
+
+Differences to the steps above:
+
+1. Instead of copying the .dll files, you need to set LD_LIBRARY_PATH to point to SwiftShader's build directory.
+2. Use `make` instead of Visual Studio.
+3. There are no Debug/Release directories or .exe suffixes, so remove them from DeviceConfig in data.go.
\ No newline at end of file