HACKING

   1
   2
   3 \ Initial design decisions
   4  -------------------------
   5
   6 Before I started working on Piglit, I asked around for OpenGL testing methods.
   7 There were basically two kinds of tests:
   8
   9 1. Glean, which is fully automatic and intends to test the letter of the
  10    OpenGL specification (at least partially).
  11
  12 2. Manual tests using Mesa samples or third-party software.
  13
  14 The weakness of Glean is that it is not flexible, not pragmatic enough for
  15 driver development. For example, it tests for precision requirements in
  16 blending, where a driver just cannot reasonably improve on what the hardware
  17 delivers. As a driver developer, one wants to consider a test successful
  18 when it reaches the optimal results that the hardware can give, even when
  19 these results may be non-compliant.
  20
  21 Manual tests are not well repeatable. They require a considerable amount of
  22 work on the part of the developer, so most of the time they aren't done at all.
  23 On the other hand, those manual tests have sometimes been created to test for
  24 a particular weakness in implementations, so they may be very suitable to
  25 detect future, similar weaknesses.
  26
  27 Due to these weaknesses, the test coverage of open source OpenGL drivers
  28 is suboptimal at best. My goal for Piglit is to create a useful test system
  29 that helps driver developers in improving driver quality.
  30
  31 With that in mind, my sub-goals are:
  32
  33 1. Combine the strengths of the two kinds of tests (Glean, manual tests)
  34    into a single framework.
  35
  36 2. Provide concise, human readable summaries of the test results, with the
  37    option to increase the detail of the report when desired.
  38
  39 3. Allow easy visualization of regressions.
  40
  41 4. Allow easy detection of performance regressions.
  42
  43 I briefly considered extending Glean, but then decided for creating an
  44 entirely new project. The most important reasons are:
  45
  46 1. I do not want to pollute the very clean philosophy behind Glean.
  47
  48 2. The model behind Glean is that one process runs all the tests.
  49    During driver development, one often gets bugs that cause tests to crash.
  50    This means that one failed test can disrupt the entire test batch.
  51    I want to use a more robust model, where each test runs in its own process.
  52    This model does not easily fit onto Glean.
  53
  54 3. The amount of code duplication and forking overhead is minimal because
  55  a) I can use Glean as a "subroutine", so no code is actually duplicated,
  56     there's just a tiny amount of additional Python glue code.
  57  b) It's unlikely that this project makes significant changes to Glean
  58     that need to be merged upstream.
  59
  60 4. While it remains reasonable to use C++ for the actual OpenGL tests,
  61    it is easier to use a higher level language like Python for the framework
  62    (summary processing etc.)
  63
  64
  65
  66
  67 \ Ugly Things (or: Coding style)
  68  -------------------------------
  69
  70 As a rule of thumb, coding style should be preserved in test code taken from
  71 other projects, as long as that code is self-contained.
  72
  73 Apart from that, the following rules are cast in stone:
  74
  75 1. Use tabulators for indentation
  76 2. Use spaces for alignment
  77 3. No whitespace at the end of a line
  78
  79 See http://electroly.com/mt/archives/000002.html for a well-written rationale.
  80
  81 Use whatever tabulator size you want:
  82 If you adhere to the rules above, the tab size does not matter. Tab size 4
  83 is recommended because it keeps the line lengths reasonable, but in the end,
  84 that's purely a matter of personal taste.
  85
  86
  87
  88 \ Release Philosophy
  89  -------------------
  90
  91 Since Piglit is a test suite, it is "production software" at all times.
  92 Test case might be incorrect, but despite that it is not useful to speak of
  93 "stable" and "unstable" versions of a test suite, especially one that sees
  94 a relatively small rate of change like Piglit.
  95
  96 For this reason, developers of OpenGL drivers and related software, and even
  97 testers are encouraged to follow the git repository on freedesktop.org at all
  98 times. A web interface to this repository can be found here:
  99
 100        http://cgit.freedesktop.org/piglit
 101
 102 Nevertheless, for purposes of marking a specific point in time for packaging
 103 in an environment where non-developers do tests on a wide range of hardware,
 104 it has been pointed out that it would be useful to have official releases.
 105
 106 For this reason, we will occasionally bump the version number in the file
 107 RELEASE and create an appropriate tag in the git repository.
 108
 109 This tag is the official way of marking a release, so the tarballs provided
 110 automatically by the cgit frontend are official release tarballs.
 111