kconfig: add config and source entry details
Subsystems (3)
PATCH 1/1 kconfig: add config and source entry details
From: Prasad Pandit <[email protected]>
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.
--- Documentation/kbuild/kconfig-language.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-)
v1:
- Fix typo path -> patch
- https://lore.kernel.org/linux-kbuild/[email protected]/T/#u
Documentation/kbuild/kconfig-language.rst +13 -5
@@ -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::
Signature · 1 line
2.44.0
Quoted 12 lines · Prasad Pandit
From: Prasad Pandit <[email protected]>
Add details to the 'config' and 'source' entry description, to make it unambiguous. It'd come handy as reference for
Kconfiglanguage or patch reviews forKconfigsource files.Signed-off-by Prasad Pandit <[email protected]>---
Documentation/kbuild/kconfig-language.rst| 18 +++++++++++++-----1 file changed, 13 insertions(+), 5 deletions(-)
-> https://lore.kernel.org/linux-kbuild/[email protected]/T/#u
Ping...!(just checking)
---
- Prasad
Quoted 24 lines · Prasad Pandit
From: Prasad Pandit <[email protected]>
Add details to the 'config' and 'source' entry description, to make it unambiguous. It'd come handy as reference for
Kconfiglanguage or patch reviews forKconfigsource files.Signed-off-by Prasad Pandit <[email protected]>--- Documentation/kbuild/kconfig-language.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-)v1:
- Fix typo path -> patch
- https://lore.kernel.org/linux-kbuild/[email protected]/T/#uDocumentation/kbuild/kconfig-language.rst +0
-0@@ -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
Documentation/kbuild/kconfig-language.rst them. A single configuration option is defined like this:: · line 46
Quoted 10 lines
Documentation/kbuild/kconfig-language.rst +5
-5-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
-------------------------------
Documentation/kbuild/kconfig-language.rst source:: · line 457
Quoted 11 lines
Documentation/kbuild/kconfig-language.rst +4
-0+ +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.
Quoted 10 lines
Documentation/kbuild/kconfig-language.rst +4
-1+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
Hello Masahiro,
On Tuesday, 16 April, 2024 at 05:19:40 pm IST, Masahiro Yamada <[email protected]> wrote:>
Quoted 7 lines
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.
Quoted 16 lines
You can write
Kconfigcode 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.
Quoted 7 lines
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
Quoted 38 lines · Prasad Pandit
Hello Masahiro,
On Tuesday, 16 April, 2024 at 05:19:40 pm IST, Masahiro Yamada <[email protected]> wrote:>
Quoted 7 lines
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
Kconfigfiles, I mistook it as language syntax.* Maybe it'll help to explicitly specify that indentation is not the
Kconfiglanguage syntax.Quoted 19 lines
You can write
Kconfigcode 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.
Quoted 6 lines
Quoted 4 lines
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
Kconfiglanguage 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.
Quoted 2 lines
* Last to confirm: is 'kconfig-language.html' reference for the
Kconfiglangauge as implemented in kernel OR it is the general language reference that applies to allKconfigfiles across all projects? Because non-kernel projects also seem to useKconfigfiles.
I hoped this file explained Kconfig language as a standalone project.
Apparently, it contains a kernel-specific description. (e.g. "Compile-testing")
Quoted 5 lines
Thank you.
---
- Prasad
Signature · 2 lines
Best Regards Masahiro Yamada
Hi,
Quoted 2 lines · Masahiro Yamada
Quoted 1 line
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.
Quoted 2 lines
Kconfigdoes 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
Quoted 22 lines · Prasad Pandit
Hi,
Quoted 2 lines · Masahiro Yamada
Quoted 1 line
Because even config entries ending with an 'EOF' are not flagged as an error.
Why should it be flagged as an error?
*
Kconfigfile 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>
Quoted 1 line
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.
Quoted 7 lines
Quoted 2 lines
Kconfigdoes 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.
Quoted 7 lines
$ 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.
Quoted 5 lines
Thank you.
---
-Prasad
Signature · 2 lines
Best Regards Masahiro Yamada
Hi,
Quoted 1 line · Masahiro Yamada
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.
Quoted 3 lines
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.
Quoted 1 line
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.
Quoted 4 lines
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
Quoted 13 lines · Prasad Pandit
Hi,
Quoted 1 line · Masahiro Yamada
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>
Quoted 8 lines
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.
Quoted 7 lines
---
$ cat t.py #!/usr/bin/pythonif (x == 10)$
$
Quoted 8 lines
$ 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.
Quoted 6 lines
Quoted 5 lines
Could you give me an example programming language that errors out when \n is missing at the end of the source file?
Quoted 6 lines
* It is not about '\n' at the end of file, but '\n' at the end of the
Kconfigstatement/record. BecauseKconfiglanguage uses EOL as a separator.Quoted 1 line
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.
Quoted 7 lines
Quoted 5 lines
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 thattest2.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.
Quoted 7 lines
* In their case colon(':') or brace ('}') are the required terminators, whereas in Kconfig's case EOL ('\n') is the required terminator.
* Because
Kconfiglanguage 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.
Signature · 2 lines
Best Regards Masahiro Yamada
#!/usr/bin/pythonprint("A")print("B")
#!/usr/bin/pythonprint("A")print("B")
Hi,
Quoted 3 lines · Masahiro Yamada
Do you see any grammar that treats
T_EOFinscripts/kconfig/parser.y? It only handlesT_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