Skip to content

A
angle
Commit 3c613c0d by Frank Henigman Committed by Jamie Madill
Options

Update docs for GN standalone and GYP deprecation.

Explain how to use GN and say not to use GYP. BUG=angleproject:1569 Change-Id: I972126dced28fa7a70eb301b500f172376a569c1 Reviewed-on: https://chromium-review.googlesource.com/775858Reviewed-by: 's avatarJamie Madill <jmadill@chromium.org> Reviewed-by: 's avatarGeoff Lang <geofflang@chromium.org>
parent 7f5c3eb7
Showing with 80 additions and 46 deletions
doc/BuildingAngleForChromiumDevelopment.md
......@@ -30,7 +30,7 @@ git checkout master
```bash
cd src/third_party/angle
GYP_GENERATORS=ninja gclient runhooks
gn gen out/Debug
```
* To build
......
doc/BuildingAngleForWindowsStore.md
# How to build ANGLE for Windows Store
Building for Windows Store is deprecated because it requires [GYP](gyp.md).
ANGLE provides OpenGL ES 2.0 and EGL 1.4 libraries and dlls. You can use these to build and run OpenGL ES 2.0 applications on Windows.
## Development setup
......@@ -46,11 +48,11 @@ Once the build completes, the output directory for your selected configuration (
* Right-click your project in the _Solution Explorer_, and select _Properties_.
* Under the _Configuration Properties_ branch, click _C/C++_.
* Add the relative path to the Khronos EGL and GLES2 header files to _Additional Include Directories_.
3. Configure your build environment to have access to `libEGL.lib` and `libGLESv2.lib` found in the build output directory (see [Building ANGLE](DevSetup.md#building-angle-on-windows)).
3. Configure your build environment to have access to `libEGL.lib` and `libGLESv2.lib` found in the build output directory (see [Building ANGLE](DevSetup.md#building-with-visual-studio)).
* For Visual C++
* Right-click your project in the _Solution Explorer_, and select _Properties_.
* Under the _Configuration Properties_ branch, open the _Linker_ branch and click _Input_.
* Add the relative paths to both the `libEGL.lib` file and `libGLESv2.lib` file to _Additional Dependencies_, separated by a semicolon.
4. Copy `libEGL.dll` and `libGLESv2.dll` from the build output directory (see [Building ANGLE](DevSetup.md#building-angle-on-windows)) into your application folder or packages location if a ANGLE Windows Store NuGet was used.
4. Copy `libEGL.dll` and `libGLESv2.dll` from the build output directory (see [Building ANGLE](DevSetup.md#building-with-visual-studio)) into your application folder or packages location if a ANGLE Windows Store NuGet was used.
5. Code your application to the Khronos [OpenGL ES 2.0](http://www.khronos.org/registry/gles/) and [EGL 1.4](http://www.khronos.org/registry/egl/) APIs.
doc/DebuggingTips.md
......@@ -8,16 +8,17 @@ There are many ways to debug ANGLE using generic or platform-dependent tools. He
The problem with ANGLE is that it exposes the same symbols as the OpenGL driver so apitrace captures the entry point calls intended for ANGLE and reroutes them to the OpenGL driver. In order to avoid this problem, use the following:
1. Compile ANGLE as a static library so that it doesn't get shadowed by apitrace's shim using the `-D angle_gl_library_type=static_library` gyp flag.
1. Link your application against the static ANGLE libraries (libGLESv2_static and libEGL_static) so they don't get shadowed by apitrace's shim.
2. Ask apitrace to explicitly load the driver instead of using a dlsym on the current module. Otherwise apitrace will use ANGLE's symbols as the OpenGL driver entrypoint (causing infinite recursion). To do this you must point an environment variable to your GL driver. For example: `export TRACE_LIBGL=/usr/lib/libGL.so.1`. You can find your libGL with `ldconfig -p | grep libGL`.
3. Link ANGLE against libGL instead of dlsyming the symbols at runtime; otherwise ANGLE won't use the replaced driver entry points. This can be done by adding `-D angle_link_glx=1`.
3. Link ANGLE against libGL instead of dlsyming the symbols at runtime; otherwise ANGLE won't use the replaced driver entry points. This is done with the gn arg `angle_link_glx = true`.
If you follow these steps, apitrace will work correctly aside from a few minor bugs like not being able to figure out what the default framebuffer size is if there is no glViewport command.
For example, to trace a run of `hello_triangle`, assuming you are using the ninja gyp generator and the apitrace executables are in `$PATH`:
```
./gyp/gyp_angle -D angle_link_glx=1 -D angle_gl_library_type=static_library
gn args out/Debug # add "angle_link_glx = true"
# edit samples/BUILD.gn and append "_static" to "angle_util", "libEGL", "libGLESv2"
ninja -C out/Debug
export TRACE_LIBGL="/usr/lib/libGL.so.1" # may require a different path
apitrace trace -o mytrace ./out/Debug/hello_triangle
......
doc/DevSetup.md
......@@ -10,23 +10,26 @@ ANGLE uses git for version control. If you are not familiar with git, helpful do
### Required Tools
On all platforms:
* GN is the supported build system. GYP is deprecated and support will be removed in the future but [instructions are available](gyp.md).
* Clang will be set up by the build system and used by default. See below for platform-specific compiler choices.
* [depot_tools](http://dev.chromium.org/developers/how-tos/install-depot-tools)
* Required to generate projects and build files, contribute patches, run the unit tests or build the shader compiler on non-Windows systems.
On Windows:
* [Visual Studio Community 2015 Update 3](https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update3-vs)
* Required to build ANGLE on Windows and for the packaged Windows 10 SDK. Note: Chrome is in the process of upgrading to Visual Studio 2017. ANGLE will switch over once Chrome does.
* [Windows 10 Standalone SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk)
* Comes with additional features that aid development, such as the Debug runtime for D3D11. Required for the D3D Compiler DLL.
* [Visual Studio Community 2017 Update 3.2](https://www.visualstudio.com/en-us/news/releasenotes/vs2017-relnotes)
* Put `is_clang = false` in your gn args to compile with the Microsoft Visual C++ compiler instead of clang.
* See the [Chromium Windows build instructions](https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md) for more info.
* Required for the packaged Windows 10 SDK.
* [Windows 10 Standalone SDK version 10.0.15063 or later](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk)
* Comes with additional features that aid development, such as the Debug runtime for D3D11. Required for the D3D Compiler DLL.
* [Cygwin's Bison, flex, and patch](https://cygwin.com/setup-x86_64.exe) (optional)
* This is only required if you need to modify GLSL ES grammar files (`glslang.l` and `glslang.y` under `src/compiler/translator`, or `ExpressionParser.y` and `Tokenizer.l` in `src/compiler/preprocessor`).
* This is only required if you need to modify GLSL ES grammar files (`glslang.l` and `glslang.y` under `src/compiler/translator`, or `ExpressionParser.y` and `Tokenizer.l` in `src/compiler/preprocessor`).
Use the latest versions of bison, flex and patch from the 64-bit cygwin distribution.
* Non-googlers need to set DEPOT_TOOLS_WIN_TOOLCHAIN environment variable to 0.
On Linux:
* The GCC or Clang compilers
* Development packages for OpenGL, X11 and libpci
* Bison and flex are not needed as we only support generating the translator grammar on Windows.
......@@ -36,18 +39,6 @@ On MacOS:
* Bison and flex are not needed as we only support generating the translator grammar on Windows.
### Getting the source
Set the following environment variables as needed:
On Windows:
* `GYP_GENERATORS` to `msvs` (other options include `ninja` and `make`)
* `GYP_MSVS_VERSION` to `2015`
On Linux and MacOS:
* `GYP_GENERATORS` to `ninja` (defaults to 'make' that pollutes your source directory)
Download the ANGLE source by running the following commands:
```
git clone https://chromium.googlesource.com/angle/angle
......@@ -55,33 +46,42 @@ cd angle
python scripts/bootstrap.py
gclient sync
git checkout master
gn gen out/Debug
```
GYP will generate the project files, if you update ANGLE or make a change to the projects, they can be regenerated by executing `gclient runhooks`.
GN will generate ninja files by default. To change the default build options run `gn args out/Debug`. Some commonly used options are:
```
is_debug = true
target_cpu = x64 (or x86)
is_clang = false (to use compiler other than clang)
```
For more information on GN run `gn help`.
On Windows GYP will generate the main VS2015 solution file as gyp/ANGLE.sln. For generating a Windows Store version of ANGLE view the [Windows Store instructions](BuildingAngleForWindowsStore.md).
Ninja can be used to compile on all platforms with one of the following commands:
```
ninja -C out/Debug
ninja -C out/Release
```
Ninja automatically calls GN to regenerate the build files on any configuration change.
Ensure `depot_tools` is in your path as it provides ninja.
On Linux and MacOS, GYP will generate the `out/Debug` and `out/Release` directories.
### Building with Visual Studio
### Building ANGLE on Windows
1. Open one of the ANGLE Visual Studio solution files (see [Getting the source](#getting-the-source)).
2. Select Build -> Configuration Manager
3. In the "Active solution configuration:" drop down, select the desired configuration (eg. Release), and close the Configuration Manager.
4. Select Build -> Build Solution.
Once the build completes, the output directory for your selected configuration (eg. `Release_Win32`, located next to the solution file) will contain the required libraries and dlls to build and run an OpenGL ES 2.0 application.
Run `scripts/msvs_projects.py` to generate a Visual Studio solution in `out/sln/ANGLE.sln`.
This script runs GN and consolidates all the targets in `out` into a single meta-solution.
### Building ANGLE on Linux and MacOS
Run `ninja -C out/Debug` or `ninja -C out/Release`. Ninja is provided by `depot_tools` so make sure you set up your `PATH` correctly.
Once the build completes, the `out/Debug` or `out/Release` directories will contain the .so or .dylib libraries and test binaries.
In Visual Studio:
1. Open the ANGLE solution file `out/sln/ANGLE.sln`.
2. The configurations found in your `out` directory will be mapped to configurations in the configuration manager. For compatibility reasons all configurations are listed as 64-bits.
3. Right click the "all" solution and select build. "Build Solution" is not functional with GN; instead build one target at a time."
Once the build completes the output directory for your selected configuration (e.g. `out/Release_x64`) will contain the required libraries and dlls to build and run an OpenGL ES 2.0 application. ANGLE executables (tests and samples) are under out/sln.
### Building ANGLE for Android
Presently, it is not possible to build standalone ANGLE for Android.
But, ANGLE for Android can be built within a Chromium checkout.
The reason for that is a dependency on Chromium for Android toolchain and that it only supports GN.
Also, it can only be built on Linux, as this is the only platform that Chromium for Android supports.
In theory, once ANGLE supports standalone GN build, it may be possible to put Chromium for Android toolchain in `third_party` or `buildtools` to build standalone ANGLE for Android.
But, for now, the steps in [Checking out and building Chromium for Android](https://chromium.googlesource.com/chromium/src/+/master/docs/android_build_instructions.md) should be followed to check out Chromium for Android and set up build environment.
At present it is not possible to build standalone ANGLE for Android but it can be built within a Chromium checkout.
Since ANGLE has converted to GN a standalone build should be possible.
For now follow the steps in
[Checking out and building Chromium for Android](https://chromium.googlesource.com/chromium/src/+/master/docs/android_build_instructions.md).
This must be done on Linux, the only platform that Chromium for Android supports.
Name your output directories `out/Debug` and `out/Release`, because Chromium GPU tests look for browser binaries in these folders. Replacing `out` with other names seems to be OK when working with multiple build configurations.
It's best to use a build configuration of some Android bot on [GPU.FYI waterfall](https://build.chromium.org/p/chromium.gpu.fyi/waterfall). Look for `generate_build_files` step output of that bot. Remove `goma_dir` flag.
For example, these are the build flags from Nexus 5X bot:
......@@ -137,12 +137,12 @@ On Windows:
* Right-click your project in the _Solution Explorer_, and select _Properties_.
* Under the _Configuration Properties_ branch, click _C/C++_.
* Add the relative path to the Khronos EGL and GLES2 header files to _Additional Include Directories_.
2. Configure your build environment to have access to `libEGL.lib` and `libGLESv2.lib` found in the build output directory (see [Building ANGLE](#building-angle-on-windows)).
2. Configure your build environment to have access to `libEGL.lib` and `libGLESv2.lib` found in the build output directory (see [Building ANGLE](#building-with-visual-studio)).
* For Visual C++
* Right-click your project in the _Solution Explorer_, and select _Properties_.
* Under the _Configuration Properties_ branch, open the _Linker_ branch and click _Input_.
* Add the relative paths to both the `libEGL.lib` file and `libGLESv2.lib` file to _Additional Dependencies_, separated by a semicolon.
3. Copy `libEGL.dll` and `libGLESv2.dll` from the build output directory (see [Building ANGLE](#building-angle-on-windows)) into your application folder.
3. Copy `libEGL.dll` and `libGLESv2.dll` from the build output directory (see [Building ANGLE](#building-with-visual-studio)) into your application folder.
4. Code your application to the Khronos [OpenGL ES 2.0](http://www.khronos.org/registry/gles/) and [EGL 1.4](http://www.khronos.org/registry/egl/) APIs.
On Linux and MacOS, either:
......
doc/dEQP.md
......@@ -43,7 +43,7 @@ ANGLE + dEQP, use the arguments:
### Check your results
If run from Visual Studio 2015, dEQP generates a test log to
`src/tests/TestResults.qpa`. To view the test log information, you'll need to
`out/sln/obj/src/tests/TestResults.qpa`. To view the test log information, you'll need to
use the open-source GUI
[Cherry](https://android.googlesource.com/platform/external/cherry). ANGLE
checks out a copy of Cherry to `angle/third_party/cherry` when you sync with
......
doc/gyp.md 0 → 100644
# Deprecated GYP Instructions
Use GN instead of GYP, as described in the [developer instructions](DevSetup.md).
Support for GYP will be removed in the future.
Though deprecated, GYP is still run by `gclient sync`.
You may want to set certain environment variables ahead of time.
On Windows:
* `GYP_GENERATORS` to `msvs` (other options include `ninja` and `make`)
* `GYP_MSVS_VERSION` to `2015`
On Linux and MacOS:
* `GYP_GENERATORS` to `ninja` (defaults to 'make' that pollutes your source directory)
To run GYP at other times use the script `gyp/gyp_angle`.
## Running ANGLE under apitrace on Linux
See the [debugging tips](DebuggingTips.md#running-angle-under-apitrace-on-linux) and replace the gn steps with:
```
gyp/gyp_angle -D angle_link_glx=1 -D angle_gl_library_type=static_library
```
# Deprecated Windows Store Instructions
[Building for Windows Store](BuildingAngleForWindowsStore.md) is deprecated because it requires GYP.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment