Bug 11826 - Unclear documentation on boolean environment variables
Unclear documentation on boolean environment variables
Status: CLOSED FIXED
Product: ccache
Classification: Unclassified
Component: ccache
3.2.4
All All
: P5 normal
: 3.2.5
Assigned To: Joel Rosdahl
Joel Rosdahl
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2016-04-08 19:09 UTC by Jim Klimov
Modified: 2016-04-17 14:49 UTC (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Jim Klimov 2016-04-08 19:09:05 UTC
It seems that if the CCACHE_DISABLE envvar is defined and exported (with any value - empty, "1", "0", "yes", "no", "true", "false" etc.) then it is treated as "true" and disables ccache.

It is easy to reproduce with:

jim@jimoi:~$ unset CCACHE_DISABLE
jim@jimoi:~$ ccache -p | grep -i disable
(default) disable = false
jim@jimoi:~$ export CCACHE_DISABLE
jim@jimoi:~$ ccache -p | grep -i disable
(default) disable = false
jim@jimoi:~$ export CCACHE_DISABLE=""
jim@jimoi:~$ ccache -p | grep -i disable
(environment) disable = true
jim@jimoi:~$ export CCACHE_DISABLE=false
jim@jimoi:~$ ccache -p | grep -i disable
(environment) disable = true

I'd treat this as a ccache bug (did not dig if it ever worked or this is a recent regression), since both the documentation and sources state it is a boolean value with different behaviors for at least "true" and "false".

The "test.sh" sets it to "1" by the way.

The few mentions in the codebase led me to fear if other booleans are similarly mis-interpreted. Yep, they are:

jim@jimoi:~$ ccache -p | grep -i hard
(default) hard_link = false
jim@jimoi:~$ export CCACHE_HARDLINK=false
jim@jimoi:~$ ccache -p | grep -i hard
(environment) hard_link = true
jim@jimoi:~$ export CCACHE_HARDLINK=true
jim@jimoi:~$ ccache -p | grep -i hard
(environment) hard_link = true
jim@jimoi:~$ export CCACHE_HARDLINK=""
jim@jimoi:~$ ccache -p | grep -i hard
(environment) hard_link = true
jim@jimoi:~$ unset CCACHE_HARDLINK
jim@jimoi:~$ ccache -p | grep -i hard
(default) hard_link = false
Comment 1 Joel Rosdahl 2016-04-08 20:07:37 UTC
The boolean environment variables have always worked that way. The corresponding variables in configuration files (a much newer invention) work in another way as documented on https://ccache.samba.org/manual.html#_boolean_values:

| Some settings are boolean values (i.e. truth values). In a configuration
| file, such values must be set to the string true or false. For the
| corresponding environment variables, the semantics are a bit different: a
| set environment variable means “true” regardless of the value (even if set
| to the empty string), and an unset environment variable means “false”. Each
| boolean environment variable also has a negated form starting with
| CCACHE_NO. For example, CCACHE_COMPRESS can be set to force compression
| and CCACHE_NOCOMPRESS can be set to force no compression.

So no, not a bug, but intended behavior. The reasons for having different behavior for configuration and environment variables are 1) I thought that it would make no sense to use the environment variable semantics for configuration settings and 2) I needed to keep the old semantics for environment variables for backward compatibility reasons.

Do you have any suggestion on what the documentation could have said so that you wouldn't have treated this as a bug?
Comment 2 Jim Klimov 2016-04-14 11:50:36 UTC
Strange, apparently my email replies did not pass back to bugzilla. Re-posting below:

1) If there are legacy uses that rely on "envvar set to anything == switch flipped", it is counter-intuitive and sort of sad.

I'm in no position to enforce a solution, but I would rather at least treat the keywords mentioned in the manpage ('true' and 'false') at face value. On one hand, this would allow reliable explicit configuration in build-ware scripts even if ccache defaults were to change in the future, and on the other hand this would match the docs which (AFAIK) do not stress non-identical behavior for different ways of passing the "same" options - ergo, they should (are expected to) behave the same way.

At the very least, if current behavior is to remain, the manpage should state that 'any envvar value for this boolean parameter switches it into the non-default state'. And say so near each such parameter, since people tend to skim over documentation only looking for bits they need - so if this notice were located far from context, it will not be noticed ;)

2) Oh, the phone initially hid your quoted bit of documentation. And I did not realize the ccache_NO options since I only looked directly at list of options I'd like to play with in the man page. (Kind'a stresses the 'far away from context location' point).

Then perhaps the minimal solution - an intuitive manpage fix - would be more simple and compact: just mention both forms of the envvar near config options, e.g.
"disable (CCACHE_DISABLE or CCACHE_NODISABLE) ..." - those interested readers would either get the point, or have a reason to dig the docs for details.

Thanks,
Jim Klimov
Comment 3 Joel Rosdahl 2016-04-14 18:19:52 UTC
> Then perhaps the minimal solution - an intuitive manpage fix - would be
> more simple and compact: just mention both forms of the envvar near config
> options, e.g. "disable (CCACHE_DISABLE or CCACHE_NODISABLE) ..." - those
> interested readers would either get the point, or have a reason to dig the
> docs for details.

Good idea. I made a variant of your suggestion:

https://git.samba.org/?p=ccache.git;a=commitdiff;h=f6dfd815f7eae4e12c83ee4a9159333425782fe1;hp=5755f6a4b8bd479d2b8723c2f3e43db585429641

Sounds OK?
Comment 4 Jim Klimov 2016-04-14 18:23:30 UTC
Yes, looks good, thanks :)
Jim
Comment 5 Joel Rosdahl 2016-04-17 14:49:35 UTC
Included in 3.2.5.