[deliverable/linux.git] / Documentation / kbuild / kconfig.txt

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 use diffconfig to see the
differences between the previous and new .config files:

	scripts/diffconfig .config.old .config | less

______________________________________________________________________
Environment variables for '*config'

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.

CONFIG_
--------------------------------------------------
If you set CONFIG_ in the environment, Kconfig will prefix all symbols
with its value when saving the configuration, instead of using the default,
"CONFIG_".

______________________________________________________________________
Environment variables for '{allyes/allmod/allno/rand}config'

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 where
KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", "make *config"
checks for a file named "all{yes/mod/no/def/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 symbols of your 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.

______________________________________________________________________
Environment variables for 'randconfig'

KCONFIG_SEED
--------------------------------------------------
You can set this to the integer value used to seed the RNG, if you want
to somehow debug the behaviour of the kconfig parser/frontends.
If not set, the current time will be used.

KCONFIG_PROBABILITY
--------------------------------------------------
This variable can be used to skew the probabilities. This variable can
be unset or empty, or set to three different formats:
	KCONFIG_PROBABILITY     y:n split           y:m:n split
	-----------------------------------------------------------------
	unset or empty          50  : 50            33  : 33  : 34
	N                        N  : 100-N         N/2 : N/2 : 100-N
    [1] N:M                     N+M : 100-(N+M)      N  :  M  : 100-(N+M)
    [2] N:M:L                    N  : 100-N          M  :  L  : 100-(M+L)

where N, M and L are integers (in base 10) in the range [0,100], and so
that:
    [1] N+M is in the range [0,100]
    [2] M+L is in the range [0,100]

Examples:
	KCONFIG_PROBABILITY=10
		10% of booleans will be set to 'y', 90% to 'n'
		5% of tristates will be set to 'y', 5% to 'm', 90% to 'n'
	KCONFIG_PROBABILITY=15:25
		40% of booleans will be set to 'y', 60% to 'n'
		15% of tristates will be set to 'y', 25% to 'm', 60% to 'n'
	KCONFIG_PROBABILITY=10:15:15
		10% of booleans will be set to 'y', 90% to 'n'
		15% of tristates will be set to 'y', 15% to 'm', 70% to 'n'

______________________________________________________________________
Environment variables for 'silentoldconfig'

KCONFIG_NOSILENTUPDATE
--------------------------------------------------
If this variable has a non-blank value, it prevents silent kernel
config updates (requires explicit updates).

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_TRISTATE
--------------------------------------------------
This environment variable can be set to specify the path & name of the
"tristate.conf" file.  Its default value is "include/config/tristate.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/generated/autoconf.h".


======================================================================
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

	When searching, symbols are sorted thus:
	  - exact match first: an exact match is when the search matches
	    the complete symbol name;
	  - alphabetical order: when two symbols do not match exactly,
	    they are sorted in alphabetical order (in the user's current
	    locale).
	For example: ^ATH.K matches:
	    ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG
	    [...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...]
	of which only ATH5K and ATH9K match exactly and so are sorted
	first (and in alphabetical order), then come all other symbols,
	sorted in alphabetical order.

______________________________________________________________________
User interface options for 'menuconfig'

MENUCONFIG_COLOR
--------------------------------------------------
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)

MENUCONFIG_MODE
--------------------------------------------------
This mode shows all sub-menus in one large tree.

Example:
	make MENUCONFIG_MODE=single_menu 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.

###
Commit	Line	Data
2af238e4 RD	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
673d29f9 JM	31	to see the new config symbols or you can use diffconfig to see the
673d29f9 JM	32	differences between the previous and new .config files:
2af238e4	33
673d29f9	34	scripts/diffconfig .config.old .config \| less
2af238e4	35
2af238e4	36	______________________________________________________________________
98f540d3	37	Environment variables for '*config'
2af238e4	38
98f540d3 MH	39	KCONFIG_CONFIG
	40	--------------------------------------------------
	41	This environment variable can be used to specify a default kernel config
	42	file name to override the default name of ".config".
2af238e4	43
98f540d3 MH	44	KCONFIG_OVERWRITECONFIG
	45	--------------------------------------------------
	46	If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not
	47	break symlinks when .config is a symlink to somewhere else.
2af238e4	48
16974326 YM	49	CONFIG_
	50	--------------------------------------------------
	51	If you set CONFIG_ in the environment, Kconfig will prefix all symbols
	52	with its value when saving the configuration, instead of using the default,
	53	"CONFIG_".
	54
2af238e4	55	______________________________________________________________________
98f540d3	56	Environment variables for '{allyes/allmod/allno/rand}config'
2af238e4 RD	57
	58	KCONFIG_ALLCONFIG
	59	--------------------------------------------------
	60	(partially based on lkml email from/by Rob Landley, re: miniconfig)
	61	--------------------------------------------------
5efe241e EB	62	The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also
	63	use the environment variable KCONFIG_ALLCONFIG as a flag or a filename
	64	that contains config symbols that the user requires to be set to a
	65	specific value. If KCONFIG_ALLCONFIG is used without a filename where
	66	KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", "make *config"
	67	checks for a file named "all{yes/mod/no/def/random}.config"
	68	(corresponding to the *config command that was used) for symbol values
	69	that are to be forced. If this file is not found, it checks for a
	70	file named "all.config" to contain forced values.
2af238e4 RD	71
	72	This enables you to create "miniature" config (miniconfig) or custom
	73	config files containing just the config symbols that you are interested
	74	in. Then the kernel config system generates the full .config file,
98f540d3	75	including symbols of your miniconfig file.
2af238e4 RD	76
	77	This 'KCONFIG_ALLCONFIG' file is a config file which contains
	78	(usually a subset of all) preset config symbols. These variable
	79	settings are still subject to normal dependency checks.
	80
	81	Examples:
	82	KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig
	83	or
	84	KCONFIG_ALLCONFIG=mini.config make allnoconfig
	85	or
	86	make KCONFIG_ALLCONFIG=mini.config allnoconfig
	87
	88	These examples will disable most options (allnoconfig) but enable or
	89	disable the options that are explicitly listed in the specified
	90	mini-config files.
	91
0d8024c6 YM	92	______________________________________________________________________
	93	Environment variables for 'randconfig'
	94
	95	KCONFIG_SEED
	96	--------------------------------------------------
	97	You can set this to the integer value used to seed the RNG, if you want
	98	to somehow debug the behaviour of the kconfig parser/frontends.
	99	If not set, the current time will be used.
	100
e43956e6 YM	101	KCONFIG_PROBABILITY
	102	--------------------------------------------------
	103	This variable can be used to skew the probabilities. This variable can
	104	be unset or empty, or set to three different formats:
	105	KCONFIG_PROBABILITY y:n split y:m:n split
	106	-----------------------------------------------------------------
	107	unset or empty 50 : 50 33 : 33 : 34
	108	N N : 100-N N/2 : N/2 : 100-N
	109	[1] N:M N+M : 100-(N+M) N : M : 100-(N+M)
	110	[2] N:M:L N : 100-N M : L : 100-(M+L)
	111
	112	where N, M and L are integers (in base 10) in the range [0,100], and so
	113	that:
	114	[1] N+M is in the range [0,100]
	115	[2] M+L is in the range [0,100]
	116
	117	Examples:
	118	KCONFIG_PROBABILITY=10
	119	10% of booleans will be set to 'y', 90% to 'n'
	120	5% of tristates will be set to 'y', 5% to 'm', 90% to 'n'
	121	KCONFIG_PROBABILITY=15:25
	122	40% of booleans will be set to 'y', 60% to 'n'
	123	15% of tristates will be set to 'y', 25% to 'm', 60% to 'n'
	124	KCONFIG_PROBABILITY=10:15:15
	125	10% of booleans will be set to 'y', 90% to 'n'
	126	15% of tristates will be set to 'y', 15% to 'm', 70% to 'n'
	127
98f540d3 MH	128	______________________________________________________________________
	129	Environment variables for 'silentoldconfig'
	130
2af238e4 RD	131	KCONFIG_NOSILENTUPDATE
	132	--------------------------------------------------
	133	If this variable has a non-blank value, it prevents silent kernel
88393161	134	config updates (requires explicit updates).
2af238e4	135
2af238e4 RD	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
bc081dd6 MM	141	KCONFIG_TRISTATE
	142	--------------------------------------------------
	143	This environment variable can be set to specify the path & name of the
	144	"tristate.conf" file. Its default value is "include/config/tristate.conf".
	145
2af238e4 RD	146	KCONFIG_AUTOHEADER
	147	--------------------------------------------------
	148	This environment variable can be set to specify the path & name of the
264a2683 SR	149	"autoconf.h" (header) file.
264a2683 SR	150	Its default value is "include/generated/autoconf.h".
2af238e4	151
98f540d3 MH	152
	153	======================================================================
	154	menuconfig
	155	--------------------------------------------------
	156
	157	SEARCHING for CONFIG symbols
	158
	159	Searching in menuconfig:
	160
	161	The Search function searches for kernel configuration symbol
	162	names, so you have to know something close to what you are
	163	looking for.
	164
	165	Example:
	166	/hotplug
	167	This lists all config symbols that contain "hotplug",
	168	e.g., HOTPLUG, HOTPLUG_CPU, MEMORY_HOTPLUG.
	169
	170	For search help, enter / followed TAB-TAB-TAB (to highlight
	171	<Help>) and Enter. This will tell you that you can also use
	172	regular expressions (regexes) in the search string, so if you
	173	are not interested in MEMORY_HOTPLUG, you could try
	174
	175	/^hotplug
	176
193b40ae YM	177	When searching, symbols are sorted thus:
	178	- exact match first: an exact match is when the search matches
	179	the complete symbol name;
	180	- alphabetical order: when two symbols do not match exactly,
	181	they are sorted in alphabetical order (in the user's current
	182	locale).
	183	For example: ^ATH.K matches:
	184	ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG
	185	[...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...]
	186	of which only ATH5K and ATH9K match exactly and so are sorted
	187	first (and in alphabetical order), then come all other symbols,
	188	sorted in alphabetical order.
	189
2af238e4	190	______________________________________________________________________
98f540d3 MH	191	User interface options for 'menuconfig'
	192
	193	MENUCONFIG_COLOR
	194	--------------------------------------------------
	195	It is possible to select different color themes using the variable
	196	MENUCONFIG_COLOR. To select a theme use:
	197
	198	make MENUCONFIG_COLOR=<theme> menuconfig
	199
	200	Available themes are:
	201	mono => selects colors suitable for monochrome displays
	202	blackbg => selects a color scheme with black background
	203	classic => theme with blue background. The classic look
	204	bluetitle => a LCD friendly version of classic. (default)
	205
2af238e4 RD	206	MENUCONFIG_MODE
	207	--------------------------------------------------
	208	This mode shows all sub-menus in one large tree.
	209
	210	Example:
98f540d3 MH	211	make MENUCONFIG_MODE=single_menu menuconfig
98f540d3 MH	212
2af238e4 RD	213
	214	======================================================================
	215	xconfig
	216	--------------------------------------------------
	217
	218	Searching in xconfig:
	219
	220	The Search function searches for kernel configuration symbol
	221	names, so you have to know something close to what you are
	222	looking for.
	223
	224	Example:
	225	Ctrl-F hotplug
	226	or
	227	Menu: File, Search, hotplug
	228
	229	lists all config symbol entries that contain "hotplug" in
	230	the symbol name. In this Search dialog, you may change the
	231	config setting for any of the entries that are not grayed out.
	232	You can also enter a different search string without having
	233	to return to the main menu.
	234
	235
	236	======================================================================
	237	gconfig
	238	--------------------------------------------------
	239
	240	Searching in gconfig:
	241
	242	None (gconfig isn't maintained as well as xconfig or menuconfig);
	243	however, gconfig does have a few more viewing choices than
	244	xconfig does.
	245
	246	###