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 \ Coding style
  67  -------------
  68
  69 Basic formatting:
  70
  71 * Indent with 8-column tabs
  72 * Limit lines to 78 characters or less
  73 * Function return type and name go on successive lines
  74 * Opening function brace goes on line by itself
  75 * Opening statement braces go on same line as the 'for' or 'else'
  76 * Use /* C style comments */, not // C++ style
  77 * Don't write 'if (condition) statement;' on one line - put the statement on
  78   a separate line.  Braces around a single statement are optional.
  79
  80 The following indent command will generally format your code for piglit's
  81 style:
  82
  83   indent -br -i8 -npcs -ce input.c -o output.c
  84
  85 Though, that doesn't give perfect results.  It messes up the
  86 PIGLIT_GL_TEST_CONFIG_BEGIN/END section.  And array initializers sometimes
  87 come out funny.
  88
  89 When in doubt see other recently added piglit tests for coding style.
  90
  91
  92 Code conventions:
  93
  94 * Use "const" qualifiers whenever possible on array declarations, pointers
  95   and global variables.
  96 * Use "static const" for initialized arrays whenever possible.
  97 * Preprocessor macros should be UPPER_CASE
  98 * Enumeration tokens should be UPPER_CASE
  99 * Most other identifiers are lower_case_with_underscores
 100 * Library, executable, and source file names are '<base>_<api>.'
 101   e.g. libpiglitutil_gles2
 102 * Test names are '<lowercasegroupname>-<testname>.'  e.g. glsl-novertexdata
 103 * Use int, float, bool except when GL types (GLint, GLfloat) are really needed
 104 * Don't put declarations after code.  For example:
 105       if (x < 3)
 106          x = 0;
 107       int y = x * x;
 108   This will not compile with MSVC.  The 'int y' declaration must be at the
 109   top of the brace-block.
 110 * Don't use named/designated initializers.  They don't compile with MSVC.
 111
 112
 113 Test conventions:
 114
 115 * The goal is to find bugs and demonstrate them as simply as possible, not
 116   to measure performance or demonstrate features.
 117 * Write tests that are easily read, understood and debugged.  Long, complicated
 118   functions are frowned upon.
 119 * Don't try to test too much in a single test program.  Most piglit programs
 120   are less than 300 lines long.
 121 * If a test doesn't render anything, it doesn't need to set the window size.
 122 * Avoid changing an existing testing such that it might fail where it
 123   previously passed.  Break it into subtests and add a new subtest, or add
 124   a new test which supersedes the old one.
 125 * Things that should be seen are drawn in green (or blue as a second color)
 126   while red is for things that shouldn't be seen.
 127 * Calculate drawing coordinates from piglit_width/piglit_height as needed,
 128   instead of hard coding.
 129 * If a test can safely run at the same time as other tests, add it as a
 130   concurrent test in 'all.tests' (or wherever you add it).
 131
 132
 133 Utility code:
 134
 135 Piglit has a rich set of utility functions for basic drawing, setting
 136 up shaders, probing pixels, error checking, etc.  Try to use them before
 137 rolling your own.
 138
 139 Python framework:
 140
 141 Piglit uses python's PEP8 standard for formatting of python code; using only
 142 spaces with no tabs for indenting.  See
 143 http://www.python.org/dev/peps/pep-0008/ for more information.
 144
 145
 146
 147 \ Release Philosophy
 148  -------------------
 149
 150 Since Piglit is a test suite, it is "production software" at all times.
 151 Test case might be incorrect, but despite that it is not useful to speak of
 152 "stable" and "unstable" versions of a test suite, especially one that sees
 153 a relatively small rate of change like Piglit.
 154
 155 For this reason, developers of OpenGL drivers and related software, and even
 156 testers are encouraged to follow the git repository on freedesktop.org at all
 157 times. A web interface to this repository can be found here:
 158
 159        http://cgit.freedesktop.org/piglit
 160
 161 Nevertheless, for purposes of marking a specific point in time for packaging
 162 in an environment where non-developers do tests on a wide range of hardware,
 163 it has been pointed out that it would be useful to have official releases.
 164
 165 For this reason, we will occasionally bump the version number in the file
 166 RELEASE and create an appropriate tag in the git repository.
 167
 168 This tag is the official way of marking a release, so the tarballs provided
 169 automatically by the cgit frontend are official release tarballs.
 170
 171
 172 \ Contributing Patches
 173  ---------------------
 174
 175 If you want to contribute patches, please subscribe to the piglit
 176 mailing list (http://lists.freedesktop.org/mailman/listinfo/piglit)
 177 and then send them to piglit@lists.freedesktop.org using "git
 178 send-email".  One of the core piglit developers should respond with
 179 comments and suggested improvements.  The piglit mailing list is also
 180 a good place for general discussion about piglit development, such as
 181 future plans for the project, and coordinating work between
 182 developers.
 183
 184 Note that Piglit patches use the terms "Reviewed-by", "Tested-by", and
 185 "Acked-by" in the same way as they are used for Linux kernel patches
 186 (see https://www.kernel.org/doc/Documentation/SubmittingPatches).  You
 187 are also welcome to add a "Signed-off-by" line to your patch, but it
 188 is not required.
 189
 190 For developers who are new to piglit: when submitting a patch, it is
 191 helpful to add a note (after the "---" line in the patch file)
 192 indicating that you are new to the project and don't have commit
 193 access; that way once your patch has been revised to meet our
 194 standards of correctness and coding style, we will know that we should
 195 commit it for you.  If we forget, please remind us!  Once you have
 196 successfully contributed a handful of patches, feel free to apply for
 197 commit access usind the process described here:
 198 http://www.freedesktop.org/wiki/AccountRequests/
 199
 200 Please be patient--most of us develop graphics drivers (such as Mesa)
 201 as our primary job, so we have limited time to respond to your patches
 202 on the piglit mailing list.  If your patch hasn't received a reply in
 203 a week, send a follow-up email to make sure we haven't missed it.  If
 204 you have questions that are better discussed in real time, many piglit
 205 developers can also be found in the #dri-devel channel on Freenode
 206 IRC.