Blame - Changes.md - platform/build

blob: eddec04a6c0f1f810fd430cbe4b0d8555c6c7110 [file] [log] [blame] [view]

Cole Faust	152cdfa	2023-07-26 14:33:51 -0700	[diff] [blame]	1	# Build System Changes for Android.mk/Android.bp Writers
				2
Cole Faust	b099030	2023-10-18 22:50:26 +0000	[diff] [blame]	3	## Soong genrules are now sandboxed
				4
				5	Previously, soong genrules could access any files in the source tree, without specifying them as
				6	inputs. This makes them incorrect in incremental builds, and incompatible with RBE and Bazel.
				7
				8	Now, genrules are sandboxed so they can only access their listed srcs. Modules denylisted in
				9	genrule/allowlists.go are exempt from this. You can also set `BUILD_BROKEN_GENRULE_SANDBOXING`
				10	in board config to disable this behavior.
				11
Cole Faust	152cdfa	2023-07-26 14:33:51 -0700	[diff] [blame]	12	## Partitions are no longer affected by previous builds
				13
				14	Partition builds used to include everything in their staging directories, and building an
				15	individual module will install it to the staging directory. Thus, previously, `m mymodule` followed
				16	by `m` would cause `mymodule` to be presinstalled on the device, even if it wasn't listed in
				17	`PRODUCT_PACKAGES`.
				18
				19	This behavior has been changed, and now the partition images only include what they'd have if you
				20	did a clean build. This behavior can be disabled by setting the
				21	`BUILD_BROKEN_INCORRECT_PARTITION_IMAGES` environment variable or board config variable.
Dan Willemsen	7733862	2017-11-08 16:39:18 -0800	[diff] [blame]	22
Cole Faust	c6a0d4d	2023-09-12 16:54:19 -0700	[diff] [blame]	23	Manually adding make rules that build to the staging directories without going through the make
				24	module system will not be compatible with this change. This includes many usages of
				25	`LOCAL_POST_INSTALL_CMD`.
				26
Liz Kammer	bc4f48c	2023-05-18 18:20:22 +0000	[diff] [blame]	27	## Perform validation of Soong plugins
				28
				29	Each Soong plugin will require manual work to migrate to Bazel. In order to
				30	minimize the manual work outside of build/soong, we are restricting plugins to
				31	those that exist today and those in vendor or hardware directories.
				32
				33	If you need to extend the build system via a plugin, please reach out to the
				34	build team via email android-building@googlegroups.com (external) for any
				35	questions, or see [go/soong](http://go/soong) (internal).
				36
Liz Kammer	b607281	2023-06-23 11:22:42 -0400	[diff] [blame]	37	To omit the validation, `BUILD_BROKEN_PLUGIN_VALIDATION` expects a
				38	space-separated list of plugins to omit from the validation. This must be set
				39	within a product configuration .mk file, board config .mk file, or buildspec.mk.
Liz Kammer	bc4f48c	2023-05-18 18:20:22 +0000	[diff] [blame]	40
Cole Faust	189905b	2022-09-09 19:41:47 -0700	[diff] [blame]	41	## Python 2 to 3 migration
				42
Cole Faust	afdc73c	2025-02-07 10:32:24 -0800	[diff] [blame]	43	Python 2 has been completely removed from the build. Please migrate any remaining usages to
				44	Python 3, and remove any version-specific properties from bp files.
Cole Faust	152cdfa	2023-07-26 14:33:51 -0700	[diff] [blame]	45
Trevor Radcliffe	c9e7266	2022-08-15 20:08:20 +0000	[diff] [blame]	46	## Stop referencing sysprop_library directly from cc modules
				47
				48	For the migration to Bazel, we are no longer mapping sysprop_library targets
				49	to their generated `cc_library` counterparts when dependning on them from a
				50	cc module. Instead, directly depend on the generated module by prefixing the
				51	module name with `lib`. For example, depending on the following module:
				52
				53	```
				54	sysprop_library {
				55	name: "foo",
				56	srcs: ["foo.sysprop"],
				57	}
				58	```
				59
				60	from a module named `bar` can be done like so:
				61
				62	```
				63	cc_library {
				64	name: "bar",
				65	srcs: ["bar.cc"],
				66	deps: ["libfoo"],
				67	}
				68	```
				69
				70	Failure to do this will result in an error about a missing variant.
				71
Vinh Tran	3fae6fe	2022-06-21 12:00:02 -0400	[diff] [blame]	72	## Gensrcs starts disallowing depfile property
				73
				74	To migrate all gensrcs to Bazel, we are restricting the use of depfile property
				75	because Bazel requires specifying the dependencies directly.
				76
				77	To fix existing uses, remove depfile and directly specify all the dependencies
				78	in .bp files. For example:
				79
				80	```
				81	gensrcs {
				82	name: "framework-cppstream-protos",
				83	tools: [
				84	"aprotoc",
				85	"protoc-gen-cppstream",
				86	],
				87	cmd: "mkdir -p $(genDir)/$(in) " +
				88	"&& $(location aprotoc) " +
				89	" --plugin=$(location protoc-gen-cppstream) " +
				90	" -I . " +
				91	" $(in) ",
				92	srcs: [
				93	"bar.proto",
				94	],
				95	output_extension: "srcjar",
				96	}
				97	```
				98	where `bar.proto` imports `external.proto` would become
				99
				100	```
				101	gensrcs {
				102	name: "framework-cppstream-protos",
				103	tools: [
				104	"aprotoc",
				105	"protoc-gen-cpptream",
				106	],
				107	tool_files: [
				108	"external.proto",
				109	],
				110	cmd: "mkdir -p $(genDir)/$(in) " +
				111	"&& $(location aprotoc) " +
				112	" --plugin=$(location protoc-gen-cppstream) " +
				113	" $(in) ",
				114	srcs: [
				115	"bar.proto",
				116	],
				117	output_extension: "srcjar",
				118	}
				119	```
				120	as in https://android-review.googlesource.com/c/platform/frameworks/base/+/2125692/.
				121
				122	`BUILD_BROKEN_DEPFILE` can be used to allowlist usage of depfile in `gensrcs`.
				123
				124	If `depfile` is needed for generating javastream proto, `java_library` with `proto.type`
				125	set `stream` is the alternative solution. Sees
				126	https://android-review.googlesource.com/c/platform/packages/modules/Permission/+/2118004/
				127	for an example.
				128
Liz Kammer	4065e5b	2022-01-31 16:16:06 -0500	[diff] [blame]	129	## Genrule starts disallowing directory inputs
				130
				131	To better specify the inputs to the build, we are restricting use of directories
				132	as inputs to genrules.
				133
				134	To fix existing uses, change inputs to specify the inputs and update the command
				135	accordingly. For example:
				136
				137	```
				138	genrule: {
				139	name: "foo",
				140	srcs: ["bar"],
				141	cmd: "cp $(location bar)/*.xml $(gendir)",
				142	...
				143	}
				144	```
				145
				146	would become
				147
				148	```
				149	genrule: {
				150	name: "foo",
				151	srcs: ["bar/*.xml"],
				152	cmd: "cp $(in) $(gendir)",
				153	...
				154	}
Andrew Walbran	9b25583	2022-03-09 14:51:51 +0000	[diff] [blame]	155	```
Liz Kammer	4065e5b	2022-01-31 16:16:06 -0500	[diff] [blame]	156
				157	`BUILD_BROKEN_INPUT_DIR_MODULES` can be used to allowlist specific directories
				158	with genrules that have input directories.
				159
Ulya Trafimovich	4b4fd16	2021-03-31 11:49:53 +0100	[diff] [blame]	160	## Dexpreopt starts enforcing `<uses-library>` checks (for Java modules)
				161
				162	In order to construct correct class loader context for dexpreopt, build system
				163	needs to know about the shared library dependencies of Java modules listed in
				164	the `<uses-library>` tags in the manifest. Since the build system does not have
				165	access to the manifest contents, that information must be present in the build
				166	files. In simple cases Soong is able to infer it from its knowledge of Java SDK
				167	libraries and the `libs` property in Android.bp, but in more complex cases it is
				168	necessary to add the missing information in Android.bp/Android.mk manually.
				169
				170	To specify a list of libraries for a given modules, use:
				171
				172	* Android.bp properties: `uses_libs`, `optional_uses_libs`
				173	* Android.mk variables: `LOCAL_USES_LIBRARIES`, `LOCAL_OPTIONAL_USES_LIBRARIES`
				174
				175	If a library is in `libs`, it usually should not be added to the above
				176	properties, and Soong should be able to infer the `<uses-library>` tag. But
				177	sometimes a library also needs additional information in its
				178	Android.bp/Android.mk file (e.g. when it is a `java_library` rather than a
				179	`java_sdk_library`, or when the library name is different from its module name,
				180	or when the module is defined in Android.mk rather than Android.bp). In such
				181	cases it is possible to tell the build system that the library provides a
				182	`<uses-library>` with a given name (however, this is discouraged and will be
				183	deprecated in the future, and it is recommended to fix the underlying problem):
				184
				185	* Android.bp property: `provides_uses_lib`
				186	* Android.mk variable: `LOCAL_PROVIDES_USES_LIBRARY`
				187
				188	It is possible to disable the check on a per-module basis. When doing that it is
				189	also recommended to disable dexpreopt, as disabling a failed check will result
				190	in incorrect class loader context recorded in the .odex file, which will cause
				191	class loader context mismatch and dexopt at first boot.
				192
				193	* Android.bp property: `enforce_uses_lib`
				194	* Android.mk variable: `LOCAL_ENFORCE_USES_LIBRARIES`
				195
				196	Finally, it is possible to globally disable the check:
				197
				198	* For a given product: `PRODUCT_BROKEN_VERIFY_USES_LIBRARIES := true`
				199	* On the command line: `RELAX_USES_LIBRARY_CHECK=true`
				200
				201	The environment variable overrides the product variable, so it is possible to
				202	disable the check for a product, but quickly re-enable it for a local build.
				203
Yo Chiang	64faf88	2020-07-15 18:35:12 +0800	[diff] [blame]	204	## `LOCAL_REQUIRED_MODULES` requires listed modules to exist {#BUILD_BROKEN_MISSING_REQUIRED_MODULES}
				205
				206	Modules listed in `LOCAL_REQUIRED_MODULES`, `LOCAL_HOST_REQUIRED_MODULES` and
				207	`LOCAL_TARGET_REQUIRED_MODULES` need to exist unless `ALLOW_MISSING_DEPENDENCIES`
				208	is set.
				209
				210	To temporarily relax missing required modules check, use:
				211
				212	`BUILD_BROKEN_MISSING_REQUIRED_MODULES := true`
				213
Jiyong Park	0b4fccb	2020-06-26 17:38:00 +0900	[diff] [blame]	214	## Changes in system properties settings
				215
				216	### Product variables
				217
				218	System properties for each of the partition is supposed to be set via following
				219	product config variables.
				220
Donghyun Jo	8c65ef6	2021-03-02 08:51:03 +0900	[diff] [blame]	221	For system partition,
Jiyong Park	0b4fccb	2020-06-26 17:38:00 +0900	[diff] [blame]	222
Donghyun Jo	8c65ef6	2021-03-02 08:51:03 +0900	[diff] [blame]	223	* `PRODUCT_SYSTEM_PROPERTIES`
Jiyong Park	0b4fccb	2020-06-26 17:38:00 +0900	[diff] [blame]	224	* `PRODUCT_SYSTEM_DEFAULT_PROPERTIES` is highly discouraged. Will be deprecated.
				225
				226	For vendor partition,
				227
				228	* `PRODUCT_VENDOR_PROPERTIES`
				229	* `PRODUCT_PROPERTY_OVERRIDES` is highly discouraged. Will be deprecated.
				230	* `PRODUCT_DEFAULT_PROPERTY_OVERRIDES` is also discouraged. Will be deprecated.
				231
				232	For odm partition,
				233
				234	* `PRODUCT_ODM_PROPERTIES`
				235
				236	For system_ext partition,
				237
				238	* `PRODUCT_SYSTEM_EXT_PROPERTIES`
				239
				240	For product partition,
				241
				242	* `PRODUCT_PRODUCT_PROPERTIES`
				243
				244	### Duplication is not allowed within a partition
				245
				246	For each partition, having multiple sysprop assignments for the same name is
				247	prohibited. For example, the following will now trigger an error:
				248
				249	`PRODUCT_VENDOR_PROPERTIES += foo=true foo=false`
				250
				251	Having duplication across partitions are still allowed. So, the following is
				252	not an error:
				253
				254	`PRODUCT_VENDOR_PROPERTIES += foo=true`
				255	`PRODUCT_SYSTEM_PROPERTIES += foo=false`
				256
				257	In that case, the final value is determined at runtime. The precedence is
				258
				259	* product
				260	* odm
				261	* vendor
				262	* system_ext
				263	* system
				264
				265	So, `foo` becomes `true` because vendor has higher priority than system.
				266
				267	To temporarily turn the build-time restriction off, use
				268
				269	`BUILD_BROKEN_DUP_SYSPROP := true`
				270
				271	### Optional assignments
				272
				273	System properties can now be set as optional using the new syntax:
				274
				275	`name ?= value`
				276
				277	Then the system property named `name` gets the value `value` only when there
				278	is no other non-optional assignments having the same name. For example, the
				279	following is allowed and `foo` gets `true`
				280
				281	`PRODUCT_VENDOR_PROPERTIES += foo=true foo?=false`
				282
				283	Note that the order between the optional and the non-optional assignments
				284	doesn't matter. The following gives the same result as above.
				285
				286	`PRODUCT_VENDOR_PROPERTIES += foo?=false foo=true`
				287
				288	Optional assignments can be duplicated and in that case their order matters.
				289	Specifically, the last one eclipses others.
				290
				291	`PRODUCT_VENDOR_PROPERTIES += foo?=apple foo?=banana foo?=mango`
				292
				293	With above, `foo` becomes `mango` since its the last one.
				294
				295	Note that this behavior is different from the previous behavior of preferring
				296	the first one. To go back to the original behavior for compatability reason,
				297	use:
				298
				299	`BUILD_BROKEN_DUP_SYSPROP := true`
				300
Yo Chiang	d474181	2020-07-14 15:15:08 +0800	[diff] [blame]	301	## ELF prebuilts in `PRODUCT_COPY_FILES` {#BUILD_BROKEN_ELF_PREBUILT_PRODUCT_COPY_FILES}
Yo Chiang	73d3148	2020-04-07 15:59:59 +0800	[diff] [blame]	302
Yo Chiang	d474181	2020-07-14 15:15:08 +0800	[diff] [blame]	303	ELF prebuilts in `PRODUCT_COPY_FILES` that are installed into these paths are an
Yo Chiang	73d3148	2020-04-07 15:59:59 +0800	[diff] [blame]	304	error:
				305
				306	* `<partition>/bin/*`
				307	* `<partition>/lib/*`
				308	* `<partition>/lib64/*`
				309
Yo Chiang	d474181	2020-07-14 15:15:08 +0800	[diff] [blame]	310	Define prebuilt modules and add them to `PRODUCT_PACKAGES` instead.
Yo Chiang	73d3148	2020-04-07 15:59:59 +0800	[diff] [blame]	311	To temporarily relax this check and restore the behavior prior to this change,
				312	set `BUILD_BROKEN_ELF_PREBUILT_PRODUCT_COPY_FILES := true` in `BoardConfig.mk`.
				313
Dan Willemsen	66d21d4	2020-01-27 19:26:02 -0800	[diff] [blame]	314	## COPY_HEADERS usage now produces warnings {#copy_headers}
				315
				316	We've considered `BUILD_COPY_HEADERS`/`LOCAL_COPY_HEADERS` to be deprecated for
				317	a long time, and the places where it's been able to be used have shrinked over
				318	the last several releases. Equivalent functionality is not available in Soong.
				319
				320	See the [build/soong/docs/best_practices.md#headers] for more information about
				321	how best to handle headers in Android.
				322
Dan Willemsen	2bfffb9	2020-01-14 10:56:53 -0800	[diff] [blame]	323	## `m4` is not available on `$PATH`
				324
				325	There is a prebuilt of it available in prebuilts/build-tools, and a make
				326	variable `M4` that contains the path.
				327
				328	Beyond the direct usage, whenever you use bison or flex directly, they call m4
				329	behind the scene, so you must set the M4 environment variable (and depend upon
				330	it for incremental build correctness):
				331
				332	```
				333	$(intermediates)/foo.c: .KATI_IMPLICIT_OUTPUTS := $(intermediates)/foo.h
				334	$(intermediates)/foo.c: $(LOCAL_PATH)/foo.y $(M4) $(BISON) $(BISON_DATA)
				335	M4=$(M4) $(BISON) ...
				336	```
				337
Dan Willemsen	2607625	2020-01-02 20:08:10 -0800	[diff] [blame]	338	## Rules executed within limited environment
				339
				340	With `ALLOW_NINJA_ENV=false` (soon to be the default), ninja, and all the
				341	rules/actions executed within it will only have access to a limited number of
				342	environment variables. Ninja does not track when environment variables change
				343	in order to trigger rebuilds, so changing behavior based on arbitrary variables
				344	is not safe with incremental builds.
				345
				346	Kati and Soong can safely use environment variables, so the expectation is that
				347	you'd embed any environment variables that you need to use within the command
				348	line generated by those tools. See the [export section](#export_keyword) below
				349	for examples.
				350
				351	For a temporary workaround, you can set `ALLOW_NINJA_ENV=true` in your
				352	environment to restore the previous behavior, or set
				353	`BUILD_BROKEN_NINJA_USES_ENV_VAR := <var> <var2> ...` in your `BoardConfig.mk`
				354	to allow specific variables to be passed through until you've fixed the rules.
				355
Dan Willemsen	0cb422f	2019-11-25 17:51:18 -0800	[diff] [blame]	356	## LOCAL_C_INCLUDES outside the source/output trees are an error {#BUILD_BROKEN_OUTSIDE_INCLUDE_DIRS}
				357
				358	Include directories are expected to be within the source tree (or in the output
				359	directory, generated during the build). This has been checked in some form
				360	since Oreo, but now has better checks.
				361
				362	There's now a `BUILD_BROKEN_OUTSIDE_INCLUDE_DIRS` variable, that when set, will
				363	turn these errors into warnings temporarily. I don't expect this to last more
				364	than a release, since they're fairly easy to clean up.
				365
				366	Neither of these cases are supported by Soong, and will produce errors when
				367	converting your module.
				368
				369	### Absolute paths
				370
				371	This has been checked since Oreo. The common reason to hit this is because a
				372	makefile is calculating a path, and ran abspath/realpath/etc. This is a problem
				373	because it makes your build non-reproducible. It's very unlikely that your
				374	source path is the same on every machine.
				375
				376	### Using `../` to leave the source/output directories
				377
				378	This is the new check that has been added. In every case I've found, this has
				379	been a mistake in the Android.mk -- assuming that `LOCAL_C_INCLUDES` (which is
				380	relative to the top of the source tree) acts like `LOCAL_SRC_FILES` (which is
				381	relative to `LOCAL_PATH`).
				382
				383	Since this usually isn't a valid path, you can almost always just remove the
				384	offending line.
				385
				386
Dan Willemsen	2607625	2020-01-02 20:08:10 -0800	[diff] [blame]	387	## `BOARD_HAL_STATIC_LIBRARIES` and `LOCAL_HAL_STATIC_LIBRARIES` are obsolete {#BOARD_HAL_STATIC_LIBRARIES}
Yifan Hong	88adfc6	2019-10-11 15:52:44 -0700	[diff] [blame]	388
				389	Define proper HIDL / Stable AIDL HAL instead.
				390
				391	* For libhealthd, use health HAL. See instructions for implementing
				392	health HAL:
				393
				394	* [hardware/interfaces/health/2.1/README.md] for health 2.1 HAL (recommended)
				395	* [hardware/interfaces/health/1.0/README.md] for health 1.0 HAL
				396
				397	* For libdumpstate, use at least Dumpstate HAL 1.0.
				398
Tao Bao	84f88a4	2019-05-28 16:30:18 -0700	[diff] [blame]	399	## PRODUCT_STATIC_BOOT_CONTROL_HAL is obsolete {#PRODUCT_STATIC_BOOT_CONTROL_HAL}
				400
				401	`PRODUCT_STATIC_BOOT_CONTROL_HAL` was the workaround to allow sideloading with
				402	statically linked boot control HAL, before shared library HALs were supported
				403	under recovery. Android Q has added such support (HALs will be loaded in
				404	passthrough mode), and the workarounds are being removed. Targets should build
				405	and install the recovery variant of boot control HAL modules into recovery
				406	image, similar to the ones installed for normal boot. See the change to
				407	crosshatch for example of this:
				408
				409	* [device/google/crosshatch/bootctrl/Android.bp] for `bootctrl.sdm845` building
				410	rules
				411	* [device/google/crosshatch/device.mk] for installing `bootctrl.sdm845.recovery`
				412	and `android.hardware.boot@1.0-impl.recovery` into recovery image
				413
				414	[device/google/crosshatch/bootctrl/Android.bp]: https://android.googlesource.com/device/google/crosshatch/+/master/bootctrl/Android.bp
				415	[device/google/crosshatch/device.mk]: https://android.googlesource.com/device/google/crosshatch/+/master/device.mk
				416
Dan Willemsen	695849e	2019-04-17 12:25:09 -0700	[diff] [blame]	417	## Deprecation of `BUILD_*` module types
				418
				419	See [build/make/Deprecation.md](Deprecation.md) for the current status.
				420
Dan Willemsen	3d05a08	2019-02-22 23:06:03 +0000	[diff] [blame]	421	## `PRODUCT_HOST_PACKAGES` split from `PRODUCT_PACKAGES` {#PRODUCT_HOST_PACKAGES}
				422
				423	Previously, adding a module to `PRODUCT_PACKAGES` that supported both the host
				424	and the target (`host_supported` in Android.bp; two modules with the same name
				425	in Android.mk) would cause both to be built and installed. In many cases you
				426	only want either the host or target versions to be built/installed by default,
				427	and would be over-building with both. So `PRODUCT_PACKAGES` will be changing to
				428	just affect target modules, while `PRODUCT_HOST_PACKAGES` is being added for
				429	host modules.
				430
				431	Functional differences between `PRODUCT_PACKAGES` and `PRODUCT_HOST_PACKAGES`:
				432
				433	* `PRODUCT_HOST_PACKAGES` does not have `_ENG`/`_DEBUG` variants, as that's a
				434	property of the target, not the host.
				435	* `PRODUCT_HOST_PACKAGES` does not support `LOCAL_MODULE_OVERRIDES`.
				436	* `PRODUCT_HOST_PACKAGES` requires listed modules to exist, and be host
				437	modules. (Unless `ALLOW_MISSING_DEPENDENCIES` is set)
				438
				439	This is still an active migration, so currently it still uses
				440	`PRODUCT_PACKAGES` to make installation decisions, but verifies that if we used
				441	`PRODUCT_HOST_PACKAGES`, it would trigger installation for all of the same host
				442	packages. This check ignores shared libraries, as those are not normally
				443	necessary in `PRODUCT_*PACKAGES`, and tended to be over-built (especially the
				444	32-bit variants).
				445
				446	Future changes will switch installation decisions to `PRODUCT_HOST_PACKAGES`
				447	for host modules, error when there's a host-only module in `PRODUCT_PACKAGES`,
				448	and do some further cleanup where `LOCAL_REQUIRED_MODULES` are still merged
				449	between host and target modules with the same name.
				450
Dan Willemsen	46267cb	2019-01-25 14:35:58 -0800	[diff] [blame]	451	## `.c.arm` / `.cpp.arm` deprecation {#file_arm}
				452
				453	In Android.mk files, you used to be able to change LOCAL_ARM_MODE for each
				454	source file by appending `.arm` to the end of the filename in
				455	`LOCAL_SRC_FILES`.
				456
				457	Soong does not support this uncommonly used behavior, instead expecting those
				458	files to be split out into a separate static library that chooses `arm` over
				459	`thumb` for the entire library. This must now also be done in Android.mk files.
				460
Dan Willemsen	f264690	2019-01-25 16:54:37 -0800	[diff] [blame]	461	## Windows cross-compiles no longer supported in Android.mk
				462
				463	Modules that build for Windows (our only `HOST_CROSS` OS currently) must now be
				464	defined in `Android.bp` files.
				465
Dan Willemsen	e048f7e	2019-02-09 18:58:36 -0800	[diff] [blame]	466	## `LOCAL_MODULE_TAGS := eng debug` are obsolete {#LOCAL_MODULE_TAGS}
Dan Willemsen	9569ddd	2019-01-22 19:38:56 -0800	[diff] [blame]	467
Dan Willemsen	e048f7e	2019-02-09 18:58:36 -0800	[diff] [blame]	468	`LOCAL_MODULE_TAGS` value `eng` and `debug` are now obsolete. They allowed
Dan Willemsen	9569ddd	2019-01-22 19:38:56 -0800	[diff] [blame]	469	modules to specify that they should always be installed on `-eng`, or `-eng`
				470	and `-userdebug` builds. This conflicted with the ability for products to
				471	specify which modules should be installed, effectively making it impossible to
				472	build a stripped down product configuration that did not include those modules.
				473
				474	For the equivalent functionality, specify the modules in `PRODUCT_PACKAGES_ENG`
				475	or `PRODUCT_PACKAGES_DEBUG` in the appropriate product makefiles.
				476
				477	Core android packages like `su` got added to the list in
				478	`build/make/target/product/base_system.mk`, but for device-specific modules
				479	there are often better base product makefiles to use instead.
				480
Dan Willemsen	0636428	2019-01-02 14:32:54 -0800	[diff] [blame]	481	## `USER` deprecation {#USER}
				482
				483	`USER` will soon be `nobody` in many cases due to the addition of a sandbox
				484	around the Android build. Most of the time you shouldn't need to know the
				485	identity of the user running the build, but if you do, it's available in the
				486	make variable `BUILD_USERNAME` for now.
				487
				488	Similarly, the `hostname` tool will also be returning a more consistent value
				489	of `android-build`. The real value is available as `BUILD_HOSTNAME`.
				490
Dan Willemsen	6dbb33d	2018-10-21 19:41:49 -0700	[diff] [blame]	491	## `BUILD_NUMBER` removal from Android.mk {#BUILD_NUMBER}
				492
				493	`BUILD_NUMBER` should not be used directly in Android.mk files, as it would
				494	trigger them to be re-read every time the `BUILD_NUMBER` changes (which it does
				495	on every build server build). If possible, just remove the use so that your
				496	builds are more reproducible. If you do need it, use `BUILD_NUMBER_FROM_FILE`:
				497
				498	``` make
				499	$(LOCAL_BUILT_MODULE):
				500	mytool --build_number $(BUILD_NUMBER_FROM_FILE) -o $@
				501	```
				502
				503	That will expand out to a subshell that will read the current `BUILD_NUMBER`
				504	whenever it's run. It will not re-run your command if the build number has
				505	changed, so incremental builds will have the build number from the last time
				506	the particular output was rebuilt.
				507
Dan Willemsen	78c40be	2018-10-17 16:50:49 -0700	[diff] [blame]	508	## `DIST_DIR`, `dist_goal`, and `dist-for-goals` {#dist}
				509
				510	`DIST_DIR` and `dist_goal` are no longer available when reading Android.mk
				511	files (or other build tasks). Always use `dist-for-goals` instead, which takes
				512	a PHONY goal, and a list of files to copy to `$DIST_DIR`. Whenever `dist` is
				513	specified, and the goal would be built (either explicitly on the command line,
				514	or as a dependency of something on the command line), that file will be copied
				515	into `$DIST_DIR`. For example,
				516
				517	``` make
				518	$(call dist-for-goals,foo,bar/baz)
				519	```
				520
				521	will copy `bar/baz` into `$DIST_DIR/baz` when `m foo dist` is run.
				522
Jeongik Cha	05210f9	2023-04-27 11:05:22 +0900	[diff] [blame]	523	#### FILE_NAME_TAG {#FILE_NAME_TAG}
				524
				525	To embed the `BUILD_NUMBER` (or for local builds, `eng.${USER}`), include
				526	`FILE_NAME_TAG_PLACEHOLDER` in the destination:
				527
				528	``` make
				529	# you can use dist-for-goals-with-filenametag function
				530	$(call dist-for-goals-with-filenametag,foo,bar.zip)
				531	# or use FILE_NAME_TAG_PLACEHOLDER manually
				532	$(call dist-for-goals,foo,bar.zip:baz-FILE_NAME_TAG_PLACEHOLDER.zip)
				533	```
				534
				535	Which will produce `$DIST_DIR/baz-1234567.zip` on build servers which set
				536	`BUILD_NUMBER=1234567`, or `$DIST_DIR/baz-eng.builder.zip` for local builds.
				537
				538	If you just want to append `BUILD_NUMBER` at the end of basename, use
				539	`dist-for-goals-with-filenametag` instead of `dist-for-goals`.
				540
Dan Willemsen	78c40be	2018-10-17 16:50:49 -0700	[diff] [blame]	541	#### Renames during copy
				542
				543	Instead of specifying just a file, a destination name can be specified,
				544	including subdirectories:
				545
				546	``` make
				547	$(call dist-for-goals,foo,bar/baz:logs/foo.log)
				548	```
				549
				550	will copy `bar/baz` into `$DIST_DIR/logs/foo.log` when `m foo dist` is run.
				551
Dan Willemsen	5fb16a6	2018-09-04 16:23:14 -0700	[diff] [blame]	552	## `.PHONY` rule enforcement {#phony_targets}
				553
				554	There are several new warnings/errors meant to ensure the proper use of
				555	`.PHONY` targets in order to improve the speed and reliability of incremental
				556	builds.
				557
				558	`.PHONY`-marked targets are often used as shortcuts to provide "friendly" names
				559	for real files to be built, but any target marked with `.PHONY` is also always
				560	considered dirty, needing to be rebuilt every build. This isn't a problem for
				561	aliases or one-off user-requested operations, but if real builds steps depend
				562	on a `.PHONY` target, it can get quite expensive for what should be a tiny
				563	build.
				564
				565	``` make
				566	...mk:42: warning: PHONY target "out/.../foo" looks like a real file (contains a "/")
				567	```
				568
				569	Between this warning and the next, we're requiring that `.PHONY` targets do not
				570	have "/" in them, and real file targets do have a "/". This makes it more
				571	obvious when reading makefiles what is happening, and will help the build
				572	system differentiate these in the future too.
				573
				574	``` make
				575	...mk:42: warning: writing to readonly directory: "kernel-modules"
				576	```
				577
				578	This warning will show up for one of two reasons:
				579
				580	1. The target isn't intended to be a real file, and should be marked with
				581	`.PHONY`. This would be the case for this example.
				582	2. The target is a real file, but it's outside the output directories. All
				583	outputs from the build system should be within the output directory,
				584	otherwise `m clean` is unable to clean the build, and future builds may not
				585	work properly.
				586
				587	``` make
				588	...mk:42: warning: real file "out/.../foo" depends on PHONY target "buildbins"
				589	```
				590
				591	If the first target isn't intended to be a real file, then it should be marked
				592	with `.PHONY`, which will satisfy this warning. This isn't the case for this
				593	example, as we require `.PHONY` targets not to have '/' in them.
				594
				595	If the second (PHONY) target is a real file, it may unnecessarily be marked
				596	with `.PHONY`.
				597
				598	### `.PHONY` and calling other build systems
				599
				600	One common pattern (mostly outside AOSP) that we've seen hit these warning is
				601	when building with external build systems (firmware, bootloader, kernel, etc).
				602	Those are often marked as `.PHONY` because the Android build system doesn't
				603	have enough dependencies to know when to run the other build system again
				604	during an incremental build.
				605
				606	We recommend to build these outside of Android, and deliver prebuilts into the
				607	Android tree instead of decreasing the speed and reliability of the incremental
				608	Android build.
				609
				610	In cases where that's not desired, to preserve the speed of Android
				611	incrementals, over-specifying dependencies is likely a better option than
				612	marking it with `.PHONY`:
				613
				614	``` make
				615	out/target/.../zImage: $(sort $(shell find -L $(KERNEL_SRCDIR)))
				616	...
				617	```
				618
				619	For reliability, many of these other build systems do not guarantee the same
				620	level of incremental build assurances as the Android Build is attempting to do
				621	-- without custom checks, Make doesn't rebuild objects when CFLAGS change, etc.
				622	In order to fix this, our recommendation is to do clean builds for each of
				623	these external build systems every time anything they rely on changes. For
				624	relatively smaller builds (like the kernel), this may be reasonable as long as
				625	you're not trying to actively debug the kernel.
				626
				627	## `export` and `unexport` deprecation {#export_keyword}
Dan Willemsen	8b9c3cc	2018-02-27 02:15:32 -0800	[diff] [blame]	628
Dan Willemsen	3a1072a	2019-05-14 22:03:58 -0700	[diff] [blame]	629	The `export` and `unexport` keywords are obsolete, and will throw errors when
				630	used.
Dan Willemsen	8b9c3cc	2018-02-27 02:15:32 -0800	[diff] [blame]	631
Dan Willemsen	8b9c3cc	2018-02-27 02:15:32 -0800	[diff] [blame]	632	Device specific configuration should not be able to affect common core build
				633	steps -- we're looking at triggering build steps to be invalidated if the set
				634	of environment variables they can access changes. If device specific
				635	configuration is allowed to change those, switching devices with the same
				636	output directory could become significantly more expensive than it already can
				637	be.
				638
Dan Willemsen	3a1072a	2019-05-14 22:03:58 -0700	[diff] [blame]	639	If used during Android.mk files, and later tasks, it is increasingly likely
				640	that they are being used incorrectly. Attempting to change the environment for
				641	a single build step, and instead setting it for hundreds of thousands.
Dan Willemsen	8b9c3cc	2018-02-27 02:15:32 -0800	[diff] [blame]	642
				643	It is not recommended to just move the environment variable setting outside of
				644	the build (in vendorsetup.sh, or some other configuration script or wrapper).
				645	We expect to limit the environment variables that the build respects in the
				646	future, others will be cleared. (There will be methods to get custom variables
				647	into the build, just not to every build step)
				648
				649	Instead, write the export commands into the rule command lines themselves:
				650
				651	``` make
				652	$(intermediates)/generated_output.img:
				653	rm -rf $@
				654	export MY_ENV_A="$(MY_A)"; make ...
				655	```
				656
				657	If you want to set many environment variables, and/or use them many times,
				658	write them out to a script and source the script:
				659
				660	``` make
				661	envsh := $(intermediates)/env.sh
				662	$(envsh):
				663	rm -rf $@
				664	echo 'export MY_ENV_A="$(MY_A)"' >$@
				665	echo 'export MY_ENV_B="$(MY_B)"' >>$@
				666
				667	$(intermediates)/generated_output.img: PRIVATE_ENV := $(envsh)
				668	$(intermediates)/generated_output.img: $(envsh) a/b/c/package.sh
				669	rm -rf $@
				670	source $(PRIVATE_ENV); make ...
				671	source $(PRIVATE_ENV); a/b/c/package.sh ...
				672	```
				673
Dan Willemsen	5f76fc0	2018-06-21 21:42:29 -0700	[diff] [blame]	674	## Implicit make rules are obsolete {#implicit_rules}
Dan Willemsen	62db0f0	2018-06-16 09:37:13 -0700	[diff] [blame]	675
				676	Implicit rules look something like the following:
				677
				678	``` make
				679	$(TARGET_OUT_SHARED_LIBRARIES)/%_vendor.so: $(TARGET_OUT_SHARED_LIBRARIES)/%.so
				680	...
				681
				682	%.o : %.foo
				683	...
				684	```
				685
Dan Willemsen	5f76fc0	2018-06-21 21:42:29 -0700	[diff] [blame]	686	These can have wide ranging effects across unrelated modules, so they're now obsolete. Instead, use static pattern rules, which are similar, but explicitly match the specified outputs:
Dan Willemsen	62db0f0	2018-06-16 09:37:13 -0700	[diff] [blame]	687
				688	``` make
				689	libs := $(foreach lib,libfoo libbar,$(TARGET_OUT_SHARED_LIBRARIES)/$(lib)_vendor.so)
				690	$(libs): %_vendor.so: %.so
				691	...
				692
				693	files := $(wildcard $(LOCAL_PATH)/*.foo)
				694	gen := $(patsubst $(LOCAL_PATH)/%.foo,$(intermediates)/%.o,$(files))
				695	$(gen): %.o : %.foo
				696	...
				697	```
				698
Dan Willemsen	ac92659	2018-06-11 22:28:00 -0700	[diff] [blame]	699	## Removing '/' from Valid Module Names {#name_slash}
				700
				701	The build system uses module names in path names in many places. Having an
				702	extra '/' or '../' being inserted can cause problems -- and not just build
				703	breaks, but stranger invalid behavior.
				704
				705	In every case we've seen, the fix is relatively simple: move the directory into
				706	`LOCAL_MODULE_RELATIVE_PATH` (or `LOCAL_MODULE_PATH` if you're still using it).
				707	If this causes multiple modules to be named the same, use unique module names
				708	and `LOCAL_MODULE_STEM` to change the installed file name:
				709
				710	``` make
				711	include $(CLEAR_VARS)
				712	LOCAL_MODULE := ver1/code.bin
				713	LOCAL_MODULE_PATH := $(TARGET_OUT_ETC)/firmware
				714	...
				715	include $(BUILD_PREBUILT)
				716
				717	include $(CLEAR_VARS)
				718	LOCAL_MODULE := ver2/code.bin
				719	LOCAL_MODULE_PATH := $(TARGET_OUT_ETC)/firmware
				720	...
				721	include $(BUILD_PREBUILT)
				722	```
				723
				724	Can be rewritten as:
				725
				726	```
				727	include $(CLEAR_VARS)
				728	LOCAL_MODULE := ver1_code.bin
				729	LOCAL_MODULE_STEM := code.bin
				730	LOCAL_MODULE_PATH := $(TARGET_OUT_VENDOR)/firmware/ver1
				731	...
				732	include $(BUILD_PREBUILT)
				733
				734	include $(CLEAR_VARS)
				735	LOCAL_MODULE := ver2_code.bin
				736	LOCAL_MODULE_STEM := code.bin
				737	LOCAL_MODULE_PATH := $(TARGET_OUT_VENDOR)/firmware/ver2
				738	...
				739	include $(BUILD_PREBUILT)
				740	```
				741
				742	You just need to make sure that any other references (`PRODUCT_PACKAGES`,
				743	`LOCAL_REQUIRED_MODULES`, etc) are converted to the new names.
				744
Dan Willemsen	bbe6a02	2018-06-10 14:49:01 -0700	[diff] [blame]	745	## Valid Module Names {#name}
				746
				747	We've adopted lexical requirements very similar to [Bazel's
				748	requirements](https://docs.bazel.build/versions/master/build-ref.html#name) for
				749	target names. Valid characters are `a-z`, `A-Z`, `0-9`, and the special
Dan Willemsen	ac92659	2018-06-11 22:28:00 -0700	[diff] [blame]	750	characters `_.+-=,@~`. This currently applies to `LOCAL_PACKAGE_NAME`,
Dan Willemsen	bbe6a02	2018-06-10 14:49:01 -0700	[diff] [blame]	751	`LOCAL_MODULE`, and `LOCAL_MODULE_SUFFIX`, and `LOCAL_MODULE_STEM*`.
				752
				753	Many other characters already caused problems if you used them, so we don't
				754	expect this to have a large effect.
				755
Dan Willemsen	5039ef4	2018-05-18 11:00:17 -0700	[diff] [blame]	756	## PATH Tools {#PATH_Tools}
				757
				758	The build has started restricting the external host tools usable inside the
				759	build. This will help ensure that build results are reproducible across
				760	different machines, and catch mistakes before they become larger issues.
				761
				762	To start with, this includes replacing the $PATH with our own directory of
				763	tools, mirroring that of the host PATH. The only difference so far is the
				764	removal of the host GCC tools. Anything that is not explicitly in the
				765	configuration as allowed will continue functioning, but will generate a log
				766	message. This is expected to become more restrictive over time.
				767
				768	The configuration is located in build/soong/ui/build/paths/config.go, and
				769	contains all the common tools in use in many builds. Anything not in that list
				770	will currently print a warning in the `$OUT_DIR/soong.log` file, including the
				771	command and arguments used, and the process tree in order to help locate the
				772	usage.
				773
				774	In order to fix any issues brought up by these checks, the best way to fix them
				775	is to use tools checked into the tree -- either as prebuilts, or building them
				776	as host tools during the build.
				777
				778	As a temporary measure, you can set `TEMPORARY_DISABLE_PATH_RESTRICTIONS=true`
				779	in your environment to temporarily turn off the error checks and allow any tool
				780	to be used (with logging). Beware that GCC didn't work well with the interposer
				781	used for logging, so this may not help in all cases.
				782
Dan Willemsen	79fd696	2017-11-28 22:32:05 -0800	[diff] [blame]	783	## Deprecating / obsoleting envsetup.sh variables in Makefiles
Dan Willemsen	7733862	2017-11-08 16:39:18 -0800	[diff] [blame]	784
				785	It is not required to source envsetup.sh before running a build. Many scripts,
				786	including a majority of our automated build systems, do not do so. Make will
				787	transparently make every environment variable available as a make variable.
				788	This means that relying on environment variables only set up in envsetup.sh will
				789	produce different output for local users and scripted users.
				790
				791	Many of these variables also include absolute path names, which we'd like to
				792	keep out of the generated files, so that you don't need to do a full rebuild if
				793	you move the source tree.
				794
				795	To fix this, we're marking the variables that are set in envsetup.sh as
				796	deprecated in the makefiles. This will trigger a warning every time one is read
Dan Willemsen	79fd696	2017-11-28 22:32:05 -0800	[diff] [blame]	797	(or written) inside Kati. Once all the warnings have been removed for a
				798	particular variable, we'll switch it to obsolete, and any references will become
				799	errors.
Dan Willemsen	7733862	2017-11-08 16:39:18 -0800	[diff] [blame]	800
				801	### envsetup.sh variables with make equivalents
				802
				803	\| instead of \| use \|
				804	\|--------------------------------------------------------------\|----------------------\|
Yasuhiro Kubota	cd301f6	2018-10-09 15:51:23 +0900	[diff] [blame]	805	\| OUT {#OUT} \| PRODUCT_OUT \|
Dan Willemsen	7733862	2017-11-08 16:39:18 -0800	[diff] [blame]	806	\| ANDROID_HOST_OUT {#ANDROID_HOST_OUT} \| HOST_OUT \|
				807	\| ANDROID_PRODUCT_OUT {#ANDROID_PRODUCT_OUT} \| PRODUCT_OUT \|
				808	\| ANDROID_HOST_OUT_TESTCASES {#ANDROID_HOST_OUT_TESTCASES} \| HOST_OUT_TESTCASES \|
				809	\| ANDROID_TARGET_OUT_TESTCASES {#ANDROID_TARGET_OUT_TESTCASES} \| TARGET_OUT_TESTCASES \|
				810
				811	All of the make variables may be relative paths from the current directory, or
				812	absolute paths if the output directory was specified as an absolute path. If you
				813	need an absolute variable, convert it to absolute during a rule, so that it's
				814	not expanded into the generated ninja file:
				815
				816	``` make
				817	$(PRODUCT_OUT)/gen.img: my/src/path/gen.sh
				818	export PRODUCT_OUT=$$(cd $(PRODUCT_OUT); pwd); cd my/src/path; ./gen.sh -o $${PRODUCT_OUT}/gen.img
				819	```
				820
				821	### ANDROID_BUILD_TOP {#ANDROID_BUILD_TOP}
				822
				823	In Android.mk files, you can always assume that the current directory is the
				824	root of the source tree, so this can just be replaced with '.' (which is what
				825	$TOP is hardcoded to), or removed entirely. If you need an absolute path, see
				826	the instructions above.
				827
				828	### Stop using PATH directly {#PATH}
				829
				830	This isn't only set by envsetup.sh, but it is modified by it. Due to that it's
				831	rather easy for this to change between different shells, and it's not ideal to
				832	reread the makefiles every time this changes.
				833
				834	In most cases, you shouldn't need to touch PATH at all. When you need to have a
				835	rule reference a particular binary that's part of the source tree or outputs,
				836	it's preferrable to just use the path to the file itself (since you should
				837	already be adding that as a dependency).
				838
				839	Depending on the rule, passing the file path itself may not be feasible due to
				840	layers of unchangable scripts/binaries. In that case, be sure to add the
				841	dependency, but modify the PATH within the rule itself:
				842
				843	``` make
				844	$(TARGET): myscript my/path/binary
				845	PATH=my/path:$$PATH myscript -o $@
				846	```
				847
				848	### Stop using PYTHONPATH directly {#PYTHONPATH}
				849
				850	Like PATH, this isn't only set by envsetup.sh, but it is modified by it. Due to
				851	that it's rather easy for this to change between different shells, and it's not
				852	ideal to reread the makefiles every time.
				853
				854	The best solution here is to start switching to Soong's python building support,
				855	which packages the python interpreter, libraries, and script all into one file
				856	that no longer needs PYTHONPATH. See fontchain_lint for examples of this:
				857
				858	* [external/fonttools/Lib/fontTools/Android.bp] for python_library_host
				859	* [frameworks/base/Android.bp] for python_binary_host
				860	* [frameworks/base/data/fonts/Android.mk] to execute the python binary
				861
				862	If you still need to use PYTHONPATH, do so within the rule itself, just like
				863	path:
				864
				865	``` make
				866	$(TARGET): myscript.py $(sort $(shell find my/python/lib -name '*.py'))
				867	PYTHONPATH=my/python/lib:$$PYTHONPATH myscript.py -o $@
				868	```
Yifan Hong	97de88c	2017-12-12 18:01:09 -0800	[diff] [blame]	869	### Stop using PRODUCT_COMPATIBILITY_MATRIX_LEVEL_OVERRIDE directly {#PRODUCT_COMPATIBILITY_MATRIX_LEVEL_OVERRIDE}
				870
				871	Specify Framework Compatibility Matrix Version in device manifest by adding a `target-level`
				872	attribute to the root element `<manifest>`. If `PRODUCT_COMPATIBILITY_MATRIX_LEVEL_OVERRIDE`
				873	is 26 or 27, you can add `"target-level"="1"` to your device manifest instead.
Dan Willemsen	7733862	2017-11-08 16:39:18 -0800	[diff] [blame]	874
Stephen Hines	178cf8e	2018-01-11 11:54:48 -0800	[diff] [blame]	875	### Stop using USE_CLANG_PLATFORM_BUILD {#USE_CLANG_PLATFORM_BUILD}
				876
				877	Clang is the default and only supported Android compiler, so there is no reason
				878	for this option to exist.
				879
Alix	a9324f0	2022-04-22 03:49:45 +0000	[diff] [blame]	880	### Stop using clang property
				881
Cole Faust	189905b	2022-09-09 19:41:47 -0700	[diff] [blame]	882	The clang property has been deleted from Soong. To fix any build errors, remove the clang
Alix	a9324f0	2022-04-22 03:49:45 +0000	[diff] [blame]	883	property from affected Android.bp files using bpmodify.
				884
				885
				886	``` make
				887	go run bpmodify.go -w -m=module_name -remove-property=true -property=clang filepath
				888	```
				889
Alix	7a4d539	2022-08-25 14:17:18 +0000	[diff] [blame]	890	`BUILD_BROKEN_CLANG_PROPERTY` can be used as temporarily workaround
Alix Espino	38e07f1	2022-09-14 19:10:51 +0000	[diff] [blame]	891
				892
				893	### Stop using clang_cflags and clang_asflags
				894
				895	clang_cflags and clang_asflags are deprecated.
				896	To fix any build errors, use bpmodify to either
				897	- move the contents of clang_asflags/clang_cflags into asflags/cflags or
				898	- delete clang_cflags/as_flags as necessary
				899
				900	To Move the contents:
				901	``` make
				902	go run bpmodify.go -w -m=module_name -move-property=true -property=clang_cflags -new-location=cflags filepath
				903	```
				904
				905	To Delete:
				906	``` make
				907	go run bpmodify.go -w -m=module_name -remove-property=true -property=clang_cflags filepath
				908	```
				909
				910	`BUILD_BROKEN_CLANG_ASFLAGS` and `BUILD_BROKEN_CLANG_CFLAGS` can be used as temporarily workarounds
				911
Dan Willemsen	7733862	2017-11-08 16:39:18 -0800	[diff] [blame]	912	### Other envsetup.sh variables {#other_envsetup_variables}
				913
				914	* ANDROID_TOOLCHAIN
				915	* ANDROID_TOOLCHAIN_2ND_ARCH
				916	* ANDROID_DEV_SCRIPTS
				917	* ANDROID_EMULATOR_PREBUILTS
				918	* ANDROID_PRE_BUILD_PATHS
				919
				920	These are all exported from envsetup.sh, but don't have clear equivalents within
				921	the makefile system. If you need one of them, you'll have to set up your own
				922	version.
				923
Cole Faust	cb30a80	2022-11-07 17:07:25 -0800	[diff] [blame]	924	## Soong config variables
				925
				926	### Soong config string variables must list all values they can be set to
				927
				928	In order to facilitate the transition to bazel, all soong_config_string_variables
				929	must only be set to a value listed in their `values` property, or an empty string.
				930	It is a build error otherwise.
				931
				932	Example Android.bp:
				933	```
				934	soong_config_string_variable {
				935	name: "my_string_variable",
				936	values: [
				937	"foo",
				938	"bar",
				939	],
				940	}
				941
				942	soong_config_module_type {
				943	name: "my_cc_defaults",
				944	module_type: "cc_defaults",
				945	config_namespace: "my_namespace",
				946	variables: ["my_string_variable"],
				947	properties: [
				948	"shared_libs",
				949	"static_libs",
				950	],
				951	}
				952	```
				953	Product config:
				954	```
				955	$(call soong_config_set,my_namespace,my_string_variable,baz) # Will be an error as baz is not listed in my_string_variable's values.
				956	```
Dan Willemsen	7733862	2017-11-08 16:39:18 -0800	[diff] [blame]	957
				958	[build/soong/Changes.md]: https://android.googlesource.com/platform/build/soong/+/master/Changes.md
Dan Willemsen	66d21d4	2020-01-27 19:26:02 -0800	[diff] [blame]	959	[build/soong/docs/best_practices.md#headers]: https://android.googlesource.com/platform/build/soong/+/master/docs/best_practices.md#headers
Dan Willemsen	7733862	2017-11-08 16:39:18 -0800	[diff] [blame]	960	[external/fonttools/Lib/fontTools/Android.bp]: https://android.googlesource.com/platform/external/fonttools/+/master/Lib/fontTools/Android.bp
				961	[frameworks/base/Android.bp]: https://android.googlesource.com/platform/frameworks/base/+/master/Android.bp
				962	[frameworks/base/data/fonts/Android.mk]: https://android.googlesource.com/platform/frameworks/base/+/master/data/fonts/Android.mk
Yifan Hong	88adfc6	2019-10-11 15:52:44 -0700	[diff] [blame]	963	[hardware/interfaces/health/1.0/README.md]: https://android.googlesource.com/platform/hardware/interfaces/+/master/health/1.0/README.md
				964	[hardware/interfaces/health/2.1/README.md]: https://android.googlesource.com/platform/hardware/interfaces/+/master/health/2.1/README.md