diff options
Diffstat (limited to 'src/devices/graphics/build-tests.jd')
| -rw-r--r-- | src/devices/graphics/build-tests.jd | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/src/devices/graphics/build-tests.jd b/src/devices/graphics/build-tests.jd new file mode 100644 index 00000000..f43d916e --- /dev/null +++ b/src/devices/graphics/build-tests.jd @@ -0,0 +1,354 @@ +page.title=Building test programs +@jd:body + +<!-- + Copyright 2015 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol id="auto-toc"> + </ol> + </div> +</div> + + +<p>The test framework has been designed with portability in mind. The only +mandatory requirements are full C++ support and standard system libraries for +I/O, threads and sockets.</p> + +<h2 id=cmake_build_system>CMake build system</h2> + +<p>The deqp sources have build scripts for CMake, which is the preferred tool for +compiling the test programs.</p> + +<p>CMake is an open source build system that supports multiple platforms and +toolchains. CMake generates native makefiles or IDE project files from +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> + +<p>CMake supports and recommends out-of-source-tree builds, i.e., you should +always create makefiles or project files in a separate build directory +outside the source tree. CMake does not have any kind of "distclean" target, so +removing any files generated by CMake must be done manually.</p> + +<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> + +<table> + <tr> + <th>Configuration option</th> + <th>Description</th> + </tr> + + <tr> + <td><code>DEQP_TARGET</code></td> +<td><p>Target name, for example: "android"</p> +<p>The deqp CMake scripts will include the file +<code>targets/<DEQP_TARGET>/<DEQP_TARGET>.cmake</code> and expect to find target-specific build options from there.</p> +</td> + </tr> + <tr> + <td><code>CMAKE_TOOLCHAIN_FILE</code></td> +<td><p>Path to toolchain file for CMake. Used for cross compilation.</p></td> + </tr> + <tr> + <td><code>CMAKE_BUILD_TYPE</code></td> +<td><p>Build type for makefile targets. Valid values are: "Debug" and "Release"</p> +<p>Note the interpretation and default type depend on the targeted build system. +See the CMake documentation for details.</p> +</td> + </tr> +</table> + +<h2 id=creating_target_build_file>Creating a target build file</h2> + +<p>The deqp build system is configured for new targets using target build files. +A target build file defines which features the platform supports and what libraries or +additional 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> + +<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> + +<table> + <tr> + <th>Variable</th> + <th>Description</th> + </tr> + <tr> + <td><code> +DEQP_TARGET_NAME</code></td> +<td><p>Target name (will be included into test logs)</p> +</td> + </tr> + <tr> + <td><code> +DEQP_SUPPORT_GLES2</code></td> +<td><p>Whether GLES2 is supported (default: OFF)</p> +</td> + </tr> + <tr> + <td><code> +DEQP_GLES2_LIBRARIES</code></td> +<td><p>GLES2 libraries (leave empty if not supported or dynamic loading is used)</p> +</td> + </tr> + <tr> + <td><code> +DEQP_SUPPORT_GLES3</code></td> +<td><p>Whether GLES3.x is supported (default: OFF)</p> +</td> + </tr> + <tr> + <td><code> +DEQP_GLES3_LIBRARIES</code></td> +<td><p>GLES3.x libraries (leave empty if not supported or dynamic loading is used)</p> +</td> + </tr> + <tr> + <td><code> +DEQP_SUPPORT_VG</code></td> +<td><p>Whether OpenVG is supported (default: OFF)</p> +</td> + </tr> + <tr> + <td><code> +DEQP_OPENVG_LIBRARIES</code></td> +<td><p>OpenVG libraries (leave empty if not supported or dynamic loading is used)</p> +</td> + </tr> + <tr> + <td><code> +DEQP_SUPPORT_EGL</code></td> +<td><p>Whether EGL is supported (default: OFF)</p> +</td> + </tr> + <tr> + <td><code> +DEQP_EGL_LIBRARIES</code></td> +<td><p>EGL libraries (leave empty if not supported or dynamic loading is used)</p> +</td> + </tr> + <tr> + <td><code> +DEQP_PLATFORM_LIBRARIES</code></td> +<td><p>Additional platform-specific libraries required for linking</p> +</td> + </tr> + <tr> + <td><code> +DEQP_PLATFORM_COPY_LIBRARIES</code></td> +<td><p>List of libraries that are copied to each test binary build directory. Can be +used to copy libraries that are needed for running tests but are not in default +search path.</p> +</td> + </tr> + <tr> + <td><code> +TCUTIL_PLATFORM_SRCS</code></td> +<td><p>Platform port source list. Default sources are determined based on the +capabilities and OS.</p> + +<p><strong>Note:</strong> Paths are relative to: <code>framework/platform</code></p> +</td> + </tr> +</table> + +<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> + +<h2 id=win32_build>Win32 build</h2> + +<p>The easiest way to build deqp modules for Windows is to use the CMake build +system. You will need CMake 2.6.12 or newer and the Microsoft Visual C/C++ +compiler. The deqp has been tested with Visual Studio 2013.</p> + +<p>Visual Studio project files can be generated with the following command:</p> + +<pre> +cmake path\to\src\deqp -G "Visual Studio 12" +</pre> + +<p>A 64-bit build can be made by selecting "Visual Studio <ver> Win64" as the build +generator:</p> + +<pre> +cmake path\to\src\deqp -G "Visual Studio 12 Win64" +</pre> + +<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> + +<h3 id=rendering_context_creation>Rendering context creation</h3> + +<p>Rendering context can be created either with WGL or with EGL on Windows.</p> + +<h4 id=wgl_support>WGL support</h4> + +<p>All Win32 binaries support GL context creation with WGL as it requires only +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 +latest drivers from NVIDIA and Intel. AMD drivers do not support the required +extension.</p> + +<h4 id=egl_support>EGL support</h4> + +<p>The deqp is built with dynamic loading for EGL on Windows if DEQP_SUPPORT_EGL +is ON. This is the default in most targets. Then, if the host has EGL libraries +available, it is possible to run tests with them with the command line +parameter: <code>--deqp-gl-context-type=egl</code></p> + +<h2 id=android_build>Android build</h2> + +<p>The Android build uses CMake build scripts for building the native test code. +Java parts, i.e., the Test Execution Server and the Test Application Stub, are +compiled using the standard Android build tools.</p> + +<p>To compile deqp test programs for Android with the provided build +scripts, you will need:</p> + +<ul> + <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 + <li>Android stand-alone SDK with API 13, SDK Tools, SDK Platform-tools, and SDK +Build-tools <a href="http://developer.android.com/sdk/index.html#Other">packages</a> installed + <li><a href="http://ant.apache.org/bindownload.cgi">Apache Ant 1.9.4</a> + (required by the Java code build) + <li><a href="http://www.cmake.org/download/">CMake 2.8.12</a> or newer + <li><a href="https://www.python.org/downloads/">Python 2.6</a> or newer in 2.x series; Python 3.x is not supported + <li>For Windows: Either NMake or JOM in <code>PATH</code> + <ul> + <li><a href="http://qt-project.org/wiki/jom">JOM</a> enables faster builds + </ul> + <li> Optional: Ninja make is also supported on Linux +</ul> + +<p>Ant and SDK binaries are located based on the PATH environment variable with +certain overriding defaults. The logic is controlled by <code>android/scripts/common.py</code>. </p> + +<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> + +<p>Deqp on-device components, the test execution service, and test programs are +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> + +<h2 id=linux_build>Linux build</h2> + +<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> + +<table> + <tr> + <th>Build target</th> + <th>Description</th> + </tr> + + <tr> + <td><code>default</code></td> +<td><p>Default target that uses CMake platform introspection to determine support for various APIs.</p> +</td> + </tr> + +<tr> + <td><code> +x11_glx</code></td> +<td><p>Uses GLX to create OpenGL (ES) contexts.</p> +</td> + </tr> + +<tr> + <td><code> +x11_egl</code></td> +<td><p>Uses EGL to create OpenGL (ES) contexts.</p> +</td> + </tr> + + <tr> + <td><code> +x11_egl_glx</code></td> +<td><p>Supports both GLX and EGL with X11.</p> +</td> + </tr> +</table> + +<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> + +<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> + +<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> + +<p>An example of a full command line used to do a 32-bit debug build against +driver headers and libraries in a custom location is the following:</p> + +<pre> +$ cmake <path to src>/deqp -DDEQP_TARGET=x11_egl -DCMAKE_C_FLAGS="-m32" +-DCMAKE_CXX_FLAGS="-m32" -DCMAKE_BUILD_TYPE=Debug +-DCMAKE_LIBRARY_PATH="<path to driver>/lib" +-DCMAKE_INCLUDE_PATH="<path to driver>/inc" +$ make -j4 +</pre> + +<h2 id=cross-compiling>Cross-compiling</h2> + +<p>Cross-compiling can be achieved by using a CMake toolchain file. The toolchain +file specifies the compiler to use, along with custom search paths for +libraries and headers. Several toolchain files for common scenarios are +included in the release package in the <code>framework/delibs/cmake</code> directory.</p> + +<p>In addition to standard CMake variables, the following deqp-specific variables +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> + +<table> + <tr> + <th>Variable</th> + <th>Description</th> + </tr> + <tr> + <td><code> +DE_OS</code></td> + <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> + </td> + </tr> + <tr> + <td><code> +DE_COMPILER</code></td> +<td><p>Compiler type. Supported values are: <code>DE_COMPILER_GCC, DE_COMPILER_MSC, DE_COMPILER_CLANG</code></p> +</td> + </tr> + <tr> + <td><code> +DE_CPU</code></td> +<td><p>CPU type. Supported values are: <code>DE_CPU_ARM, DE_CPU_X86</code>.</p> +</td> + </tr> + <tr> + <td><code> +DE_PTR_SIZE</code></td> +<td><p>sizeof(void*) on the platform. Supported values are: 4 and 8</p> +</td> + </tr> +</table> + +<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> + +<pre> +cmake <path to src>/deqp –DDEQP_BUILD_TYPE="Release" +–DCMAKE_TOOLCHAIN_FILE=<path to src>/delibs/cmake/toolchain-arm-cs.cmake +–DARM_CC_BASE=<path to cc directory> +</pre> + +<h2 id=run-time_linking_of_gles_and_egl_libraries>Run-time linking of GLES and EGL libraries</h2> + +<p>The deqp does not need entry points of the API under test during linking. The +test code always accesses the APIs through function pointers. Entry points can +then be loaded dynamically at run time or the platform port can provide them at +link time.</p> + +<p>If support for an API is turned on in the build settings and link libraries are +not provided, the deqp will load the needed entry points at run time. If the +static linking is desired, provide the needed link libraries in the <code>DEQP_<API>_LIBRARIES</code> build configuration variable.</p> |