1page.title=Building test programs 2@jd:body 3 4<!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18--> 19 20<div id="qv-wrapper"> 21 <div id="qv"> 22 <h2>In this document</h2> 23 <ol id="auto-toc"> 24 </ol> 25 </div> 26</div> 27 28 29<p>The test framework has been designed with portability in mind. The only 30mandatory requirements are full C++ support and standard system libraries for 31I/O, threads and sockets.</p> 32 33<h2 id=cmake_build_system>CMake build system</h2> 34 35<p>The deqp sources have build scripts for CMake, which is the preferred tool for 36compiling the test programs.</p> 37 38<p>CMake is an open source build system that supports multiple platforms and 39toolchains. CMake generates native makefiles or IDE project files from 40target-independent configuration files. For more information on CMake, 41please see the <a href="http://www.cmake.org/cmake/help/documentation.html">CMake</a> documentation.</p> 42 43<p>CMake supports and recommends out-of-source-tree builds, i.e., you should 44always create makefiles or project files in a separate build directory 45outside the source tree. CMake does not have any kind of "distclean" target, so 46removing any files generated by CMake must be done manually.</p> 47 48<p>Configuration options are given to CMake using <code>-D<OPTION_NAME>=<VALUE></code> syntax. Some commonly used options for deqp are listed below.</p> 49 50<table> 51 <tr> 52 <th>Configuration option</th> 53 <th>Description</th> 54 </tr> 55 56 <tr> 57 <td><code>DEQP_TARGET</code></td> 58<td><p>Target name, for example: "android"</p> 59<p>The deqp CMake scripts will include the file 60<code>targets/<DEQP_TARGET>/<DEQP_TARGET>.cmake</code> and expect to find target-specific build options from there.</p> 61</td> 62 </tr> 63 <tr> 64 <td><code>CMAKE_TOOLCHAIN_FILE</code></td> 65<td><p>Path to toolchain file for CMake. Used for cross compilation.</p></td> 66 </tr> 67 <tr> 68 <td><code>CMAKE_BUILD_TYPE</code></td> 69<td><p>Build type for makefile targets. Valid values are: "Debug" and "Release"</p> 70<p>Note the interpretation and default type depend on the targeted build system. 71See the CMake documentation for details.</p> 72</td> 73 </tr> 74</table> 75 76<h2 id=creating_target_build_file>Creating a target build file</h2> 77 78<p>The deqp build system is configured for new targets using target build files. 79A target build file defines which features the platform supports and what libraries or 80additional include paths are required. Target file names follow the <code>targets/<name>/<name>.cmake</code> format and the target is selected using the <code>DEQP_TARGET</code> build parameter.</p> 81 82<p>File paths in target files are relative to the base <code>deqp</code> directory, not the <code>targets/<name></code> directory. The following standard variables can be set by target build file.</p> 83 84<table> 85 <tr> 86 <th>Variable</th> 87 <th>Description</th> 88 </tr> 89 <tr> 90 <td><code> 91DEQP_TARGET_NAME</code></td> 92<td><p>Target name (will be included into test logs)</p> 93</td> 94 </tr> 95 <tr> 96 <td><code> 97DEQP_SUPPORT_GLES2</code></td> 98<td><p>Whether GLES2 is supported (default: OFF)</p> 99</td> 100 </tr> 101 <tr> 102 <td><code> 103DEQP_GLES2_LIBRARIES</code></td> 104<td><p>GLES2 libraries (leave empty if not supported or dynamic loading is used)</p> 105</td> 106 </tr> 107 <tr> 108 <td><code> 109DEQP_SUPPORT_GLES3</code></td> 110<td><p>Whether GLES3.x is supported (default: OFF)</p> 111</td> 112 </tr> 113 <tr> 114 <td><code> 115DEQP_GLES3_LIBRARIES</code></td> 116<td><p>GLES3.x libraries (leave empty if not supported or dynamic loading is used)</p> 117</td> 118 </tr> 119 <tr> 120 <td><code> 121DEQP_SUPPORT_VG</code></td> 122<td><p>Whether OpenVG is supported (default: OFF)</p> 123</td> 124 </tr> 125 <tr> 126 <td><code> 127DEQP_OPENVG_LIBRARIES</code></td> 128<td><p>OpenVG libraries (leave empty if not supported or dynamic loading is used)</p> 129</td> 130 </tr> 131 <tr> 132 <td><code> 133DEQP_SUPPORT_EGL</code></td> 134<td><p>Whether EGL is supported (default: OFF)</p> 135</td> 136 </tr> 137 <tr> 138 <td><code> 139DEQP_EGL_LIBRARIES</code></td> 140<td><p>EGL libraries (leave empty if not supported or dynamic loading is used)</p> 141</td> 142 </tr> 143 <tr> 144 <td><code> 145DEQP_PLATFORM_LIBRARIES</code></td> 146<td><p>Additional platform-specific libraries required for linking</p> 147</td> 148 </tr> 149 <tr> 150 <td><code> 151DEQP_PLATFORM_COPY_LIBRARIES</code></td> 152<td><p>List of libraries that are copied to each test binary build directory. Can be 153used to copy libraries that are needed for running tests but are not in default 154search path.</p> 155</td> 156 </tr> 157 <tr> 158 <td><code> 159TCUTIL_PLATFORM_SRCS</code></td> 160<td><p>Platform port source list. Default sources are determined based on the 161capabilities and OS.</p> 162 163<p><strong>Note:</strong> Paths are relative to: <code>framework/platform</code></p> 164</td> 165 </tr> 166</table> 167 168<p>The target build file can add additional include or link paths using the <code>include_directories()</code> and <code>link_directories()</code> CMake functions.</p> 169 170<h2 id=win32_build>Win32 build</h2> 171 172<p>The easiest way to build deqp modules for Windows is to use the CMake build 173system. You will need CMake 2.6.12 or newer and the Microsoft Visual C/C++ 174compiler. The deqp has been tested with Visual Studio 2013.</p> 175 176<p>Visual Studio project files can be generated with the following command:</p> 177 178<pre> 179cmake path\to\src\deqp -G "Visual Studio 12" 180</pre> 181 182<p>A 64-bit build can be made by selecting "Visual Studio <ver> Win64" as the build 183generator:</p> 184 185<pre> 186cmake path\to\src\deqp -G "Visual Studio 12 Win64" 187</pre> 188 189<p>You can also generate NMake makefiles with the <code>-G "NMake Makefiles"</code> option as well as the build type (<code>-DCMAKE_BUILD_TYPE="Debug"</code> or <code>"Release"</code>).</p> 190 191<h3 id=rendering_context_creation>Rendering context creation</h3> 192 193<p>Rendering context can be created either with WGL or with EGL on Windows.</p> 194 195<h4 id=wgl_support>WGL support</h4> 196 197<p>All Win32 binaries support GL context creation with WGL as it requires only 198standard libraries. WGL context can be selected using the <code>--deqp-gl-context-type=wgl</code> command line argument. In the WGL mode, the deqp uses the <code>WGL_EXT_create_context_es_profile</code> extension to create OpenGL ES contexts. This has been tested to work with 199latest drivers from NVIDIA and Intel. AMD drivers do not support the required 200extension.</p> 201 202<h4 id=egl_support>EGL support</h4> 203 204<p>The deqp is built with dynamic loading for EGL on Windows if DEQP_SUPPORT_EGL 205is ON. This is the default in most targets. Then, if the host has EGL libraries 206available, it is possible to run tests with them with the command line 207parameter: <code>--deqp-gl-context-type=egl</code></p> 208 209<h2 id=android_build>Android build</h2> 210 211<p>The Android build uses CMake build scripts for building the native test code. 212Java parts, i.e., the Test Execution Server and the Test Application Stub, are 213compiled using the standard Android build tools.</p> 214 215<p>To compile deqp test programs for Android with the provided build 216scripts, you will need:</p> 217 218<ul> 219 <li>The latest version of the <a href="http://developer.android.com/tools/sdk/ndk/index.html">Android NDK</a>; the <code>android/scripts/common.py</code> file lists the required version 220 <li>Android stand-alone SDK with API 13, SDK Tools, SDK Platform-tools, and SDK 221Build-tools <a href="http://developer.android.com/sdk/index.html#Other">packages</a> installed 222 <li><a href="http://ant.apache.org/bindownload.cgi">Apache Ant 1.9.4</a> 223 (required by the Java code build) 224 <li><a href="http://www.cmake.org/download/">CMake 2.8.12</a> or newer 225 <li><a href="https://www.python.org/downloads/">Python 2.6</a> or newer in 2.x series; Python 3.x is not supported 226 <li>For Windows: Either NMake or JOM in <code>PATH</code> 227 <ul> 228 <li><a href="http://qt-project.org/wiki/jom">JOM</a> enables faster builds 229 </ul> 230 <li> Optional: Ninja make is also supported on Linux 231</ul> 232 233<p>Ant and SDK binaries are located based on the PATH environment variable with 234certain overriding defaults. The logic is controlled by <code>android/scripts/common.py</code>. </p> 235 236<p>The NDK directory must be either <code>~/android-ndk-<version></code> or <code>C:/android/android-ndk-<version></code> or defined via the <code>ANDROID_NDK_PATH</code> environment variable.</p> 237 238<p>Deqp on-device components, the test execution service, and test programs are 239built by executing the <code>android/scripts/build.py</code> script. The final .apk is created in <code>android/package/bin</code> and can be installed by the <code>install.py</code> script. If the <a href="port-tests.html#test_execution_service">command line executor</a> is used, the ExecService is launched with <code>launch.py</code> script on the device via ADB. The scripts can be executed from any directory.</p> 240 241<h2 id=linux_build>Linux build</h2> 242 243<p>Test binaries and command line utilities can be built for Linux by generating makefiles using CMake. There are multiple, pre-defined build targets that are useful when building for Linux.</p> 244 245<table> 246 <tr> 247 <th>Build target</th> 248 <th>Description</th> 249 </tr> 250 251 <tr> 252 <td><code>default</code></td> 253<td><p>Default target that uses CMake platform introspection to determine support for various APIs.</p> 254</td> 255 </tr> 256 257<tr> 258 <td><code> 259x11_glx</code></td> 260<td><p>Uses GLX to create OpenGL (ES) contexts.</p> 261</td> 262 </tr> 263 264<tr> 265 <td><code> 266x11_egl</code></td> 267<td><p>Uses EGL to create OpenGL (ES) contexts.</p> 268</td> 269 </tr> 270 271 <tr> 272 <td><code> 273x11_egl_glx</code></td> 274<td><p>Supports both GLX and EGL with X11.</p> 275</td> 276 </tr> 277</table> 278 279<p>Always use <code>-DCMAKE_BUILD_TYPE=<Debug|Release></code> to define the build type. <code>Release</code> is a good default. Without it, a default, unoptimized release build is made.</p> 280 281<p>The <code>-DCMAKE_C_FLAGS</code> and <code>-DCMAKE_CXX_FLAGS</code> command line arguments can be used to pass extra arguments to the compiler. For example the 32-bit or 64-bit build can be done by setting <code>-DCMAKE_C(XX)_FLAGS="-m32"</code> or <code>"-m64"</code> respectively. If not specified, the toolchain native architecture, typically 64-bit on the 64-bit toolchain, is used.</p> 282 283<p>The <code>-DCMAKE_LIBRARY_PATH</code> and <code>-DCMAKE_INCLUDE_PATH</code> arguments can be used for CMake to give CMake additional library or include search paths.</p> 284 285<p>An example of a full command line used to do a 32-bit debug build against 286driver headers and libraries in a custom location is the following:</p> 287 288<pre> 289$ cmake <path to src>/deqp -DDEQP_TARGET=x11_egl -DCMAKE_C_FLAGS="-m32" 290-DCMAKE_CXX_FLAGS="-m32" -DCMAKE_BUILD_TYPE=Debug 291-DCMAKE_LIBRARY_PATH="<path to driver>/lib" 292-DCMAKE_INCLUDE_PATH="<path to driver>/inc" 293$ make -j4 294</pre> 295 296<h2 id=cross-compiling>Cross-compiling</h2> 297 298<p>Cross-compiling can be achieved by using a CMake toolchain file. The toolchain 299file specifies the compiler to use, along with custom search paths for 300libraries and headers. Several toolchain files for common scenarios are 301included in the release package in the <code>framework/delibs/cmake</code> directory.</p> 302 303<p>In addition to standard CMake variables, the following deqp-specific variables 304can be set by the toolchain file. CMake can usually detect <code>DE_OS</code>, <code>DE_COMPILER</code> and <code>DE_PTR_SIZE</code> correctly but <code>DE_CPU</code> must be set by the toolchain file.</p> 305 306<table> 307 <tr> 308 <th>Variable</th> 309 <th>Description</th> 310 </tr> 311 <tr> 312 <td><code> 313DE_OS</code></td> 314 <td><p>Operating system. Supported values are: <code>DE_OS_WIN32, DE_OS_UNIX, DE_OS_WINCE, DE_OS_OSX, DE_OS_ANDROID, DE_OS_SYMBIAN, DE_OS_IOS</code></p> 315 </td> 316 </tr> 317 <tr> 318 <td><code> 319DE_COMPILER</code></td> 320<td><p>Compiler type. Supported values are: <code>DE_COMPILER_GCC, DE_COMPILER_MSC, DE_COMPILER_CLANG</code></p> 321</td> 322 </tr> 323 <tr> 324 <td><code> 325DE_CPU</code></td> 326<td><p>CPU type. Supported values are: <code>DE_CPU_ARM, DE_CPU_X86</code>.</p> 327</td> 328 </tr> 329 <tr> 330 <td><code> 331DE_PTR_SIZE</code></td> 332<td><p>sizeof(void*) on the platform. Supported values are: 4 and 8</p> 333</td> 334 </tr> 335</table> 336 337<p>The toolchain file can be selected using the <code>CMAKE_TOOLCHAIN_FILE</code> build parameter. For example, the following would create makefiles for a build using the CodeSourcery cross-compiler for ARM/Linux:</p> 338 339<pre> 340cmake <path to src>/deqp –DDEQP_BUILD_TYPE="Release" 341–DCMAKE_TOOLCHAIN_FILE=<path to src>/delibs/cmake/toolchain-arm-cs.cmake 342–DARM_CC_BASE=<path to cc directory> 343</pre> 344 345<h2 id=run-time_linking_of_gles_and_egl_libraries>Run-time linking of GLES and EGL libraries</h2> 346 347<p>The deqp does not need entry points of the API under test during linking. The 348test code always accesses the APIs through function pointers. Entry points can 349then be loaded dynamically at run time or the platform port can provide them at 350link time.</p> 351 352<p>If support for an API is turned on in the build settings and link libraries are 353not provided, the deqp will load the needed entry points at run time. If the 354static linking is desired, provide the needed link libraries in the <code>DEQP_<API>_LIBRARIES</code> build configuration variable.</p> 355