354 lines
14 KiB
HTML
354 lines
14 KiB
HTML
<html devsite>
|
||
<head>
|
||
<title>Building test programs</title>
|
||
<meta name="project_path" value="/_project.yaml" />
|
||
<meta name="book_path" value="/_book.yaml" />
|
||
</head>
|
||
<body>
|
||
<!--
|
||
Copyright 2017 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.
|
||
-->
|
||
|
||
|
||
|
||
|
||
<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<var>OPTION_NAME</var>=<var>VALUE</var></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/<var>DEQP_TARGET</var>/<var>DEQP_TARGET</var>.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/<var>NAME</var>/<var>NAME</var>.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/<var>NAME</var></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 class="devsite-terminal devsite-click-to-copy">
|
||
cmake path\to\src\deqp -G "Visual Studio 12"
|
||
</pre>
|
||
|
||
<p>A 64-bit build can be made by selecting "Visual Studio <var>VERSION</var> Win64" as the build
|
||
generator:</p>
|
||
|
||
<pre class="devsite-terminal devsite-click-to-copy">
|
||
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-<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>
|
||
|
||
<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 class="devsite-click-to-copy">
|
||
<code class="devsite-terminal">cmake <path to src>/deqp -DDEQP_TARGET=x11_egl -DCMAKE_C_FLAGS="-m32"
|
||
-DCMAKE_CXX_FLAGS="-m32" -DCMAKE_BUILD_TYPE=Debug
|
||
-DCMAKE_LIBRARY_PATH="<var>PATH_TO_DRIVER</var>/lib"
|
||
-DCMAKE_INCLUDE_PATH="<var>PATH_TO_DRIVER</var>/inc"</code>
|
||
<code class="devsite-terminal">make -j4</code>
|
||
</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 class="devsite-terminal devsite-click-to-copy">
|
||
cmake <var>PATH_TO_SRC</var>/deqp –DDEQP_BUILD_TYPE="Release"
|
||
–DCMAKE_TOOLCHAIN_FILE=<var>PATH_TO_SRC</var>/delibs/cmake/toolchain-arm-cs.cmake
|
||
–DARM_CC_BASE=<var>PATH_TO_CC_DIRECTORY</var>
|
||
</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>
|
||
|
||
</body>
|
||
</html>
|