[mirror_ubuntu-bionic-kernel.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
	make listnewconfig

and the config program will list any new symbols, one per line.

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