[PATCH v1] kconfig: add config and source entry details

[PATCH v1] kconfig: add config and source entry details

[Prasad Pandit]

From: Prasad Pandit <pjp@fedoraproject.org>

Add details to the 'config' and 'source' entry description,
to make it unambiguous. It'd come handy as reference for
Kconfig language or patch reviews for Kconfig source files.

Signed-off-by: Prasad Pandit <pjp@fedoraproject.org>
---
 Documentation/kbuild/kconfig-language.rst | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

v1:
 - Fix typo path -> patch
 - https://lore.kernel.org/linux-kbuild/20240404064037.3440433-1-ppandit@redhat.com/T/#u

diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
index 0135905c0aa3..0783850d5a00 100644
--- a/Documentation/kbuild/kconfig-language.rst
+++ b/Documentation/kbuild/kconfig-language.rst
@@ -39,11 +39,14 @@ them. A single configuration option is defined like this::
 	  kernel.  ...
 
 Every line starts with a key word and can be followed by multiple
-arguments.  "config" starts a new config entry. The following lines
-define attributes for this config option. Attributes can be the type of
-the config option, input prompt, dependencies, help text and default
-values. A config option can be defined multiple times with the same
-name, but every definition can have only a single input prompt and the
+arguments.  "config" starts a new config entry. The following lines,
+indented by a leading tab (\t) character, define attributes for this
+config option. Attributes can be the type of the config option,
+input prompt, dependencies, default values and help text. Help text
+is further indented by two more spaces.
+
+A config option can be defined multiple times with the same name,
+but every definition can have only a single input prompt and the
 type must not conflict.
 
 Menu attributes
@@ -451,6 +454,11 @@ source::
 	"source" <prompt>
 
 This reads the specified configuration file. This file is always parsed.
+The specified file path is from the top source directory ($SRCTREE).
+It allows one to source a file from any subdirectory under the source
+tree. Such path is always unique under the source directory.
+A configuration file must terminate with a new line (\n) character
+at the end.
 
 mainmenu::
 
-- 
2.44.0

Re: [PATCH v1] kconfig: add config and source entry details

[Prasad Pandit]

>On Sunday, 7 April, 2024 at 12:59:48 pm IST, Prasad Pandit wrote: 
>From: Prasad Pandit <pjp@fedoraproject.org>
>
>Add details to the 'config' and 'source' entry description,
>to make it unambiguous. It'd come handy as reference for
>Kconfig language or patch reviews for Kconfig source files.
>
>Signed-off-by: Prasad Pandit <pjp@fedoraproject.org>
>---
>Documentation/kbuild/kconfig-language.rst | 18 +++++++++++++-----
>1 file changed, 13 insertions(+), 5 deletions(-)
>

-> https://lore.kernel.org/linux-kbuild/20240407072933.3562124-1-ppandit@redhat.com/T/#u


Ping...!(just checking)
---
  - Prasad

Re: [PATCH v1] kconfig: add config and source entry details

[Masahiro Yamada]

On Sun, Apr 7, 2024 at 4:29 PM Prasad Pandit <ppandit@redhat.com> wrote:
>
> From: Prasad Pandit <pjp@fedoraproject.org>
>
> Add details to the 'config' and 'source' entry description,
> to make it unambiguous. It'd come handy as reference for
> Kconfig language or patch reviews for Kconfig source files.
>
> Signed-off-by: Prasad Pandit <pjp@fedoraproject.org>
> ---
>  Documentation/kbuild/kconfig-language.rst | 18 +++++++++++++-----
>  1 file changed, 13 insertions(+), 5 deletions(-)
>
> v1:
>  - Fix typo path -> patch
>  - https://lore.kernel.org/linux-kbuild/20240404064037.3440433-1-ppandit@redhat.com/T/#u
>
> diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
> index 0135905c0aa3..0783850d5a00 100644
> --- a/Documentation/kbuild/kconfig-language.rst
> +++ b/Documentation/kbuild/kconfig-language.rst
> @@ -39,11 +39,14 @@ them. A single configuration option is defined like this::
>           kernel.  ...
>
>  Every line starts with a key word and can be followed by multiple
> -arguments.  "config" starts a new config entry. The following lines
> -define attributes for this config option. Attributes can be the type of
> -the config option, input prompt, dependencies, help text and default
> -values. A config option can be defined multiple times with the same
> -name, but every definition can have only a single input prompt and the
> +arguments.  "config" starts a new config entry. The following lines,
> +indented by a leading tab (\t) character, define attributes for this
> +config option. Attributes can be the type of the config option,
> +input prompt, dependencies, default values and help text. Help text
> +is further indented by two more spaces.


Wrong.

You added

 - indented by a leading tab (\t) character,
 - Help text is further indented by two more spaces.


These are recommended coding styles for readability,
not grammatical requirements.



You can write Kconfig code without indentation,
without blank lines in-between.


config FOO
bool "foo"
depends on BAR
config BAR
bool "bar"
config BAZ
bool "baz"


It is unreadable, but it works fine.



Only the place where the indentation plays an act
is the end of help. It is already documented.

  The end of the help text is determined by
  the indentation level, this means it ends at the first line which has
  a smaller indentation than the first line of the help text.





The kernel coding style is documented
in a different file.



See Documentation/process/coding-style.rst


 10) Kconfig configuration files
 -------------------------------








> +
> +A config option can be defined multiple times with the same name,
> +but every definition can have only a single input prompt and the
>  type must not conflict.
>
>  Menu attributes
> @@ -451,6 +454,11 @@ source::
>         "source" <prompt>
>
>  This reads the specified configuration file. This file is always parsed.
> +The specified file path is from the top source directory ($SRCTREE).


No.

Kconfig searches for the sourced file in the current working directory.
If not found, it searches from $SRCTREE next.




> +It allows one to source a file from any subdirectory under the source
> +tree. Such path is always unique under the source directory.
> +A configuration file must terminate with a new line (\n) character
> +at the end.
>
>  mainmenu::
>
> --
> 2.44.0
>


--
Best Regards
Masahiro Yamada

Re: [PATCH v1] kconfig: add config and source entry details

[Prasad Pandit]

Hello Masahiro,

On Tuesday, 16 April, 2024 at 05:19:40 pm IST, Masahiro Yamada <masahiroy@kernel.org> wrote:>
>You added
>
>- indented by a leading tab (\t) character,
>- Help text is further indented by two more spaces.
>
>These are recommended coding styles for readability,
>not grammatical requirements.

  -> https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html

* I see, thank you for the clarification. Reading this language reference and seeing the config entries consistently using indentation in Kconfig files, I mistook it as language syntax.

* Maybe it'll help to explicitly specify that indentation is not the Kconfig language syntax.


>You can write Kconfig code without indentation,
>without blank lines in-between.
>
>
>config FOO
>bool "foo"
>depends on BAR
>config BAR
>bool "bar"
>config BAZ
>bool "baz"
>
>
>It is unreadable, but it works fine.
>
>
>Only the place where the indentation plays an act
>is the end of help. It is already documented.
>
>  The end of the help text is determined by
>  the indentation level, this means it ends at the first line which has
>  a smaller indentation than the first line of the help text.
>

* Got it. In that case, to confirm: are there any input cases which are erroneous according to the Kconfig language syntax? Because even config entries ending with an 'EOF' are not flagged as an error.


* Last to confirm: is 'kconfig-language.html' reference for the Kconfig langauge as implemented in kernel OR it is the general language reference that applies to all Kconfig files across all projects? Because non-kernel projects also seem to use Kconfig files.


Thank you.
---
  - Prasad

Re: [PATCH v1] kconfig: add config and source entry details

[Masahiro Yamada]

On Wed, Apr 17, 2024 at 3:30 PM Prasad Pandit <pjp@fedoraproject.org> wrote:
>
> Hello Masahiro,
>
> On Tuesday, 16 April, 2024 at 05:19:40 pm IST, Masahiro Yamada <masahiroy@kernel.org> wrote:>
> >You added
> >
> >- indented by a leading tab (\t) character,
> >- Help text is further indented by two more spaces.
> >
> >These are recommended coding styles for readability,
> >not grammatical requirements.
>
>   -> https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html
>
> * I see, thank you for the clarification. Reading this language reference and seeing the config entries consistently using indentation in Kconfig files, I mistook it as language syntax.
>
> * Maybe it'll help to explicitly specify that indentation is not the Kconfig language syntax.
>
>
> >You can write Kconfig code without indentation,
> >without blank lines in-between.
> >
> >
> >config FOO
> >bool "foo"
> >depends on BAR
> >config BAR
> >bool "bar"
> >config BAZ
> >bool "baz"
> >
> >
> >It is unreadable, but it works fine.
> >
> >
> >Only the place where the indentation plays an act
> >is the end of help. It is already documented.
> >
> >  The end of the help text is determined by
> >  the indentation level, this means it ends at the first line which has
> >  a smaller indentation than the first line of the help text.
> >
>
> * Got it. In that case, to confirm: are there any input cases which are erroneous according to the Kconfig language syntax? Because even config entries ending with an 'EOF' are not flagged as an error.


Why should it be flagged as an error?


Kconfig does not require a new line at the end of file.
Same for other languages such as C, Python, etc.



>
> * Last to confirm: is 'kconfig-language.html' reference for the Kconfig langauge as implemented in kernel OR it is the general language reference that applies to all Kconfig files across all projects? Because non-kernel projects also seem to use Kconfig files.


I hoped this file explained Kconfig language as a standalone project.

Apparently, it contains a kernel-specific description.
(e.g. "Compile-testing")



>
>
> Thank you.
> ---
>   - Prasad



-- 
Best Regards
Masahiro Yamada

Re: [PATCH v1] kconfig: add config and source entry details

[Prasad Pandit]

Hi,

On Saturday, 20 April, 2024 at 12:54:59 pm IST, Masahiro Yamada wrote: 
>>Because even config entries ending with an 'EOF' are not flagged as an error.
>Why should it be flagged as an error?

* Kconfig file defines records of config entries, wherein each line starts with a keyword. Line there implies an EOL at the end. So when a config entry does not end with an EOL, then it is inconsistent with other config records, which then requires special handling while parsing. Ex.

   config OPTION-A
      bool
      default 1

   config OPTION-B
      stirng
      default "Value-B"

   ....

   config OPTION-N
      int<EOF>

If the last entry was like int<EOL><EOF>, that makes them entries consistent and easier to parse. I don't see much value in allowing such inconsistency.


>Kconfig does not require a new line at the end of file.
>Same for other languages such as C, Python, etc.

* It's not about EOL at the end of file, but EOL at the end of a config entry/record.

* C, Python all languages define statements to have fixed format ex. in C statement must end with a semi-colon (;), a function definition has to have both opening ({) and closing braces (}). Python requires that a conditional statement must end with a colon (:) character, Python also requires that indentations are consistent.

    $ python t.py 
    File "/tmp/t.py", line 3
      if (x == 10)
                ^
    SyntaxError: expected ':'

And any such digressions are flagged as an error. IMHO, config entry records should have consistent format/syntax.


Thank you.
---
  -Prasad

Re: [PATCH v1] kconfig: add config and source entry details

[Masahiro Yamada]

On Tue, Apr 23, 2024 at 3:41 PM Prasad Pandit <pjp@fedoraproject.org> wrote:
>
> Hi,
>
> On Saturday, 20 April, 2024 at 12:54:59 pm IST, Masahiro Yamada wrote:
> >>Because even config entries ending with an 'EOF' are not flagged as an error.
> >Why should it be flagged as an error?
>
> * Kconfig file defines records of config entries, wherein each line starts with a keyword. Line there implies an EOL at the end. So when a config entry does not end with an EOL, then it is inconsistent with other config records, which then requires special handling while parsing. Ex.
>
>    config OPTION-A
>       bool
>       default 1
>
>    config OPTION-B
>       stirng
>       default "Value-B"
>
>    ....
>
>    config OPTION-N
>       int<EOF>
>
> If the last entry was like int<EOL><EOF>, that makes them entries consistent and easier to parse. I don't see much value in allowing such inconsistency.



EOL is a statement separator.

There is no ambiguity even if the last statement lacks EOL
because the whole code ends with EOF anyway.



Could you give me an example programming language
that errors out when \n is missing at the end of the
source file?



I do not think requiring EOL at the end of file
would help simplify the lexer/parser.

When the lexer is encountered with EOF, it must
tell the parser to finish the current statement
and go back to the previous source file.
So, EOF implies the end of the statement anyway.



> >Kconfig does not require a new line at the end of file.
> >Same for other languages such as C, Python, etc.
>
> * It's not about EOL at the end of file, but EOL at the end of a config entry/record.
>
> * C, Python all languages define statements to have fixed format ex. in C statement must end with a semi-colon (;), a function definition has to have both opening ({) and closing braces (}). Python requires that a conditional statement must end with a colon (:) character, Python also requires that indentations are consistent.
>
>     $ python t.py
>     File "/tmp/t.py", line 3
>       if (x == 10)
>                 ^
>     SyntaxError: expected ':'
>
> And any such digressions are flagged as an error. IMHO, config entry records should have consistent format/syntax.



This is a job of linter or code formatter.


Requiring a new line at the end of a file is a coding style.
Not a grammatical requirement.







>
>
> Thank you.
> ---
>   -Prasad



-- 
Best Regards
Masahiro Yamada

Re: [PATCH v1] kconfig: add config and source entry details

[Prasad Pandit]

Hi,

On Tuesday, 23 April, 2024 at 03:41:35 pm IST, Masahiro Yamada <masahiroy@kernel.org> wrote: 
>EOL is a statement separator.

* Right. So are semi-colon (;), braces (}{) and colon (:) in case of C and Python.

===
$ cat t.c

#include <stdio.h>

int main (void)
{ printf("Hello, world!\n");$
$
$ cc -xc -o t t.c 
t.c: In function ‘main’:
t.c:6:1: error: expected declaration or statement at end of input
    6 | { printf("Hello, world!\n");
      | ^
---

$ cat t.py
#!/usr/bin/python

if (x == 10)$
$
$ python t.py 
  File "/tmp/im/t.py", line 3
    if (x == 10)
                ^
SyntaxError: expected ':'
===

* In above examples, files terminate without completing the statement and/or function definition (missing closing brace '}'), which is being treated as an error.


>Could you give me an example programming language
>that errors out when \n is missing at the end of the
>source file?

* It is not about '\n' at the end of file, but '\n' at the end of the Kconfig statement/record. Because Kconfig language uses EOL as a separator.


> I do not think requiring EOL at the end of file would help simplify the lexer/parser.

* It does, because on the parser side you don't have to define rule(s) with EOF to parse statements.


>When the lexer is encountered with EOF, it must
>tell the parser to finish the current statement
>and go back to the previous source file.
>So, EOF implies the end of the statement anyway.

* No, EOF does not imply end of a statement. The errors reported by gcc(1) and Python above clearly confirm that EOF is not end of statement.

* In their case colon(':') or brace ('}') are the required terminators, whereas in Kconfig's case EOL ('\n') is the required terminator.

* Because Kconfig language uses EOL ('\n') as statement separator/terminator, IMHO it should display an error when that condition is not met, because such statement remains incomplete.


Thank you.
---
  -Prasad

Re: [PATCH v1] kconfig: add config and source entry details

[Masahiro Yamada]

[-- Attachment #1: Type: text/plain, Size: 3241 bytes --]

On Wed, Apr 24, 2024 at 2:27 PM Prasad Pandit <pjp@fedoraproject.org> wrote:
>
> Hi,
>
> On Tuesday, 23 April, 2024 at 03:41:35 pm IST, Masahiro Yamada <masahiroy@kernel.org> wrote:
> >EOL is a statement separator.
>
> * Right. So are semi-colon (;), braces (}{) and colon (:) in case of C and Python.
>
> ===
> $ cat t.c
>
> #include <stdio.h>
>
> int main (void)
> { printf("Hello, world!\n");$
> $
> $ cc -xc -o t t.c
> t.c: In function ‘main’:
> t.c:6:1: error: expected declaration or statement at end of input
>     6 | { printf("Hello, world!\n");
>       | ^



It is because the missing closing brace
is a grammatical error.



> ---
>
> $ cat t.py
> #!/usr/bin/python
>
> if (x == 10)$
> $
> $ python t.py
>   File "/tmp/im/t.py", line 3
>     if (x == 10)
>                 ^
> SyntaxError: expected ':'
> ===
>
> * In above examples, files terminate without completing the statement and/or function definition (missing closing brace '}'), which is being treated as an error.



Again, this is wrong Python code. That's why.





>
>
> >Could you give me an example programming language
> >that errors out when \n is missing at the end of the
> >source file?
>
> * It is not about '\n' at the end of file, but '\n' at the end of the Kconfig statement/record. Because Kconfig language uses EOL as a separator.
>
>
> > I do not think requiring EOL at the end of file would help simplify the lexer/parser.
>
> * It does, because on the parser side you don't have to define rule(s) with EOF to parse statements.


Do you see any grammar that treats T_EOF in
scripts/kconfig/parser.y ?
It only handles T_EOL.

The parser is already simplified.



>
> >When the lexer is encountered with EOF, it must
> >tell the parser to finish the current statement
> >and go back to the previous source file.
> >So, EOF implies the end of the statement anyway.
>
> * No, EOF does not imply end of a statement. The errors reported by gcc(1) and Python above clearly confirm that EOF is not end of statement.



In Python, a newline (and also a semicolon)
separates two statements, but it does not mean
it is required at the end of file.


If EOF is encountered, the statement ends.




I attached two Python scripts for you.

test.py and test2.py are almost the same.

Only the difference is that
test2.py lacks a new line at the end of file.



masahiro@zoe:/tmp$ cat test.py
#!/usr/bin/python
print("A")
print("B")
masahiro@zoe:/tmp$ cat test2.py
#!/usr/bin/python
print("A")
print("B")masahiro@zoe:/tmp$



masahiro@zoe:/tmp$ ./test.py
A
B
masahiro@zoe:/tmp$ chmod +x test2.py
masahiro@zoe:/tmp$ ./test2.py
A
B



As I said, it is a linter's job (e.g. pylint)
to check the missing newline at the end.




>
> * In their case colon(':') or brace ('}') are the required terminators, whereas in Kconfig's case EOL ('\n') is the required terminator.
>
> * Because Kconfig language uses EOL ('\n') as statement separator/terminator, IMHO it should display an error when that condition is not met, because such statement remains incomplete.
>
>
> Thank you.







-- 
Best Regards
Masahiro Yamada

[-- Attachment #2: test.py --]
[-- Type: text/x-python, Size: 40 bytes --]

#!/usr/bin/python
print("A")
print("B")

[-- Attachment #3: test2.py --]
[-- Type: text/x-python, Size: 39 bytes --]

#!/usr/bin/python
print("A")
print("B")

Re: [PATCH v1] kconfig: add config and source entry details

[Prasad Pandit]

Hi,


On Saturday, 27 April, 2024 at 12:51:45 am IST, Masahiro Yamada wrote:
>Do you see any grammar that treats T_EOF in
>scripts/kconfig/parser.y ? It only handles T_EOL.
>

* Right. If the parser rule is expecting EOL, but still works when there's no EOL, that seems like a discrepancy.

* If you think that's okay, then that's fine. It'll help if the implementation is documented as is in the Kconfig language page ('kconfig-language.html').


Thank you.
---
  -Prasad