user remarks for config symbols
cover user remarks for config symbols
- RFC -
--- Comments, Reviews, Test reports, Notes, everything welcome ---
Hi,
I recently had the need to create a documentation for a kernel config, and decided to extend the kernel config tool(s) to allow me to do that with minium effort.
Specifically, I extended make xconfig (and now also others) for editing a remark per config symbol and I created a config2html frontend to the kconfig lib which outputs the config options with their comments to a HTML table.
Besides that, it was sometimes been interesting to be able to add a note for some config choices in order to see that note again when revisiting that config choice again later.
So I hope that the patches which I created could be useable by the greater Linux community, and hereby, I submit them for discussion and if liked, for inclusion.
Thanks,
Bernhard Kaindl
Bernhard Kaindl (4):
Support loading and saving custom remarks for config symbols
menuconfig: allow editing of remarks for config symbols
xconfig: allow editing of remarks for config symbols
make config / oldconfig: allow editing of remarks for config symbols
scripts/kconfig/conf.c | 19 +++++++++++++ scripts/kconfig/confdata.c | 45 ++++++++++++++++++++++++++++-- scripts/kconfig/expr.h | 1 + scripts/kconfig/lxdialog/menubox.c | 3 ++ scripts/kconfig/mconf.c | 51 ++++++++++++++++++++++++++++++++++ scripts/kconfig/qconf.cc | 53 ++++++++++++++++++++++++++++++++++++ scripts/kconfig/qconf.h | 19 +++++++++++++ 7 files changed, 188 insertions(+), 3 deletions(-)
PS: Here is also an update to my CREDITS entry:
CREDITS +3 -3
@@ -1714,11 +1714,11 @@ S: Tata S: Hungary N: Bernhard Kaindl -E: [email protected] -E: [email protected] +E: [email protected] D: Author of a menu based configuration tool, kmenu, which D: is the predecessor of 'make menuconfig' and 'make xconfig'. -D: digiboard driver update(modularisation work and 2.1.x upd) +D: Various fixes for the kernel configuration tools +D: Digiboard driver update (modularisation work and 2.1.x update) S: Tallak 95 S: 8103 Rein S: Austria
PATCH 1/4 Support loading and saving custom remarks for config symbols
Add the infrastructure to load and save remarks for config symbols to the kconfig library functions conf_read() and conf_write()
This
- adds sym->remark
- extends conf_read() to call conf_read_remarks()
- adds conf_read_remarks() which:
-> reads remarks from a file and
-> stores them in sym->remark
- extends conf_write() to save each sym->remark so that conf_read_remarks() will be able to reread them
To not keep any additional file when no remarks exist, and to stay completely out of the way when this feature is not used, conf_write() does not keep empty remarks files, so anyone not using this code will see no changes.
The filename of the remarks file is derived from the used config file name and path by appending "-remarks" to the config file name. So the default remarks file would be ".config-remarks".
This code supports one-line remarks without newlines. The changes to the tools (menuconfig, xconfig, config) also only support one-line remarks as they use the existing UI functions for editing strings.
--- scripts/kconfig/confdata.c | 45 +++++++++++++++++++++++++++++++++++++++++-- scripts/kconfig/expr.h | 1 + 2 files changed, 43 insertions(+), 3 deletions(-)
scripts/kconfig/confdata.c +42 -3
@@ -152,6 +152,30 @@ static int conf_set_sym_val(struct symbol *sym, int def, int def_flags, char *p)return 0 ; } +/** +* Read remarks from -remarks file: +*/ +void conf_read_remarks (const char *remfile) +{ +FILE *in; +char line[1024 ], *p, *p2; +struct symbol *sym; + +sprintf (line,"%s-remarks" , remfile ? remfile :conf_get_configname ()); +if (!(in =zconf_fopen (line))) +return ; +while (fgets (line,sizeof (line), in)) { +if (!(p =strchr (line,' ' )))/* ' ' is our delimiter */ +continue ;/* skip lines without one */ + *p++ ='\0' ;/* put a \0 there, advance */ +if ((p2 =strchr (p,'\n' )))/* look for \n after remark */ + *p2 ='\0' ;/* remove it, no \n in remarks */ +if ((sym =sym_find (line)))/* find the matching sym */ + sym->remark =strdup (p);/* and register the remark */ + } +fclose (in); +} +int conf_read_simple (const char *name,int def) {FILE *in =NULL ;
@@ -393,16 +417,18 @@ int conf_read(const char *name)sym_add_change_count (conf_warnings || conf_unsaved); +conf_read_remarks (name);return 0 ; }int conf_write (const char *name) { -FILE *out; +FILE *out, *rem; +struct stat sb;struct symbol *sym;struct menu *menu;const char *basename; -char dirname[128 ], tmpname[128 ], newname[128 ]; +char dirname[128 ], tmpname[128 ], newname[128 ], tmprem[128 ], newrem[128 ];int type, l;const char *str;time_t now;
@@ -432,15 +458,19 @@ int conf_write(const char *name) basename =conf_get_configname ();sprintf (newname,"%s%s" , dirname, basename); +sprintf (newrem,"%s%s-remarks" , dirname, basename); env =getenv ("KCONFIG_OVERWRITECONFIG" );if (!env || !*env) {sprintf (tmpname,"%s.tmpconfig.%d" , dirname, (int )getpid ()); out =fopen (tmpname,"w" ); +sprintf (tmprem,"%s.tmpconfig-remarks.%d" , dirname, (int )getpid ()); + rem =fopen (tmprem,"w" ); }else { *tmpname =0 ; out =fopen (newname,"w" ); + rem =fopen (newrem,"w" ); } -if (!out) +if (!out || !rem)return 1 ; sym =sym_lookup ("KERNELVERSION" ,0 );
@@ -528,6 +558,8 @@ int conf_write(const char *name) } next: +if (sym && sym->remark) +fprintf (rem,"%s %s\n" , sym->name, sym->remark);if (menu->list) { menu = menu->list;continue ;
@@ -542,6 +574,7 @@ int conf_write(const char *name) } }fclose (out); +fclose (rem);if (*tmpname) {strcat (dirname, basename);
@@ -549,7 +582,13 @@ int conf_write(const char *name)rename (newname, dirname);if (rename (tmpname, newname))return 1 ; +sprintf (dirname,"%s.old" , newrem); +rename (newrem, dirname); +if (rename (tmprem, newrem)) +conf_warning ("moving %s to %s failed!" , tmprem, newrem); } +if (!stat (newrem, &sb) && !sb.st_size) +unlink (newrem); printf(_("#\n" "# configuration written to %s\n"
scripts/kconfig/expr.h +1 -0
@@ -77,6 +77,7 @@ enum {struct symbol {struct symbol *next;char *name; +char *remark;enum symbol_type type;struct symbol_value curr;struct symbol_value def[S_DEF_COUNT ];
Signature · 1 line
1.6.0.4
PATCH 2/4 menuconfig: allow editing of remarks for config symbols
Extend menuconfig to allow editing of remarks for config symbols:
Add a new key to lxdialog (currently '<') which, when pressed, is forwarded to menuconfig, which handles it similar to the search key ('/') which can be used at any time, but passes the currently selected menu entry to conf_remark()
conf_remark() is based on conf_string(), which allows to edit a string, but before, it checks if the passed menu entry is a config symbol, and if not it displays a short notice saying that it currently does not support editing comments for a pure menu entries without attached config symbol.
It then allows to edit a string, which is initialized from the sym->remark entry and if the user changed the string, it updates sym->remark and sets things up so that menuconfig asks to save the config before exiting, so the changed remark is saved in that go.
--- scripts/kconfig/lxdialog/menubox.c | 3 ++ scripts/kconfig/mconf.c | 51 ++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+), 0 deletions(-)
scripts/kconfig/lxdialog/menubox.c +3 -0
@@ -383,6 +383,7 @@ do_resize:case 'n' :case 'm' :case '/' : +case '<' :/* save scroll info */ *s_scroll = scroll;delwin (menu);
@@ -402,6 +403,8 @@ do_resize:return 6 ;case '/' :return 7 ; +case '<' : +return 8 ; }return 0 ;case 'h' :
scripts/kconfig/mconf.c +51 -0
69 lines not on this page · raw message
Signature · 1 line
1.6.0.4
PATCH 3/4 xconfig: allow editing of remarks for config symbols
Extend xconfig to allow editing of remarks for config symbols:
Add a new key to xconfig (currently '<') which, when pressed while a menu entry with a config symbol is selected, shows a QLineEdit (identical to the one used for string symbol editing) which is filled with sym->remark.
After the current config item looses focus or the user presses Escape/Return/Enter to close the QLineEdit, the QLineEdit saves the edited string to sym->remark and hides.
The new descendent of QLineEdit is called ConfigRemarkEdit and is mostly a copy of its silbling ConfigLineEdit, which is used for changing the values of int, hex and string values.
--- scripts/kconfig/qconf.cc | 53 ++++++++++++++++++++++++++++++++++++++++++++++ scripts/kconfig/qconf.h | 19 ++++++++++++++++ 2 files changed, 72 insertions(+), 0 deletions(-)
scripts/kconfig/qconf.cc +53 -0
@@ -278,6 +278,54 @@ ConfigItem::~ConfigItem(void) } } +ConfigRemarkEdit::ConfigRemarkEdit(ConfigView* parent) : Parent(parent) +{ + connect(this, SIGNAL(lostFocus()), SLOT(hide())); + Parent::hide(); +} + +void ConfigRemarkEdit::show(ConfigItem* i) +{ + item = i; + if (item->menu->sym->remark) + setText(QString::fromLocal8Bit(item->menu->sym->remark)); + else + setText(QString::null); + Parent::show(); + setFocus(); +} + +void ConfigRemarkEdit::saveremark() +{ + if (item && item->menu && item->menu->sym) { + if (item->menu->sym->remark) + free(item->menu->sym->remark); + item->menu->sym->remark = strdup(text().latin1()); + sym_set_changed(item->menu->sym); + sym_add_change_count(1); + sym_clear_all_valid(); + } +} + +void ConfigRemarkEdit::hide() { + saveremark(); + Parent::hide(); +} + +void ConfigRemarkEdit::keyPressEvent(QKeyEvent* e) +{ + switch (e->key()) { + case Qt::Key_Escape: + case Qt::Key_Return: + case Qt::Key_Enter: + e->accept(); + parent()->list->setFocus(); + hide(); + return; + } + Parent::keyPressEvent(e); +} + ConfigLineEdit::ConfigLineEdit(ConfigView* parent) : Parent(parent) {
@@ -668,6 +716,10 @@ void ConfigList::keyPressEvent(QKeyEvent* ev) emit menuSelected(menu); break; } + case Qt::Key_Less: + if (item && item->menu && item->menu->sym && !sym_is_choice(item->menu->sym)) + parent()->remarkEdit->show(item); + break; case Qt::Key_Space: changeValue(item); break;
@@ -843,6 +895,7 @@ ConfigView::ConfigView(QWidget* parent, const char *name) list = new ConfigList(this, name); lineEdit = new ConfigLineEdit(this); lineEdit->hide(); + remarkEdit = new ConfigRemarkEdit(this); this->nextView = viewList; viewList = this;
scripts/kconfig/qconf.h +19 -0
@@ -29,6 +29,7 @@ class ConfigView;class ConfigList;class ConfigItem;class ConfigLineEdit; +class ConfigRemarkEdit;class ConfigMainWindow;
@@ -197,6 +198,23 @@ public:bool goParent; }; +class ConfigRemarkEdit : public QLineEdit { +Q_OBJECT + typedef class QLineEdit Parent; +public: +ConfigRemarkEdit (ConfigView* parent); +ConfigView *parent (void ) const + { + return (ConfigView*)Parent::parent(); + } +void keyPressEvent (QKeyEvent *e); +void show (ConfigItem *i); +void hide (); +private: +ConfigItem *item; +void saveremark (); +}; + class ConfigLineEdit : public QLineEdit {Q_OBJECT typedef class QLineEdit Parent;
@@ -239,6 +257,7 @@ signals: public:ConfigList * list;ConfigLineEdit * lineEdit; +ConfigRemarkEdit * remarkEdit;static ConfigView * viewList;ConfigView * nextView;
Signature · 1 line
1.6.0.4
PATCH 4/4 make config / oldconfig: allow editing of remarks for config symbols
In conf_sym(), which is used for ask for all bool/tristate symbols, print sym->remark (if one exists) befor prompting for the option and analogous to help (triggered by an input beginning with '?'), when the user enters a line starting with '<', allow the user to enter a remark or update it.
This extension does not cover the configuration of string, integer or choice values. I leave this open for follow-up submission in case there is interest in the config symbol remarks in general and in really supporting these also fully in make config, oldconfig and (possibly) silbings.
PS:
make gconfig could also be considered for extension, but it does apparently does not have a great deal of string editing UI yet, so adding remarks to it would require finding a way to edit string symbols in it first.
--- scripts/kconfig/conf.c | 19 +++++++++++++++++++ 1 files changed, 19 insertions(+), 0 deletions(-)
scripts/kconfig/conf.c +19 -0
@@ -158,8 +158,11 @@ static int conf_sym(struct menu *menu)struct symbol *sym = menu->sym;int type;tristate oldval, newval; +char *p;while (1 ) { +if (sym->remark) +printf ("Remark: %s\n" , sym->remark);printf ("%*s%s " , indent -1 ,"" ,_ (menu->prompt->text));if (sym->name)printf ("(%s) " , sym->name);
@@ -214,6 +217,8 @@ static int conf_sym(struct menu *menu)break ;case '?' : goto help; +case '<' : + goto remark;default :continue ; }
@@ -221,6 +226,20 @@ static int conf_sym(struct menu *menu)return 0 ; help:print_help (menu); +continue ; +remark: +if (sym->remark) +printf ("Current Remark: %s\n" , sym->remark); +printf (" New remark: " ); +fgets (line,sizeof (line), stdin); + +if ((p =strchr (line,'\n' ))) + *p ='\0' ;/* no \n in remark */ +if (line[0 ]) { +if (sym->remark) +free (sym->remark); + sym->remark =strdup (line); + } } }
Signature · 1 line
1.6.0.4
Re: [PATCH 1/4] Support loading and saving custom remarks for config symbols
In reply to Bernhard KaindlHi!
Quoted 9 lines
This code supports one-line remarks without newlines. The changes to the tools (menuconfig, xconfig, config) also only support one-line remarks as they use the existing UI functions for editing strings.
scripts/kconfig/confdata.c +0
-0
scripts/kconfig/confdata.c static int conf_set_sym_val(struct symbol *sym, int def, int def_flags, char *p) · line 157
Quoted 6 lines
scripts/kconfig/confdata.c +3
-0@@ -152,6 +152,30 @@ static int conf_set_sym_val(struct symbol *sym, int def, int def_flags, char *p)return 0 ; } +/** +* Read remarks from -remarks file: +*/
/** means kerneldoc but this is not valid kerneldoc.
Pavel
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
Re: [PATCH 1/4] Support loading and saving custom remarks for config symbols
In reply to Bernhard Kaindl[Added Roman Zippel (maintainer of kconfig) to CC, the whole thread is at http://thread.gmane.org/gmane.linux.kbuild.devel/4039)
Quoted 2 lines · Bernhard Kaindl
Add the infrastructure to load and save remarks for config symbols to the kconfig library functions
conf_read()andconf_write()
First of all, I think this is a great idea, a mechanism to attach user comments to config options in .config would be really helpful, esp. for people maintaining distribution configs.
Quoted 9 lines
This
- addssym->remark
- extendsconf_read()to callconf_read_remarks()
- addsconf_read_remarks()which:
-> reads remarks from a file and
-> stores them insym->remark
- extendsconf_write()to save eachsym->remarkso thatconf_read_remarks()will be able to reread them
Quoted 7 lines
To not keep any additional file when no remarks exist, and to stay completely out of the way when this feature is not used,
conf_write()does not keep empty remarks files, so anyone not using this code will see no changes.The filename of the remarks file is derived from the used config file name and path by appending "-remarks" to the config file name. So the default remarks file would be ".config-remarks".
This is not really obvious if you are viewing the .config directly, though. What about storing the remarks in the .config itself? E.g. if a symbol is directly preceded by a line that starts with '#', contains some non-whitespace characters (to skip comments comming from Kconfig files) and does not look like "# CONFIG_FOO=[ym]" or " CONFIG_FOO is not set", interpret that line as remark for the next symbol:
#
# File systems
#
# CONFIG_EXT2_FS is not set
# this line is a remark, the lines above are not CONFIG_EXT3_FS=y
The write operation would just print the remark before each symbol. Sure there would be false matches sometimes, but I think people would appreciate that their inline comments survive make oldconfig.
What do you think? I'll try creating a patch tomorrow.
Michal
Quoted 130 lines
This code supports one-line remarks without newlines. The changes to the tools (menuconfig, xconfig, config) also only support one-line remarks as they use the existing UI functions for editing strings.
Signed-off-by Bernhard Kaindl <[email protected]>--- scripts/kconfig/confdata.c | 45 +++++++++++++++++++++++++++++++++++++++++-- scripts/kconfig/expr.h | 1 + 2 files changed, 43 insertions(+), 3 deletions(-)scripts/kconfig/confdata.c +42
-3@@ -152,6 +152,30 @@ static int conf_set_sym_val(struct symbol *sym, int def, int def_flags, char *p)return 0 ; } +/** +* Read remarks from -remarks file: +*/ +void conf_read_remarks (const char *remfile) +{ +FILE *in; +char line[1024 ], *p, *p2; +struct symbol *sym; + +sprintf (line,"%s-remarks" , remfile ? remfile :conf_get_configname ()); +if (!(in =zconf_fopen (line))) +return ; +while (fgets (line,sizeof (line), in)) { +if (!(p =strchr (line,' ' )))/* ' ' is our delimiter */ +continue ;/* skip lines without one */ + *p++ ='\0' ;/* put a \0 there, advance */ +if ((p2 =strchr (p,'\n' )))/* look for \n after remark */ + *p2 ='\0' ;/* remove it, no \n in remarks */ +if ((sym =sym_find (line)))/* find the matching sym */ + sym->remark =strdup (p);/* and register the remark */ + } +fclose (in); +} +int conf_read_simple (const char *name,int def) {FILE *in =NULL ;@@ -393,16 +417,18 @@ int conf_read(const char *name)sym_add_change_count (conf_warnings || conf_unsaved); +conf_read_remarks (name);return 0 ; }int conf_write (const char *name) { -FILE *out; +FILE *out, *rem; +struct stat sb;struct symbol *sym;struct menu *menu;const char *basename; -char dirname[128 ], tmpname[128 ], newname[128 ]; +char dirname[128 ], tmpname[128 ], newname[128 ], tmprem[128 ], newrem[128 ];int type, l;const char *str;time_t now;@@ -432,15 +458,19 @@ int conf_write(const char *name) basename =conf_get_configname ();sprintf (newname,"%s%s" , dirname, basename); +sprintf (newrem,"%s%s-remarks" , dirname, basename); env =getenv ("KCONFIG_OVERWRITECONFIG" );if (!env || !*env) {sprintf (tmpname,"%s.tmpconfig.%d" , dirname, (int )getpid ()); out =fopen (tmpname,"w" ); +sprintf (tmprem,"%s.tmpconfig-remarks.%d" , dirname, (int )getpid ()); + rem =fopen (tmprem,"w" ); }else { *tmpname =0 ; out =fopen (newname,"w" ); + rem =fopen (newrem,"w" ); } -if (!out) +if (!out || !rem)return 1 ; sym =sym_lookup ("KERNELVERSION" ,0 );@@ -528,6 +558,8 @@ int conf_write(const char *name) } next: +if (sym && sym->remark) +fprintf (rem,"%s %s\n" , sym->name, sym->remark);if (menu->list) { menu = menu->list;continue ;@@ -542,6 +574,7 @@ int conf_write(const char *name) } }fclose (out); +fclose (rem);if (*tmpname) {strcat (dirname, basename);@@ -549,7 +582,13 @@ int conf_write(const char *name)rename (newname, dirname);if (rename (tmpname, newname))return 1 ; +sprintf (dirname,"%s.old" , newrem); +rename (newrem, dirname); +if (rename (tmprem, newrem)) +conf_warning ("moving %s to %s failed!" , tmprem, newrem); } +if (!stat (newrem, &sb) && !sb.st_size) +unlink (newrem); printf(_("#\n" "# configuration written to %s\n"scripts/kconfig/expr.h +1
-0@@ -77,6 +77,7 @@ enum {struct symbol {struct symbol *next;char *name; +char *remark;enum symbol_type type;struct symbol_value curr;struct symbol_value def[S_DEF_COUNT ];
PATCH 1/1 Support loading and saving custom remarks in .config
To make it easier for users to maintain their .config over time, add support for one-line comments (remarks) attached to config option assignments. The format is
# some remark CONFIG_FOO=y # another remark # CONFIG_BAR is not set
If a config option is removed, the respective remark is removed as well. This patch is based on a previous patch by Bernhard Kaindl.
--- scripts/kconfig/confdata.c | 52 +++++++++++++++++++++++++++++++++++++++++++- scripts/kconfig/expr.h | 1 + 2 files changed, 52 insertions(+), 1 deletions(-)
scripts/kconfig/confdata.c +51 -1
@@ -152,13 +152,46 @@ static int conf_set_sym_val(struct symbol *sym, int def, int def_flags, char *p)return 0 ; } +static char *extract_remark (const char *line) +{ +const char *p; +char *res, *p2; +static const char *alnum = +"ABCDEFGHIJKLMNOPQRSTUVWXYZ" +"abcdefghijklmnopqrstuvwxyz" +"0123456789_" ; + + +if (!line || *line !='#' ) +return NULL ; + line++; + line +=strspn (line," \t" ); +if (!*line || *line =='\n' ) +return NULL ; +if (strncmp (line,"CONFIG_" ,sizeof ("CONFIG_" ) -1 ) !=0 ) + goto found; + p = line +strspn (line, alnum); +if (strcmp (p," is not set\n" ) ==0 ) +return NULL ; +/* skip commented out assignments */ +if (p[1 ] =='=' && !strchr (p,' ' ) && !strchr (p,'\t' )) +return NULL ; +found: + res =strdup (line); + p2 =strchr (res,'\n' ); +if (p2) + *p2 ='\0' ; +return res; +} +int conf_read_simple (const char *name,int def) {FILE *in =NULL ;char line[1024 ];char *p, *p2;struct symbol *sym; -int i, def_flags; +char *last_remark; +int i, def_flags, last_remark_lineno;if (name) { in =zconf_fopen (name);
@@ -195,6 +228,8 @@ load: conf_lineno =0 ; conf_warnings =0 ; conf_unsaved =0 ; + last_remark =NULL ; + last_remark_lineno =0 ; def_flags =SYMBOL_DEF << def; for_all_symbols(i, sym) {
@@ -215,8 +250,15 @@ load: }while (fgets (line,sizeof (line), in)) { +char *remark; conf_lineno++; sym =NULL ; + remark =extract_remark (line); +if (remark) { +free (last_remark); + last_remark = remark; + last_remark_lineno = conf_lineno; + }switch (line[0 ]) {case '#' :if (memcmp (line +2 ,"CONFIG_" ,7 ))
@@ -309,6 +351,12 @@ load: } cs->def[def].tri =EXPR_OR (cs->def[def].tri, sym->def[def].tri); } +if (sym && last_remark && + last_remark_lineno == conf_lineno -1 ) { + sym->remark = last_remark; +/* don't free() the string in the next iteration */ + last_remark =NULL ; + } }fclose (in);
@@ -484,6 +532,8 @@ int conf_write(const char *name)if (modules_sym->curr.tri == no) type =S_BOOLEAN ; } +if (sym->remark) +fprintf (out,"# %s\n" , sym->remark);switch (type) {case S_BOOLEAN :case S_TRISTATE :
scripts/kconfig/expr.h +1 -0
@@ -77,6 +77,7 @@ enum {struct symbol {struct symbol *next;char *name; +char *remark;enum symbol_type type;struct symbol_value curr;struct symbol_value def[S_DEF_COUNT ];
Signature · 1 line
1.6.4.2