Re: [Qemu-devel] [PATCH] Kconfig: add documentation

[Markus Armbruster <armbru@redhat.com>]

Paolo Bonzini <pbonzini@redhat.com> writes:

> On 12/02/19 10:08, Markus Armbruster wrote:
>> Please wrap your lines at column 70 or so.  Humans tend to have trouble
>> following long lines with their eyes (I sure do).  Typographic manuals
>> suggest to limit columns to roughly 60 characters for exactly that
>> reason[*].
>
> Yup, fixed in v2.
>
>>> +Each QEMU target enables a subset of the boards, devices and buses that are included
>>> +in QEMU's source code.  As a result, each QEMU executable only links a small subset
>> 
>> Really?  Hmm...
>> 
>> $ size aarch64-softmmu/qemu-system-aarch64
>>    text	   data	    bss	    dec	    hex	filename
>> 19183216	7200124	 592732	26976072	19b9f48	aarch64-softmmu/qemu-system-aarch64
>> $ size -t `find -name \*.o `| grep TOT
>> 92713559	18652227	1183961440	1295327226	4d351ffa	(TOTALS)
>> 
>> Yep, really.
>
> Haha. :)
>
>>> +  Optionally, a condition for applying the default value can be added with
>>> +  ``if``.  A config option can have any number of default values (usually, if more than
>>> +  one default is present, they will have different conditions). If multiple
>>> +  default values satisfy their condition, only the first defined one is active.
>> 
>> Hmm.  Is "multiple default values, first one wins" a healthy state?
>> How obvious is "first defined" to humans?  
>
> It certainly helps that we never have more than one default. :)

True!

> I could also be persuaded to remove "default n", so that multiple
> "default y" clauses are just an OR of the conditions and the ordering
> does not matter.

I'm looking for something that doesn't involve too much global
reasoning.

"All default directives must provide the same value; their conditions
are ORed" feels fine to me.  Order doesn't matter then.  "if <expr>"
really means "if", not "if-and-only-if", and that's fine.

Additionally permitting an *unconditional* default with the negated
value would still be okay, I guess.  But I'd do that only when we have a
use.

> Are multiple "default y" clauses useful?  They were there in earlier
> versions of the patches, for now "imply" has removed the need
> everywhere.  However, I'm not sure it's a good idea to remove them
> altogether before we try to extend Kconfig to more features.  (A
> secondary effect of the documentation is to clarify the current scope of
> Kconfig).

My general advice would be YAGNI.  However, keeping currently unused
features around while we grow Kconfig makes sense to me.

>>> +**reverse default** (weak reverse dependency): ``imply <symbol> [if <expr>]``
>> 
>> If "reverse default" can be regarded as weak reverse dependency, could
>> "default value" be regarded as weak (forward) dependency?
>
> "default n if" could, but we never use it.  This also shows how we use
> the language in a very limited way, according to the very simple rules
> in the second part of the document; but even Linux only has a handful of
> occurrences of "default n if".
>
>>> +
>>> +  This is similar to ``select`` as it applies a lower limit of ``y`` to another
>>> +  symbol.  However, the lower limit is only a default and the "implied" symbol's
>>> +  value may still be set to ``n`` from a ``default-configs/*.mak`` files.  The
>> 
>> I'm afraid I don't get "lower limit".  What's the ordering relation?
>
> False < true, so "lower limit of y" means "tries to force to y".  The
> difference is that a contradiction is ignored by "imply" (and then the
> symbol remains at n), while it causes a build error for "select".

Can we use this explanation to rephrase the documentation in simpler
language?

Let me summarize to see whether I got it.  Please correct
misunderstandings.

* "depends on" forces to false unless condition is met

* "select" forces to true if condition is met

* Contradictions between "depends on" and "select" are rejected

* If neither applies, default-configs/*.mak may supply the value

* If it doesn't, "default" / "imply" supply the value if condition is
  met

* What about contradictions between "default" / "imply"?


PS: Thanks for writing down intended use in "Guidelines for writing
Kconfig files", not just the language specification, makes the document
so much more useful.