Piglit ------ 1. About 2. Setup 3. How to run tests 4. Available test sets 5. How to write tests 6. Todo 1. About -------- Piglit is a collection of automated tests for OpenGL and OpenCL implementations. The goal of Piglit is to help improve the quality of open source OpenGL and OpenCL drivers by providing developers with a simple means to perform regression tests. The original tests have been taken from - Glean ( http://glean.sf.net/ ) and - Mesa ( http://www.mesa3d.org/ ) 2. Setup -------- First of all, you need to make sure that the following are installed: - Python 2.7.x - Python Mako module - numpy (http://www.numpy.org) - six (https://pypi.python.org/pypi/six) - cmake (http://www.cmake.org) - GL, glu and glut libraries and development packages (i.e. headers) - X11 libraries and development packages (i.e. headers) - waffle (http://www.waffle-gl.org) Optionally, you can install the following: - nose. A python test framework, used for running the python framework test suite. (https://nose.readthedocs.org/en/latest/) - tox. A tool for testing python packages against multiple configurations of python (https://tox.readthedocs.org/en/latest/index.html) - lxml. An accelerated python xml library using libxml2 (http://lxml.de/) - simplejson. A fast C based implementation of the python json library. (https://simplejson.readthedocs.org/en/latest/) - backports.lzma. A packport of python3's lzma module to python2, this enables fast native xz (de)compression in piglit for results files (https://github.com/peterjc/backports.lzma) - mock. A python module for mocking other python modules. Required only for unittests (https://github.com/testing-cabal/mock) Now configure the build system: $ ccmake . This will start cmake's configuration tool, just follow the onscreen instructions. The default settings should be fine, but I recommend you: - Press 'c' once (this will also check for dependencies) and then - Set "CMAKE_BUILD_TYPE" to "Debug" Now you can press 'c' again and then 'g' to generate the build system. Now build everything: $ make 2.1 Cross Compiling ------------------- On Linux, if cross-compiling a 32-bit build on a 64-bit host, then you must invoke cmake with option "-DCMAKE_SYSTEM_PROCESSOR=i386". 2.2 Ubuntu ---------- Install development packages. $ sudo apt-get install cmake g++ mesa-common-dev libgl1-mesa-dev python-numpy python-mako freeglut3-dev x11proto-gl-dev libxrender-dev Install additional components for which Ubuntu packages do not yet exist: - waffle (http://www.waffle-gl.org) Configure and build. $ cmake . $ make 2.3 Mac OS X ------------ Install CMake. http://cmake.org/cmake/resources/software.html Download and install 'Mac OSX Universal' platform. Install Xcode. http://developer.apple.com/xcode Configure and build. $ cmake . $ make glean glean will not build with MacOSX10.7.sdk. If you are trying to build glean on Mac OS 10.7 (Lion), you will have to use MacOSX10.6.sdk. $ ccmake . Set 'CMAKE_OSX_SYSROOT' to '/Developer/SDKs/MacOSX10.6.sdk'. Configure. Generate and exit. $ make 2.4 Cygwin ---------- Install development packages. - cmake - gcc4 - make - opengl - libGL-devel - python - python-numpy - libglut-devel Configure and build. $ cmake . $ make 2.5 Windows ----------- Install Python. http://www.python.org/download Install NumPy. http://sourceforge.net/projects/numpy/files/NumPy Install CMake. http://cmake.org/cmake/resources/software.html Download and install 'Windows' platform. Install Microsoft Visual Studio 2013 or later. Install 'Visual C++' feature. Download OpenGL Core API and Extension Header Files. http://www.opengl.org/registry/#headers Copy header files to MSVC. C:\Program Files\Microsoft Visual Studio 12.0\VC\include\GL Install pip. http://www.pip-installer.org/en/latest/installing.html Install python mako. > c:\Python27\Scripts\pip.exe install mako 2.5.1 GLUT ---------- Download freeglut for MSVC. http://www.transmissionzero.co.uk/software/freeglut-devel Open Visual Studio Command Prompt. Start Menu->All Programs->Visual Studio 2013->Visual Studio Tools->VS2013 x86 Native Tools Command Prompt CD to piglit directory. Run CMake GUI. > C:\Program Files\CMake 2.8\bin\cmake-gui.exe . Configure - NMake Makefiles - Use default native compilers Set these variables in the Advanced view. - GLUT_INCLUDE_DIR - GLUT_glut_LIBRARY Configure Generate File->Exit Build from the Visual Studio Command Prompt. > nmake 2.5.2 Waffle ------------ Download waffle for MSVC. http://www.waffle-gl.org/ Open the Command Prompt. CD to piglit directory. Run CMake GUI. > C:\Program Files\CMake 2.8\bin\cmake-gui.exe . Configure - 'Visual Studio 12 2013', or - 'Visual Studio 12 2013 Win64' - Use default native compilers Set these variables in the Advanced view. Note that the values provided are for reference purposed and may differ on your system. - PIGLIT_USE_WAFFLE, BOOL, TRUE - WAFFLE_INCLUDE_DIRS, PATH, ${waffle_root}\include\waffle - WAFFLE_LDFLAGS, FILEPATH, ${waffle_root}\lib\waffle-1.lib - GLEXT_INCLUDE_DIR, PATH, C:\Program Files\Microsoft Visual Studio 12.0\VC\include\GL Configure Generate File->Exit Build from the Command Prompt. > cmake --build . 3. How to run tests ------------------- Make sure that everything is set up correctly: $ ./piglit run sanity results/sanity You may include '.py' on the profile, or you may exclude it (sanity vs sanity.py), both are equally valid. You may also preface test profiles with tests/ (or any other path you like), which may be useful for shell tab completion. You may provide multiple profiles to be run at the same time: $ ./piglit run quick_cl gpu deqp_gles3 results/gl-cl-combined Use $ ./piglit run or $ ./piglit run -h To learn more about the command's syntax. Have a look into the tests/ directory to see what test profiles are available: $ ls tests/*.py See also section 4. To create some nice formatted test summaries, run $ ./piglit summary html summary/sanity results/sanity.results Hint: You can combine multiple test results into a single summary. During development, you can use this to watch for regressions: $ ./piglit summary html summary/compare results/baseline.results results/current.results You can combine as many testruns as you want this way (in theory; the HTML layout becomes awkward when the number of testruns increases) Have a look at the results with a browser: $ xdg-open summary/sanity/index.html The summary shows the 'status' of a test: pass This test has completed successfully. warn The test completed successfully, but something unexpected happened. Look at the details for more information. fail The test failed. crash The test binary exited with a non-zero exit code skip The test was skipped. timeout The test ran longer than its allotted time and was forcibly killed. There are also dmesg-* statuses. These have the same meaning as above, but are triggered by dmesg related messages. 3.1 Note -------- The way 'piglit run' and 'piglit summary' count tests are different, 'piglit run' counts the number of Test derived instance in the profile(s) selected, while 'piglit summary' counts the number of subtests a result contains, or it's result if there are no subtests. This means that the number shown by 'piglit run' will be less than or equal to the number calculated by 'piglit summary'. 4. Available test sets ---------------------- Test sets are specified as Python scripts in the tests directory. The following test sets are currently available: 4.1 OpenGL Tests ---------------- sanity.py This suite contains minimal OpenGL sanity tests. These tests must pass, otherwise the other tests will not generate reliable results. all.py This suite contains all OpenGL tests. quick.py Run all tests, but cut down significantly on their runtime (and thus on the number of problems they can find). In particular, this runs Glean with the --quick option, which reduces the number of visuals and state combinations tested. gpu.py A further reduced set of tests from quick.py, this runs tests only for hardware functionality and not tests for the software stack. llvmpipe.py A reduced set of tests from gpu.py removing tests that are problematic using llvmpipe cpu.py This profile runs tests that don't touch the gpu, in other words all of the tests in quick.py that are not run by gpu.py glslparser.py A subset of all.py which runs only glslparser tests shader.py A subset of all.py which runs only shader tests 4.2 OpenCL Tests ---------------- cl.py This suite contains all OpenCL tests. quick_cl.py This runs all of the tests from cl.py as well as tests from opencv and oclconform. 4.3 External Integration ------------------------ xts.py Support for running the X Test Suite using piglit. igt.py Support for running Intel-gpu-tools test suite using piglit. deqp_gles2.py Support for running deQP's gles2 profile with piglit. deqp_gles3.py Support for running deQP's gles3 profile with piglit. deqp_gles31.py Support for running deQP's gles3.1 profile with piglit. 5. How to write tests --------------------- Every test is run as a separate process. This minimizes the impact that severe bugs like memory corruption have on the testing process. Therefore, tests can be implemented in an arbitrary standalone language. C is the prefered language for compiled tests, piglit also supports its own simple formats for test shaders and glsl parser input. All new tests must be added to the appropriate profile, all.py profile for OpenGL and cl.py for OpenCL. There are a few basic test classes supported by the python framework: GleanTest This is a test that is only used to integrate Glean tests PiglitBaseTest A shared base class for all native piglit tests. It starts each test as a subprocess, captures stdout and stderr, and waits for the test to return. It provides test timeouts by setting the instances 'timeout' attribute to an integer > 0 which is the number of seconds the test should run. It interprets output by reading stdout and looking for 'PIGLIT: ' in the output, and then reading any trailing characters as well formed json returning the test result. This is a base class and should not be used directly, but provides an explanation of the behavior of the following classes. PiglitGLTest A test class for native piglit OpenGL tests. In addition to the properties of PiglitBaseTest it provides a mechanism for detecting test window resizes and rerunning tests as well as keyword arguments for platform requirements. PiglitCLTest A test class for native piglit OpenCL tests. It currently provides no special features. GLSLParserTest A class for testing a glsl parser. It is generally unnecessary to call this class directly as it uses a helper function to search directories for tests. ShaderTest A class for testing using OpenGL shaders. It is generally unnecessary to call this class directly as it uses a helper function to search directories for tests.