src/sys/core/README.md - fuchsia - Git at Google

 # How to vary a core realm

 Note: for a more in-depth explanation, see [RFC-0089][rfc].

 The core realm is the highest-level CFv2 component realm holding other packaged
 components. The contents of this realm may vary across products, as certain
 parts of our platform belongs in certain configurations and not in others.

 The exact contents of the core realm are controlled by a GN argument that is set
 in the product definitions (located in //products). This argument contains a
 list of GN targets. These targets are walked at GN metadata time to find CML
 shard files to be [merged with][cml-includes] a common base to create the core
 realm.

 ## The core's base

 The common portions of the core realm which are shared across all products are
 included in `//src/sys/core/meta/core.cml`.

 Any components or capability routes included in this file will be part of all
 Fuchsia products. Core shard operations are only additive. Therefore if a new
 product is added which wishes to exclude a portion of this file, the
 to-be-excluded contents should be removed from this file and added to a new core
 shard.

 ## The core shards

 The optional portions of the core realm are included in separate CML files, and
 are pointed to by the `core_shard` template defined in
 `//src/sys/core/build/core_shard.gni`.

 Any product wishing to merge a shard into its core realm should include the
 shard's GN target in the `core_realm_shards` argument in the product's `.gni`
 file.

 ## The core name

 Each product which uses the `core_realm_shards` argument should set a unique
 value for the `core_realm_package_name`. This value is used for the name of the
 generated core realm's package, so that the core realm packages between
 different products can be disambiguated.

 By convention, this value should be set to `core-$PRODUCT_NAME`. So for example
 the workstation product's core package name is `core-workstation`.

 [rfc]: //docs/contribute/governance/rfcs/0089_core_realm_variations.md
 [cml-includes]: //docs/development/components/build.md#component-manifest-includes
	# How to vary a core realm

	Note: for a more in-depth explanation, see [RFC-0089][rfc].

	The core realm is the highest-level CFv2 component realm holding other packaged
	components. The contents of this realm may vary across products, as certain
	parts of our platform belongs in certain configurations and not in others.

	The exact contents of the core realm are controlled by a GN argument that is set
	in the product definitions (located in //products). This argument contains a
	list of GN targets. These targets are walked at GN metadata time to find CML
	shard files to be [merged with][cml-includes] a common base to create the core
	realm.

	## The core's base

	The common portions of the core realm which are shared across all products are
	included in `//src/sys/core/meta/core.cml`.

	Any components or capability routes included in this file will be part of all
	Fuchsia products. Core shard operations are only additive. Therefore if a new
	product is added which wishes to exclude a portion of this file, the
	to-be-excluded contents should be removed from this file and added to a new core
	shard.

	## The core shards

	The optional portions of the core realm are included in separate CML files, and
	are pointed to by the `core_shard` template defined in
	`//src/sys/core/build/core_shard.gni`.

	Any product wishing to merge a shard into its core realm should include the
	shard's GN target in the `core_realm_shards` argument in the product's `.gni`
	file.

	## The core name

	Each product which uses the `core_realm_shards` argument should set a unique
	value for the `core_realm_package_name`. This value is used for the name of the
	generated core realm's package, so that the core realm packages between
	different products can be disambiguated.

	By convention, this value should be set to `core-$PRODUCT_NAME`. So for example
	the workstation product's core package name is `core-workstation`.

	[rfc]: //docs/contribute/governance/rfcs/0089_core_realm_variations.md
	[cml-includes]: //docs/development/components/build.md#component-manifest-includes