1# ANGLE Orientation 2 3A basic guide to get up and running fixing bugs and performance issues in ANGLE. 4 5## First ANGLE Compile 6 7### Windows 8 9- Download and install 10 [Visual Studio 2017 Community](https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx). 11 Installing takes some time. 12 13- Take the time to register a Microsoft account, otherwise you'll get nagged to death. 14 15- Download and install Chromium's 16 [depot_tools](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up) 17 for building ANGLE. 18 19- Add the `depot_tools` dir to your system path. Open start menu, type "edit environment variables", 20 add it to PATH. 21 22- (recommended) Download and install [Git for Windows](http://gitforwindows.org/). 23 24- Open Git bash, head to C:/src and follow the steps on 25 [the ANGLE wiki](https://chromium.googlesource.com/angle/angle/+/master/doc/DevSetup.md#Development-setup-Getting-the-source) 26 to set up the ANGLE solution for the first time. 27 28- The VS 2017 solution will be in `c:/src/angle/out/sln/ANGLE.sln`. Open and let the installation 29 finish. **Important**: set indent style to spaces, not tabs! 30 31- Building should work at this point! 32 33- Try running `angle_end2end_tests`, `angle_unittests` or a sample program. 34 35- Useful VS extensions: 36 37 1. [Build Only Startup Project](https://marketplace.visualstudio.com/items?itemName=SenHarada.BuildOnlyStartupProject) 38 2. [SwitchStartupProject](https://marketplace.visualstudio.com/items?itemName=vs-publisher-141975.SwitchStartupProject) 39 3. [Smart CommandLine Arguments](https://www.visualstudiogallery.msdn.microsoft.com/535f79b1-fbe0-4b0a-a346-8cdf271ea071) 40 41### Linux 42 43- Download and install Chromium's 44 [depot_tools](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up) 45 for building ANGLE. 46 47- Ensure you add `depot_tools` to your bashrc as in the wiki link above. 48 49- Follow the steps on 50 [the ANGLE wiki](https://chromium.googlesource.com/angle/angle/+/master/doc/DevSetup.md#Development-setup-Getting-the-source) 51 to setup ANGLE's build. 52 53- Building should work at this point! Follow the steps on the Wiki. 54 55- Try running `angle_end2end_tests`, `angle_unittests` or a sample program. 56 57## Setting up the [drawElements testing suite](http://go/dEQP) 58 59- [Cherry](https://sites.google.com/a/google.com/deqp/cherry) is the UI for viewing test results. 60 ANGLE checks out a copy in `<angledir>/third_party/cherry`. 61 62- Follow the instructions in the 63 [installation README](https://android.googlesource.com/platform/external/cherry/+/refs/heads/master/README) 64 to get it running. On Windows, use 64-bit. 65 66- Read up on testing with 67 [dEQP on the ANGLE Wiki](https://chromium.googlesource.com/angle/angle/+/master/doc/dEQP.md). 68 69- Try running `angle_deqp_gles2_tests_no_gtest` with the flag 70 `--deqp-case=dEQP-GLES2.functional.negative_api.*` and load a test report in Cherry. 71 72- To use Cherry, browse to [http://localhost:8080/#/results](http://localhost:8080/#/results) and 73 click '**Import existing batch**', loading `TestResults.qpa`. Look for the qpa file in the 74 current working directory, or `<angledir>/src/tests` if you ran the tests from Visual Studio. 75 76- Note: we only use Cherry for viewing test output, not running the tests. On start, you may see 77 some runtime messages about unable to load case lists. These are safe to ignore. If you didn't 78 load the results URL directly, click the "**Results**" tab to find the Import button. 79 80## Profiling 81 82- You can use `scripts/perf_test_runner.py` to run any target of `./angle_perftests` (see script 83 source for details). 84 85### With Visual Studio 86 87- In Visual Studio 2017, look under Debug/Profiler/Performance Explorer/New Performance Session. 88 Right-click "Targets" and add `angle_perftests` as a Target Project. 89 90- Run `angle_perftests` with the flag `--gtest_filter=DrawCallPerfBenchmark.Run/d3d11_null` for 91 D3D11, `.../d3d9_null` for D3D9, `.../gl_null` for OpenGL and `.../vulkan_null` for Vulkan. 92 93- Make sure you close all open instances of Chrome, they use a lot of background CPU and GPU. In 94 fact, close every process and application you can. 95 96### Profiling with Visual Studio + Chrome 97 98- Install [Chrome Canary](https://www.google.com/chrome/browser/canary.html). 99 100- Canary's install dir is usually `%APPDATA%/Local/Google/Chrome SxS/Application` 101 102- Build ANGLE x64, Release, and run 'python scripts/update_canary_angle.py' to replace Canary's 103 ANGLE with your custom ANGLE. (Note: Canary must be closed) 104 105- Start Canary with `--gpu-startup-dialog --disable-gpu-sandbox`, wait for the dialog. 106 107- In Visual Studio, under Debug/Profiler, choose attach to process. 108 109- Attach to the Chrome GPU process, then immediately pause profiling. 110 111- **IMPORTANT:** Verify ANGLE details are correct in `about:gpu`. 112 113- In Canary, start your benchmark, then resume profiling, and exit when done. The report will load 114 automatically. 115 116## Bookmark the latest Khronos specs 117 118- [The GLES 2.0 Spec](https://www.khronos.org/registry/OpenGL/specs/es/2.0/es_full_spec_2.0.pdf) 119 120- [The GLES 3.0 Spec](https://www.khronos.org/registry/OpenGL/specs/es/3.0/es_spec_3.0.pdf) 121 122- [The GLES 3.1 Spec](https://www.khronos.org/registry/gles/specs/3.1/es_spec_3.1.pdf) 123 124- [The GLES Shading Language 1.00 Spec](https://www.khronos.org/files/opengles_shading_language.pdf) 125 126- [The GLES Shading Language 3.00 Spec](https://www.khronos.org/registry/gles/specs/3.0/GLSL_ES_Specification_3.00.4.pdf) 127 128- [The WebGL Specs](https://www.khronos.org/registry/webgl/specs/latest/) 129 130- [A modern desktop OpenGL Spec](https://www.opengl.org/registry/doc/glspec45.core.pdf) 131 (for reference) 132 133- [The Vulkan Spec](https://www.khronos.org/registry/vulkan/specs/1.0-wsi_extensions/html/vkspec.html) 134 135These specs can be found in the [OpenGL Registry](https://github.com/KhronosGroup/OpenGL-Registry) 136and the [Vulkan Docs](https://github.com/KhronosGroup/Vulkan-Docs) repositories as well. 137 138## Join Groups and Chats 139 140- Join the `#angle` channel in `chromium.slack.com`. 141 142### For Googlers 143 144- Join angle-team@ for access to many important emails and shared documents. 145 146- We have a Hangouts Chat channel. Ask for an invite. 147