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