[Mesa-dev] [PATCH v2] docs: update MESA_DEBUG envvar documentation.

[Alejandro Piñeiro]

On 30/06/16 15:28, Brian Paul wrote:
> On 06/29/2016 09:50 AM, Alejandro Piñeiro wrote:
>> silent, flush, incomplete_tex and incomplete_fbo flags were not
>> documented (see src/mesa/main.debug.c for more info).
>>
>> FP is not checked anymore.
>>
>> v2 (Brian Paul):
>>   * MESA_DEBUG accepts a comma-separated list of parameters.
>>   * Clarify how MESA_DEBUG behaves with mesa debug and release builds.
>>   * Updated wording.
>> ---
>>
>> Tried to answer all the comments from previous review on the
>> documentation itself.
>>
>> Initially I had the following paragraph as an extra explanation:
>>
>> "MESA_DEBUG=1 on release builds is equivalent to the default behaviour
>> of debug builds. MESA_DEBUG=silent on debug builds is equivalent to
>> the default behaviour of release builds."
>>
>> But I think that is not needed, as should be understood from the
>> documentation.
>>
>>   docs/envvars.html | 15 +++++++++++++--
>>   1 file changed, 13 insertions(+), 2 deletions(-)
>>
>> diff --git a/docs/envvars.html b/docs/envvars.html
>> index ed957bd..7d19fb3 100644
>> --- a/docs/envvars.html
>> +++ b/docs/envvars.html
>> @@ -50,8 +50,19 @@ sometimes be useful for debugging end-user issues.
>>      if the application generates a GL_INVALID_ENUM error, a
>> corresponding error
>>      message indicating where the error occurred, and possibly why,
>> will be
>>      printed to stderr.<br>
>> -   If the value of MESA_DEBUG is 'FP' floating point arithmetic
>> errors will
>> -   generate exceptions.
>> +
>> +   MESA_DEBUG=1 is not needed for mesa debug builds, as it is the
>> +   behaviour by default. It would be needed for mesa release builds,
>> +   that silent debug messages.<br>
>
> The second sentence is a bit off.  How about this:  "For release
> builds, MESA_DEBUG defaults to off (no debug output)."

Ok.

>
>
>> +
>> +   MESA_DEBUG accepts the following comma-separated list of named
>> +   flags, which adds extra behaviour to just set MESA_DEBUG=1:
>> +   <ul>
>> +     <li>silent - turn off debug messages. Only useful for debug
>> builds.</li>
>> +     <li>flush - flush after each drawing command</li>
>> +     <li>incomplete_tex - extra debug messages when a texture is
>> incomplete</li>
>> +     <li>incomplete_fbo - extra debug messages when a fbo is
>> incomplete</li>
>> +   </ul>
>>   <li>MESA_LOG_FILE - specifies a file name for logging all errors,
>> warnings,
>>   etc., rather than stderr
>>   <li>MESA_TEX_PROG - if set, implement conventional texture env
>> modes with
>>
>
> With that, Reviewed-by: Brian Paul <brianp at vmware.com>

Thanks. Just pushed.

>
> Longer term, MESA_DEBUG should be cleaned up.  It's a bit of a
> hodgepodge now.
>

Yes, right it is hard to follow the debug logic unless you check the
code. For example getenv(MESA_DEBUG) is called in several places of the
code. Probably it would be better to call it once, at main/debug.c, when
the DEBUG_FLAGS are initialized.

BR