Bug 34361 - Mesa needs a man-page or several
Summary: Mesa needs a man-page or several
Alias: None
Product: Mesa
Classification: Unclassified
Component: Other (show other bugs)
Version: git
Hardware: All All
: medium normal
Assignee: mesa-dev
QA Contact:
Depends on:
Reported: 2011-02-16 16:12 UTC by Sergey Kondakov
Modified: 2018-03-08 02:42 UTC (History)
0 users

See Also:
i915 platform:
i915 features:


Description Sergey Kondakov 2011-02-16 16:12:27 UTC
it would be really handy to have mesa manual page with brief info about mesa&gallium and all stuff it consist of. especially environmental variables which are kind of runtime options, so it would be essential for users to know runtime options their mesa driver have and what they do.
besides, such variables hidden deep inside mesa&gallium driver code, changing its behaviour, without up-to-date listing may be seen by some as "undocumented features" which are hated by IT security people.
Comment 1 Tormod Volden 2011-02-17 01:48:23 UTC
There is an old list of environmental variables here: http://dri.freedesktop.org/wiki/TestingAndDebugging
Comment 2 Sergey Kondakov 2011-02-17 05:36:04 UTC
yeah, as you said, it's old, it's also incomplete and, what's more importantly, it's not on _my_ system when i installed mesa.

of course, i can grep the shit out those html docs that come with tarballs and hope that they up-to-date and i didn't missed anything but it's hardly a suitable alternative.
Comment 3 Tormod Volden 2011-02-17 06:23:53 UTC
Yes, I was not saying that this resolves the documentation issue per your bug report. I was just pointing to this information; if you are putting together a man page maybe you will find this wiki page helpful.
Comment 4 Brian Paul 2011-02-17 06:37:20 UTC
I've updated the docs/envvars.html page with more environment variables, and removed some old ones.  The website is updated too.

Note that almost all of the Mesa/Gallium env vars are for debugging and only used by the developers.  These env vars can often change and new ones are added as the drivers evolve.

A man page might be useful, but I think someone will have step up to contribute it and maintain it.  Would you be interested in doing that, Sergey?
Comment 5 Sergey Kondakov 2011-02-17 07:46:21 UTC
it _is_ very interesting link, especially part with:
"Due to their specificity and volatility is _not worth to have all driver specific environment variables here_. An interesting way to list them is to do:
    * strings /usr/X11R6/lib/modules/dri/<driver>_dri.so | grep DEBUG"

i'd say that specificity and volatility is exactly the reasons to have them properly documented but page suggest to poke the damn binary.

there are bits and pieces like that and you can't be sure if it does what it says it does or that it even works. only devs who go around insides can reliably say what the hell the situation with all those variables is.

when there are news about some new feature or a problem with some functionality and people go for advice to some place like Phoronix forums they can be quite surprised that there is some hidden switch. i can see benefits of putting temporary/undocumented env. vars for developers but they surely don't want to be single testers of their code or worse, to forget to remove them later (and something tells me - there are plenty of those) or something like that.
if one would want to write a manual the last thing he would want is snooping around a load of code, htmls and watch in binaries unless one does that already on daily basis. and if one wants just RTFM, it's not very cool to have him to write it first.

so, it's not just about having a manual but also about updating it, i.e. documenting development more which is thing for devs to do.

but, i still need to understand why damn googleearth segfaults on both my machines with r300g and r600g and for that i need some more output from libGL and r*00_dri before crash and for that i need to find radeon switches and _maybe_ i will not be lazy in that moment and come up with something :) no promises or commitment though yet.

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.