+<h2 id="envvars">Environment Variables</h2>
+
+<p>
+The <b>MESA_GLSL</b> environment variable can be set to a comma-separated
+list of keywords to control some aspects of the GLSL compiler and shader
+execution. These are generally used for debugging.
+</p>
+<ul>
+<li><b>dump</b> - print GLSL shader code to stdout at link time
+<li><b>log</b> - log all GLSL shaders to files.
+ The filenames will be "shader_X.vert" or "shader_X.frag" where X
+ the shader ID.
+<li><b>cache_info</b> - print debug information about shader cache
+<li><b>cache_fb</b> - force cached shaders to be ignored and do a full
+ recompile via the fallback path</li>
+<li><b>uniform</b> - print message to stdout when glUniform is called
+<li><b>nopvert</b> - force vertex shaders to be a simple shader that just transforms
+ the vertex position with ftransform() and passes through the color and
+ texcoord[0] attributes.
+<li><b>nopfrag</b> - force fragment shader to be a simple shader that passes
+ through the color attribute.
+<li><b>useprog</b> - log glUseProgram calls to stderr
+</ul>
+<p>
+Example: export MESA_GLSL=dump,nopt
+</p>
+
+<h3 id="replacement">Experimenting with Shader Replacements</h3>
+<p>
+Shaders can be dumped and replaced on runtime for debugging purposes. This
+feature is not currently supported by SCons build.
+
+This is controlled via following environment variables:
+<ul>
+<li><b>MESA_SHADER_DUMP_PATH</b> - path where shader sources are dumped
+<li><b>MESA_SHADER_READ_PATH</b> - path where replacement shaders are read
+</ul>
+Note, path set must exist before running for dumping or replacing to work.
+When both are set, these paths should be different so the dumped shaders do
+not clobber the replacement shaders. Also, the filenames of the replacement shaders
+should match the filenames of the corresponding dumped shaders.
+</p>
+
+<h3 id="capture">Capturing Shaders</h3>
+
+<p>
+Setting <b>MESA_SHADER_CAPTURE_PATH</b> to a directory will cause the compiler
+to write <tt>.shader_test</tt> files for use with
+<a href="https://cgit.freedesktop.org/mesa/shader-db">shader-db</a>, a tool
+which compiler developers can use to gather statistics about shaders
+(instructions, cycles, memory accesses, and so on).
+</p>
+<p>
+Notably, this captures linked GLSL shaders - with all stages together -
+as well as ARB programs.
+</p>
+
+<h2 id="support">GLSL Version</h2>
+
+<p>
+The GLSL compiler currently supports version 3.30 of the shading language.
+</p>
+
+<p>
+Several GLSL extensions are also supported:
+</p>
+<ul>
+<li>GL_ARB_draw_buffers
+<li>GL_ARB_fragment_coord_conventions
+<li>GL_ARB_shader_bit_encoding
+</ul>
+
+
+<h2 id="unsup">Unsupported Features</h2>
+
+<p>XXX update this section</p>