kbuild: make *config usage docs

Create a kconfig user assistance guide, with a few tips and hints about using menuconfig, xconfig, and gconfig. Mostly contains user interface, environment variables, and search topics, along with mini.config/custom.config usage. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>

kbuild: make *config usage docs
Create a kconfig user assistance guide, with a few tips and hints about using menuconfig, xconfig, and gconfig. Mostly contains user interface, environment variables, and search topics, along with mini.config/custom.config usage. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Randy Dunlap · Sam Ravnborg
1 parent 80a7d1d991
Showing 3 changed files with 210 additions and 12 deletions Side-by-side Diff
Documentation/kbuild/00-INDEX
Documentation/kbuild/kconfig.txt
README
@@ -4,6 +4,8 @@
 	- specification of Config Language, the language in Kconfig files
 makefiles.txt
 	- developer information for linux kernel makefiles
+kconfig.txt
+	- usage help for make *config
 modules.txt
 	- how to build modules and to install them
+This file contains some assistance for using "make *config".
+
+Use "make help" to list all of the possible configuration targets.
+
+The xconfig ('qconf') and menuconfig ('mconf') programs also
+have embedded help text.  Be sure to check it for navigation,
+search, and other general help text.
+
+======================================================================
+General
+--------------------------------------------------
+
+New kernel releases often introduce new config symbols.  Often more
+important, new kernel releases may rename config symbols.  When
+this happens, using a previously working .config file and running
+"make oldconfig" won't necessarily produce a working new kernel
+for you, so you may find that you need to see what NEW kernel
+symbols have been introduced.
+
+To see a list of new config symbols when using "make oldconfig", use
+
+	cp user/some/old.config .config
+	yes "" | make oldconfig >conf.new
+
+and the config program will list as (NEW) any new symbols that have
+unknown values.  Of course, the .config file is also updated with
+new (default) values, so you can use:
+
+	grep "(NEW)" conf.new
+
+to see the new config symbols or you can 'diff' the previous and
+new .config files to see the differences:
+
+	diff .config.old .config | less
+
+(Yes, we need something better here.)
+
+
+======================================================================
+menuconfig
+--------------------------------------------------
+
+SEARCHING for CONFIG symbols
+
+Searching in menuconfig:
+
+	The Search function searches for kernel configuration symbol
+	names, so you have to know something close to what you are
+	looking for.
+
+	Example:
+		/hotplug
+		This lists all config symbols that contain "hotplug",
+		e.g., HOTPLUG, HOTPLUG_CPU, MEMORY_HOTPLUG.
+
+	For search help, enter / followed TAB-TAB-TAB (to highlight
+	<Help>) and Enter.  This will tell you that you can also use
+	regular expressions (regexes) in the search string, so if you
+	are not interested in MEMORY_HOTPLUG, you could try
+
+		/^hotplug
+
+
+______________________________________________________________________
+Color Themes for 'menuconfig'
+
+It is possible to select different color themes using the variable
+MENUCONFIG_COLOR.  To select a theme use:
+
+	make MENUCONFIG_COLOR=<theme> menuconfig
+
+Available themes are:
+  mono       => selects colors suitable for monochrome displays
+  blackbg    => selects a color scheme with black background
+  classic    => theme with blue background. The classic look
+  bluetitle  => a LCD friendly version of classic. (default)
+
+______________________________________________________________________
+Environment variables in 'menuconfig'
+
+KCONFIG_ALLCONFIG
+--------------------------------------------------
+(partially based on lkml email from/by Rob Landley, re: miniconfig)
+--------------------------------------------------
+The allyesconfig/allmodconfig/allnoconfig/randconfig variants can
+also use the environment variable KCONFIG_ALLCONFIG as a flag or a
+filename that contains config symbols that the user requires to be
+set to a specific value.  If KCONFIG_ALLCONFIG is used without a
+filename, "make *config" checks for a file named
+"all{yes/mod/no/random}.config" (corresponding to the *config command
+that was used) for symbol values that are to be forced.  If this file
+is not found, it checks for a file named "all.config" to contain forced
+values.
+
+This enables you to create "miniature" config (miniconfig) or custom
+config files containing just the config symbols that you are interested
+in.  Then the kernel config system generates the full .config file,
+including dependencies of your miniconfig file, based on the miniconfig
+file.
+
+This 'KCONFIG_ALLCONFIG' file is a config file which contains
+(usually a subset of all) preset config symbols.  These variable
+settings are still subject to normal dependency checks.
+
+Examples:
+	KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig
+or
+	KCONFIG_ALLCONFIG=mini.config make allnoconfig
+or
+	make KCONFIG_ALLCONFIG=mini.config allnoconfig
+
+These examples will disable most options (allnoconfig) but enable or
+disable the options that are explicitly listed in the specified
+mini-config files.
+
+KCONFIG_NOSILENTUPDATE
+--------------------------------------------------
+If this variable has a non-blank value, it prevents silent kernel
+config udpates (requires explicit updates).
+
+KCONFIG_CONFIG
+--------------------------------------------------
+This environment variable can be used to specify a default kernel config
+file name to override the default name of ".config".
+
+KCONFIG_OVERWRITECONFIG
+--------------------------------------------------
+If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not
+break symlinks when .config is a symlink to somewhere else.
+
+KCONFIG_NOTIMESTAMP
+--------------------------------------------------
+If this environment variable exists and is non-null, the timestamp line
+in generated .config files is omitted.
+
+KCONFIG_AUTOCONFIG
+--------------------------------------------------
+This environment variable can be set to specify the path & name of the
+"auto.conf" file.  Its default value is "include/config/auto.conf".
+
+KCONFIG_AUTOHEADER
+--------------------------------------------------
+This environment variable can be set to specify the path & name of the
+"autoconf.h" (header) file.  Its default value is "include/linux/autoconf.h".
+
+______________________________________________________________________
+menuconfig User Interface Options
+----------------------------------------------------------------------
+MENUCONFIG_MODE
+--------------------------------------------------
+This mode shows all sub-menus in one large tree.
+
+Example:
+	MENUCONFIG_MODE=single_menu make menuconfig
+
+======================================================================
+xconfig
+--------------------------------------------------
+
+Searching in xconfig:
+
+	The Search function searches for kernel configuration symbol
+	names, so you have to know something close to what you are
+	looking for.
+
+	Example:
+		Ctrl-F hotplug
+	or
+		Menu: File, Search, hotplug
+
+	lists all config symbol entries that contain "hotplug" in
+	the symbol name.  In this Search dialog, you may change the
+	config setting for any of the entries that are not grayed out.
+	You can also enter a different search string without having
+	to return to the main menu.
+
+
+======================================================================
+gconfig
+--------------------------------------------------
+
+Searching in gconfig:
+
+	None (gconfig isn't maintained as well as xconfig or menuconfig);
+	however, gconfig does have a few more viewing choices than
+	xconfig does.
+
+###
@@ -52,11 +52,11 @@
  
  - The Documentation/DocBook/ subdirectory contains several guides for
    kernel developers and users.  These guides can be rendered in a
-   number of formats:  PostScript (.ps), PDF, and HTML, among others.
-   After installation, "make psdocs", "make pdfdocs", or "make htmldocs"
-   will render the documentation in the requested format.
+   number of formats:  PostScript (.ps), PDF, HTML, & man-pages, among others.
+   After installation, "make psdocs", "make pdfdocs", "make htmldocs",
+   or "make mandocs" will render the documentation in the requested format.
  
-INSTALLING the kernel:
+INSTALLING the kernel source:
  
  - If you install the full sources, put the kernel tarball in a
    directory where you have permissions (eg. your home directory) and
@@ -187,14 +187,9 @@
 	"make randconfig"  Create a ./.config file by setting symbol
 			   values to random values.
  
-   The allyesconfig/allmodconfig/allnoconfig/randconfig variants can
-   also use the environment variable KCONFIG_ALLCONFIG to specify a
-   filename that contains config options that the user requires to be
-   set to a specific value.  If KCONFIG_ALLCONFIG=filename is not used,
-   "make *config" checks for a file named "all{yes/mod/no/random}.config"
-   for symbol values that are to be forced.  If this file is not found,
-   it checks for a file named "all.config" to contain forced values.
-   
+   You can find more information on using the Linux kernel config tools
+   in Documentation/kbuild/make-configs.txt.
+
 	NOTES on "make config":
 	- having unnecessary drivers will make the kernel bigger, and can
 	  under some circumstances lead to problems: probing for a
@@ -230,6 +225,19 @@
  
  - If you configured any of the parts of the kernel as `modules', you
    will also have to do "make modules_install".
+
+ - Verbose kernel compile/build output:
+
+   Normally the kernel build system runs in a fairly quiet mode (but not
+   totally silent).  However, sometimes you or other kernel developers need
+   to see compile, link, or other commands exactly as they are executed.
+   For this, use "verbose" build mode.  This is done by inserting
+   "V=1" in the "make" command.  E.g.:
+
+	make V=1 all
+
+   To have the build system also tell the reason for the rebuild of each
+   target, use "V=2".  The default is "V=0".
  
  - Keep a backup kernel handy in case something goes wrong.  This is 
    especially true for the development releases, since each new release
...	...	@@ -4,6 +4,8 @@
4	4	- specification of Config Language, the language in Kconfig files
5	5	makefiles.txt
6	6	- developer information for linux kernel makefiles
	7	+kconfig.txt
	8	+ - usage help for make *config
7	9	modules.txt
8	10	- how to build modules and to install them
	1	+This file contains some assistance for using "make *config".
	2	+
	3	+Use "make help" to list all of the possible configuration targets.
	4	+
	5	+The xconfig ('qconf') and menuconfig ('mconf') programs also
	6	+have embedded help text. Be sure to check it for navigation,
	7	+search, and other general help text.
	8	+
	9	+======================================================================
	10	+General
	11	+--------------------------------------------------
	12	+
	13	+New kernel releases often introduce new config symbols. Often more
	14	+important, new kernel releases may rename config symbols. When
	15	+this happens, using a previously working .config file and running
	16	+"make oldconfig" won't necessarily produce a working new kernel
	17	+for you, so you may find that you need to see what NEW kernel
	18	+symbols have been introduced.
	19	+
	20	+To see a list of new config symbols when using "make oldconfig", use
	21	+
	22	+ cp user/some/old.config .config
	23	+ yes "" \| make oldconfig >conf.new
	24	+
	25	+and the config program will list as (NEW) any new symbols that have
	26	+unknown values. Of course, the .config file is also updated with
	27	+new (default) values, so you can use:
	28	+
	29	+ grep "(NEW)" conf.new
	30	+
	31	+to see the new config symbols or you can 'diff' the previous and
	32	+new .config files to see the differences:
	33	+
	34	+ diff .config.old .config \| less
	35	+
	36	+(Yes, we need something better here.)
	37	+
	38	+
	39	+======================================================================
	40	+menuconfig
	41	+--------------------------------------------------
	42	+
	43	+SEARCHING for CONFIG symbols
	44	+
	45	+Searching in menuconfig:
	46	+
	47	+ The Search function searches for kernel configuration symbol
	48	+ names, so you have to know something close to what you are
	49	+ looking for.
	50	+
	51	+ Example:
	52	+ /hotplug
	53	+ This lists all config symbols that contain "hotplug",
	54	+ e.g., HOTPLUG, HOTPLUG_CPU, MEMORY_HOTPLUG.
	55	+
	56	+ For search help, enter / followed TAB-TAB-TAB (to highlight
	57	+ <Help>) and Enter. This will tell you that you can also use
	58	+ regular expressions (regexes) in the search string, so if you
	59	+ are not interested in MEMORY_HOTPLUG, you could try
	60	+
	61	+ /^hotplug
	62	+
	63	+
	64	+______________________________________________________________________
	65	+Color Themes for 'menuconfig'
	66	+
	67	+It is possible to select different color themes using the variable
	68	+MENUCONFIG_COLOR. To select a theme use:
	69	+
	70	+ make MENUCONFIG_COLOR=<theme> menuconfig
	71	+
	72	+Available themes are:
	73	+ mono => selects colors suitable for monochrome displays
	74	+ blackbg => selects a color scheme with black background
	75	+ classic => theme with blue background. The classic look
	76	+ bluetitle => a LCD friendly version of classic. (default)
	77	+
	78	+______________________________________________________________________
	79	+Environment variables in 'menuconfig'
	80	+
	81	+KCONFIG_ALLCONFIG
	82	+--------------------------------------------------
	83	+(partially based on lkml email from/by Rob Landley, re: miniconfig)
	84	+--------------------------------------------------
	85	+The allyesconfig/allmodconfig/allnoconfig/randconfig variants can
	86	+also use the environment variable KCONFIG_ALLCONFIG as a flag or a
	87	+filename that contains config symbols that the user requires to be
	88	+set to a specific value. If KCONFIG_ALLCONFIG is used without a
	89	+filename, "make *config" checks for a file named
	90	+"all{yes/mod/no/random}.config" (corresponding to the *config command
	91	+that was used) for symbol values that are to be forced. If this file
	92	+is not found, it checks for a file named "all.config" to contain forced
	93	+values.
	94	+
	95	+This enables you to create "miniature" config (miniconfig) or custom
	96	+config files containing just the config symbols that you are interested
	97	+in. Then the kernel config system generates the full .config file,
	98	+including dependencies of your miniconfig file, based on the miniconfig
	99	+file.
	100	+
	101	+This 'KCONFIG_ALLCONFIG' file is a config file which contains
	102	+(usually a subset of all) preset config symbols. These variable
	103	+settings are still subject to normal dependency checks.
	104	+
	105	+Examples:
	106	+ KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig
	107	+or
	108	+ KCONFIG_ALLCONFIG=mini.config make allnoconfig
	109	+or
	110	+ make KCONFIG_ALLCONFIG=mini.config allnoconfig
	111	+
	112	+These examples will disable most options (allnoconfig) but enable or
	113	+disable the options that are explicitly listed in the specified
	114	+mini-config files.
	115	+
	116	+KCONFIG_NOSILENTUPDATE
	117	+--------------------------------------------------
	118	+If this variable has a non-blank value, it prevents silent kernel
	119	+config udpates (requires explicit updates).
	120	+
	121	+KCONFIG_CONFIG
	122	+--------------------------------------------------
	123	+This environment variable can be used to specify a default kernel config
	124	+file name to override the default name of ".config".
	125	+
	126	+KCONFIG_OVERWRITECONFIG
	127	+--------------------------------------------------
	128	+If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not
	129	+break symlinks when .config is a symlink to somewhere else.
	130	+
	131	+KCONFIG_NOTIMESTAMP
	132	+--------------------------------------------------
	133	+If this environment variable exists and is non-null, the timestamp line
	134	+in generated .config files is omitted.
	135	+
	136	+KCONFIG_AUTOCONFIG
	137	+--------------------------------------------------
	138	+This environment variable can be set to specify the path & name of the
	139	+"auto.conf" file. Its default value is "include/config/auto.conf".
	140	+
	141	+KCONFIG_AUTOHEADER
	142	+--------------------------------------------------
	143	+This environment variable can be set to specify the path & name of the
	144	+"autoconf.h" (header) file. Its default value is "include/linux/autoconf.h".
	145	+
	146	+______________________________________________________________________
	147	+menuconfig User Interface Options
	148	+----------------------------------------------------------------------
	149	+MENUCONFIG_MODE
	150	+--------------------------------------------------
	151	+This mode shows all sub-menus in one large tree.
	152	+
	153	+Example:
	154	+ MENUCONFIG_MODE=single_menu make menuconfig
	155	+
	156	+======================================================================
	157	+xconfig
	158	+--------------------------------------------------
	159	+
	160	+Searching in xconfig:
	161	+
	162	+ The Search function searches for kernel configuration symbol
	163	+ names, so you have to know something close to what you are
	164	+ looking for.
	165	+
	166	+ Example:
	167	+ Ctrl-F hotplug
	168	+ or
	169	+ Menu: File, Search, hotplug
	170	+
	171	+ lists all config symbol entries that contain "hotplug" in
	172	+ the symbol name. In this Search dialog, you may change the
	173	+ config setting for any of the entries that are not grayed out.
	174	+ You can also enter a different search string without having
	175	+ to return to the main menu.
	176	+
	177	+
	178	+======================================================================
	179	+gconfig
	180	+--------------------------------------------------
	181	+
	182	+Searching in gconfig:
	183	+
	184	+ None (gconfig isn't maintained as well as xconfig or menuconfig);
	185	+ however, gconfig does have a few more viewing choices than
	186	+ xconfig does.
	187	+
	188	+###
...	...	@@ -52,11 +52,11 @@
52	52
53	53	- The Documentation/DocBook/ subdirectory contains several guides for
54	54	kernel developers and users. These guides can be rendered in a
55		- number of formats: PostScript (.ps), PDF, and HTML, among others.
56		- After installation, "make psdocs", "make pdfdocs", or "make htmldocs"
57		- will render the documentation in the requested format.
	55	+ number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others.
	56	+ After installation, "make psdocs", "make pdfdocs", "make htmldocs",
	57	+ or "make mandocs" will render the documentation in the requested format.
58	58
59		-INSTALLING the kernel:
	59	+INSTALLING the kernel source:
60	60
61	61	- If you install the full sources, put the kernel tarball in a
62	62	directory where you have permissions (eg. your home directory) and
...	...	@@ -187,14 +187,9 @@
187	187	"make randconfig" Create a ./.config file by setting symbol
188	188	values to random values.
189	189
190		- The allyesconfig/allmodconfig/allnoconfig/randconfig variants can
191		- also use the environment variable KCONFIG_ALLCONFIG to specify a
192		- filename that contains config options that the user requires to be
193		- set to a specific value. If KCONFIG_ALLCONFIG=filename is not used,
194		- "make *config" checks for a file named "all{yes/mod/no/random}.config"
195		- for symbol values that are to be forced. If this file is not found,
196		- it checks for a file named "all.config" to contain forced values.
197		-
	190	+ You can find more information on using the Linux kernel config tools
	191	+ in Documentation/kbuild/make-configs.txt.
	192	+
198	193	NOTES on "make config":
199	194	- having unnecessary drivers will make the kernel bigger, and can
200	195	under some circumstances lead to problems: probing for a
...	...	@@ -230,6 +225,19 @@
230	225
231	226	- If you configured any of the parts of the kernel as `modules', you
232	227	will also have to do "make modules_install".
	228	+
	229	+ - Verbose kernel compile/build output:
	230	+
	231	+ Normally the kernel build system runs in a fairly quiet mode (but not
	232	+ totally silent). However, sometimes you or other kernel developers need
	233	+ to see compile, link, or other commands exactly as they are executed.
	234	+ For this, use "verbose" build mode. This is done by inserting
	235	+ "V=1" in the "make" command. E.g.:
	236	+
	237	+ make V=1 all
	238	+
	239	+ To have the build system also tell the reason for the rebuild of each
	240	+ target, use "V=2". The default is "V=0".
233	241
234	242	- Keep a backup kernel handy in case something goes wrong. This is
235	243	especially true for the development releases, since each new release