Directory Layout
================
- data
  Data files for tests, such as reference images, vertex data, texture
  images, etc.

- misc
  If you want Crucible to play nicely with bash, zsh, vim, emacs, or whatever,
  then look in misc/.

- src/tests
  Source for the tests themselves.

- src/tests/examples
  Example tests that demonstrate how to use the framework or how to accomplish
  a tricky testing task.

- src/tests/func: Functional tests

- src/tests/stress: Stress tests

- src/tests/self: Self-tests for Crucible. Used by `make check`.

- include
  Headers under include/ define each module's public API.  This contrasts with
  headers under src/, which are private to their containing directory.

- include/tapi
  The test API. Functions that begin with 't_' may be called only inside
  a running test thread.

- include/qonos
  Wrappers around the Vulkan API that make life easier for test authors.

- include/util
  Utilities that may be used by any module. They are safe to use inside or
  outside running test threads. Consider this to be Crucible's "standard
  library".

- include/framework
  Crucible's framework APIs are off-limits to test code ( (that is, by code
  under src/tests/).



Writing Tests
=============
Tests live in the 'src/tests' directory.

Tests have access to the APIs in the 'include/' directory (except
'include/framework/', which is reserved for Crucible's test framework).

After writing a test, you will likely need to generate a reference image for
it.  The command 'crucible bootstrap' can generate one for you.

All images in the 'data' directory are available to tests. You can load an
image with `t_new_cru_image_from_filename(filename)`, where filename is
relative to the 'data' directory.



Generated Files
===============
The names of generated source files should match the glob "*_gen.[ch]".

Do not commit generated image files. They consume too much space in the git
history.

Do commit a generated source file if the diff of the generated file is
substantially more reviewable and informative than the diff of the generator
script. Often, small cryptic changes to a generator script will produce easily
understood changes in its generated files. As a corollary, if a generated file
is commited, then its generator script must produce deterministic output.

Do not commit a generated source file if it doesn't satisfy the "reviewability"
criterion above.