docs/get-started/learn/components/declaring-components.md - fuchsia - Git at Google

 # Declaring components

 Every component has a declaration that describes the component's attributes and
 capabilities. For components that are distributed in packages, the declaration
 is expressed using a **component manifest file** and loaded with the help of a
 **component resolver**.

 ![Diagram showing how components are declared using a "component manifest." The
 manifest is compiled by the developer tools and resolved onto the device at
 runtime.](images/component-manifest.png){: width="836"}

 You declare components using component manifest language (CML) files. At build
 time, the Component Manifest Compiler (`cmc`) tool validates and compiles the
 manifest source into a binary format (`.cm`) and stores it in the component's
 package. At runtime, component resolvers load the manifest into a
 [ComponentDecl](https://fuchsia.dev/reference/fidl/fuchsia.sys2#ComponentDecl)
 FIDL structure for [Component Manager](/docs/glossary/README.md#Component-Manager).

 ## Component manifests

 CML files are JSON5 files that end with a `.cml` extension. Below is an example
 CML manifest file for a simple component running an ELF binary that prints a
 "Hello, World" message to the system log:

 ```json5
 {
     // Information about the program to run.
     program: {
         // Use the built-in ELF runner.
         runner: "elf",
         // The binary to run for this component.
         binary: "bin/hello",
         // Program arguments
         args: [
             "Hello",
             "World!",
         ],
     },

     // Capabilities used by this component.
     use: [
         { protocol: "fuchsia.logger.LogSink" },
     ],
 }
 ```

 This file declares two main sections of information about the component:

 Note: For more details on component manifests and CML syntax, see
 [component manifests](/docs/concepts/components/v2/component_manifests.md).

 * `program`: Describes the executable information such as the binary file,
   program arguments, and the associated runtime. In this example, a binary
   written in C++ or Rust is compiled as an ELF executable and uses the built-in
   [ELF runner](/docs/concepts/components/v2/elf_runner.md).
 * `use`: Declares the capabilities this component requires to run. In this
   example, the `fuchsia.logger.LogSink` protocol enables the component to write
   messages to the system log (`syslog`).

 ## Manifest shards

 Some collections of capabilities represent use case requirements that are common
 to many components in the system, such as logging. To simplify including these
 capabilities in your components, the framework abstracts them into
 **manifest shards** that can be included in your CML source file.

 Below is an equivalent CML to the previous example. In this case, the necessary
 logging capabilities are provided by including
 `diagnostics/syslog/client.shard.cml` instead of declaring
 `fuchsia.logger.LogSink` explicitly:

 ```json5
 {
     include: [ "syslog/client.shard.cml" ],

     // Information about the program to run.
     program: {
         // Use the built-in ELF runner.
         runner: "elf",
         // The binary to run for this component.
         binary: "bin/hello-world",
         // Program arguments
         args: [
             "Hello",
             "World!",
         ],
     },
 }
 ```

 <aside class="key-point">
 To review the merged CML output with all includes resolved, run the
 <code>fx cmc include</code> command with your manifest. For more details, see
 the <a href="/docs/reference/tools/sdk/cmc.md"> reference documentation</a>.
 </aside>

 ## Building components

 The Fuchsia build system provides templates as GN imports in
 [`//build/components.gni`](/build/components.gni) to build and package software
 into Fuchsia components. Below is an example of a `BUILD.gn` file for a simple
 C++ component:

 ```gn
 {% verbatim %}
 import("//build/components.gni")

 executable("bin") {
   sources = [ "main.cc" ]
 }

 resource("my_file") {
   sources = [ "my_file.txt" ]
   outputs = [ "data/{{source_file_part}}" ]
 }

 fuchsia_component("hello-world-component") {
   component_name = "hello-world"
   deps = [
     ":bin",
     ":my_file",
   ]
   manifest = "meta/hello-world.cml"
 }

 fuchsia_package("hello-world") {
   package-name = "hello-world"
   deps = [
     ":hello-world-component",
   ]
 }
 {% endverbatim %}
 ```

 This file contains the following main elements:

 * `executable()`: Compiles the source code into a binary. This target varies
   depending on the programming language. For example, an `executable` target
   can be used for C++, `rustc_binary` for Rust, `go_binary` for Golang.
 * `resource()`: Optional named collection of data files to copy as resources
   into another GN target. These files are accessible to the binary inside the
   component's namespace.
 * `fuchsia_component()`: Collects the binary, component manifest, and additional
   resources together into a single target. This target compiles the manifest
   source into a component declaration using `cmc`.
 * `fuchsia_package()`: Unit of distribution for components. Allows one or more
   components to be hosted in a package repository and included in the target
   device's package sets. This target generates the package metadata and builds
   the Fuchsia Archive (`.far`) file.

 Packages can contain multiple components, listed as `deps` in the
 `fuchsia_package()` template. You can simplify the build file for packages
 containing only one component using the `fuchsia_package_with_single_component()`
 template.

 The following simplified `BUILD.gn` example is equivalent to to the previous
 example:

 ```gn
 {% verbatim %}
 import("//build/components.gni")

 executable("bin") {
   sources = [ "main.cc" ]
 }

 resource("my_file") {
   sources = [ "my_file.txt" ]
   outputs = [ "data/{{source_file_part}}" ]
 }

 fuchsia_package_with_single_component("hello-world") {
   manifest = "meta/hello-world.cml"
   deps = [
     ":bin",
     ":my_file",
   ]
 }
 {% endverbatim %}
 ```

 Note: For more details on the GN syntax of the component build rules, see the
 [components build reference](/docs/development/components/build.md).

 ## Exercise: Create a new component

 In this exercise, you'll build and run a basic component that reads the program
 arguments and echoes a greeting out the system log.

 To begin, create a project scaffold for a new Rust component called `echo-args`
 under the `//vendor/fuchsia-codelab` directory:

 ```posix-terminal
 fx create component --path vendor/fuchsia-codelab/echo-args --lang rust
 ```

 This creates a project directory structure with a basic component template:

 ```none {:.devsite-disable-click-to-copy}
 echo-args
   |- BUILD.gn
   |- meta
   |   |- echo_args.cml
   |
   |- src
       |- main.rs
 ```

 * `BUILD.gn`: GN build targets for the executable binaries, component, and
   package.
 * `meta/echo_args.cml`: Manifest declaring the component's executable and
   required capabilities.
 * `src/main.rs`: Source code for the Rust executable binary and unit tests.

 ### Add program arguments

 Open the `echo_args.cml` component manifest file in your editor and locate the
 `program` block. This defines the attributes of the component's executable.
 Add an `args` array to supply the list of names to greet:

 `echo-args/meta/echo_args.cml`:

 ```json5
 {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/echo/meta/echo.cml" region_tag="manifest" adjust_indentation="auto" highlight="15,16,17,18,19,21,22" %}
 ```

 ### Log the arguments

 Open the `main.rs` source file and replace the import statements with the
 following code:

 `echo-args/src/main.rs`:

 ```rust
 {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/echo/src/main.rs" region_tag="imports" adjust_indentation="auto" %}
 ```

 Replace the `main()` function with the following code:

 `echo-args/src/main.rs`:

 ```rust
 {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/echo/src/main.rs" region_tag="main" adjust_indentation="auto" %}
 ```

 <aside class="key-point">
 The <code>fuchsia::component</code> attribute removes some common boilerplate
 for component execution in Rust, such as initializing logging or async execution
 behavior.
 </aside>

 This code reads the program arguments and passes them to a function called
 `greeting()` to generate a response for the syslog entry.

 Add the following code to implement the `greeting()` function:

 `echo-args/src/main.rs`:

 ```rust
 {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/echo/src/main.rs" region_tag="greeting" adjust_indentation="auto" %}
 ```

 This function creates a simple string from the list of provided arguments based
 on the length of the list.

 <aside class="key-point">
   <b>Logging and standard streams</b>
   <p>Fuchsia has two main logging buffers; the system log (<code>syslog</code>)
   and debug log (<code>klog</code>). By default, components do not have stream
   handles for stdout and stderr available to record log messages from your code.
   Instead, you must use one of Fuchsia's logging libraries or redirect these
   streams to a Fuchsia log buffer.</p>

   <p>For more details on logging from your code, see
   <a href="/docs/development/diagnostics/logs/recording.md">Recording Logs</a>.</p>
 </aside>

 ### Add to the build configuration

 Add your new component to the build configuration:

 ```posix-terminal
 fx set workstation.qemu-x64 --with //vendor/fuchsia-codelab/echo-args
 ```

 Run `fx build` and verify that the build completes successfully:

 ```posix-terminal
 fx build
 ```

 In the next section, you'll integrate this component into the build and test the
 output in the system log.
	# Declaring components

	Every component has a declaration that describes the component's attributes and
	capabilities. For components that are distributed in packages, the declaration
	is expressed using a component manifest file and loaded with the help of a
	component resolver.

	![Diagram showing how components are declared using a "component manifest." The
	manifest is compiled by the developer tools and resolved onto the device at
	runtime.](images/component-manifest.png){: width="836"}

	You declare components using component manifest language (CML) files. At build
	time, the Component Manifest Compiler (`cmc`) tool validates and compiles the
	manifest source into a binary format (`.cm`) and stores it in the component's
	package. At runtime, component resolvers load the manifest into a
	[ComponentDecl](https://fuchsia.dev/reference/fidl/fuchsia.sys2#ComponentDecl)
	FIDL structure for [Component Manager](/docs/glossary/README.md#Component-Manager).

	## Component manifests

	CML files are JSON5 files that end with a `.cml` extension. Below is an example
	CML manifest file for a simple component running an ELF binary that prints a
	"Hello, World" message to the system log:

	```json5
	{
	// Information about the program to run.
	program: {
	// Use the built-in ELF runner.
	runner: "elf",
	// The binary to run for this component.
	binary: "bin/hello",
	// Program arguments
	args: [
	"Hello",
	"World!",
	],
	},

	// Capabilities used by this component.
	use: [
	{ protocol: "fuchsia.logger.LogSink" },
	],
	}
	```

	This file declares two main sections of information about the component:

	Note: For more details on component manifests and CML syntax, see
	[component manifests](/docs/concepts/components/v2/component_manifests.md).

	* `program`: Describes the executable information such as the binary file,
	program arguments, and the associated runtime. In this example, a binary
	written in C++ or Rust is compiled as an ELF executable and uses the built-in
	[ELF runner](/docs/concepts/components/v2/elf_runner.md).
	* `use`: Declares the capabilities this component requires to run. In this
	example, the `fuchsia.logger.LogSink` protocol enables the component to write
	messages to the system log (`syslog`).

	## Manifest shards

	Some collections of capabilities represent use case requirements that are common
	to many components in the system, such as logging. To simplify including these
	capabilities in your components, the framework abstracts them into
	manifest shards that can be included in your CML source file.

	Below is an equivalent CML to the previous example. In this case, the necessary
	logging capabilities are provided by including
	`diagnostics/syslog/client.shard.cml` instead of declaring
	`fuchsia.logger.LogSink` explicitly:

	```json5
	{
	include: [ "syslog/client.shard.cml" ],

	// Information about the program to run.
	program: {
	// Use the built-in ELF runner.
	runner: "elf",
	// The binary to run for this component.
	binary: "bin/hello-world",
	// Program arguments
	args: [
	"Hello",
	"World!",
	],
	},
	}
	```

	<aside class="key-point">
	To review the merged CML output with all includes resolved, run the
	<code>fx cmc include</code> command with your manifest. For more details, see
	the <a href="/docs/reference/tools/sdk/cmc.md"> reference documentation</a>.
	</aside>

	## Building components

	The Fuchsia build system provides templates as GN imports in
	[`//build/components.gni`](/build/components.gni) to build and package software
	into Fuchsia components. Below is an example of a `BUILD.gn` file for a simple
	C++ component:

	```gn
	{% verbatim %}
	import("//build/components.gni")

	executable("bin") {
	sources = [ "main.cc" ]
	}

	resource("my_file") {
	sources = [ "my_file.txt" ]
	outputs = [ "data/{{source_file_part}}" ]
	}

	fuchsia_component("hello-world-component") {
	component_name = "hello-world"
	deps = [
	":bin",
	":my_file",
	]
	manifest = "meta/hello-world.cml"
	}

	fuchsia_package("hello-world") {
	package-name = "hello-world"
	deps = [
	":hello-world-component",
	]
	}
	{% endverbatim %}
	```

	This file contains the following main elements:

	* `executable()`: Compiles the source code into a binary. This target varies
	depending on the programming language. For example, an `executable` target
	can be used for C++, `rustc_binary` for Rust, `go_binary` for Golang.
	* `resource()`: Optional named collection of data files to copy as resources
	into another GN target. These files are accessible to the binary inside the
	component's namespace.
	* `fuchsia_component()`: Collects the binary, component manifest, and additional
	resources together into a single target. This target compiles the manifest
	source into a component declaration using `cmc`.
	* `fuchsia_package()`: Unit of distribution for components. Allows one or more
	components to be hosted in a package repository and included in the target
	device's package sets. This target generates the package metadata and builds
	the Fuchsia Archive (`.far`) file.

	Packages can contain multiple components, listed as `deps` in the
	`fuchsia_package()` template. You can simplify the build file for packages
	containing only one component using the `fuchsia_package_with_single_component()`
	template.

	The following simplified `BUILD.gn` example is equivalent to to the previous
	example:

	```gn
	{% verbatim %}
	import("//build/components.gni")

	executable("bin") {
	sources = [ "main.cc" ]
	}

	resource("my_file") {
	sources = [ "my_file.txt" ]
	outputs = [ "data/{{source_file_part}}" ]
	}

	fuchsia_package_with_single_component("hello-world") {
	manifest = "meta/hello-world.cml"
	deps = [
	":bin",
	":my_file",
	]
	}
	{% endverbatim %}
	```

	Note: For more details on the GN syntax of the component build rules, see the
	[components build reference](/docs/development/components/build.md).

	## Exercise: Create a new component

	In this exercise, you'll build and run a basic component that reads the program
	arguments and echoes a greeting out the system log.

	To begin, create a project scaffold for a new Rust component called `echo-args`
	under the `//vendor/fuchsia-codelab` directory:

	```posix-terminal
	fx create component --path vendor/fuchsia-codelab/echo-args --lang rust
	```

	This creates a project directory structure with a basic component template:

	```none {:.devsite-disable-click-to-copy}
	echo-args
	\|- BUILD.gn
	\|- meta
	\| \|- echo_args.cml
	\|
	\|- src
	\|- main.rs
	```

	* `BUILD.gn`: GN build targets for the executable binaries, component, and
	package.
	* `meta/echo_args.cml`: Manifest declaring the component's executable and
	required capabilities.
	* `src/main.rs`: Source code for the Rust executable binary and unit tests.

	### Add program arguments

	Open the `echo_args.cml` component manifest file in your editor and locate the
	`program` block. This defines the attributes of the component's executable.
	Add an `args` array to supply the list of names to greet:

	`echo-args/meta/echo_args.cml`:

	```json5
	{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/echo/meta/echo.cml" region_tag="manifest" adjust_indentation="auto" highlight="15,16,17,18,19,21,22" %}
	```

	### Log the arguments

	Open the `main.rs` source file and replace the import statements with the
	following code:

	`echo-args/src/main.rs`:

	```rust
	{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/echo/src/main.rs" region_tag="imports" adjust_indentation="auto" %}
	```

	Replace the `main()` function with the following code:

	`echo-args/src/main.rs`:

	```rust
	{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/echo/src/main.rs" region_tag="main" adjust_indentation="auto" %}
	```

	<aside class="key-point">
	The <code>fuchsia::component</code> attribute removes some common boilerplate
	for component execution in Rust, such as initializing logging or async execution
	behavior.
	</aside>

	This code reads the program arguments and passes them to a function called
	`greeting()` to generate a response for the syslog entry.

	Add the following code to implement the `greeting()` function:

	`echo-args/src/main.rs`:

	```rust
	{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/echo/src/main.rs" region_tag="greeting" adjust_indentation="auto" %}
	```

	This function creates a simple string from the list of provided arguments based
	on the length of the list.

	<aside class="key-point">
	<b>Logging and standard streams</b>
	<p>Fuchsia has two main logging buffers; the system log (<code>syslog</code>)
	and debug log (<code>klog</code>). By default, components do not have stream
	handles for stdout and stderr available to record log messages from your code.
	Instead, you must use one of Fuchsia's logging libraries or redirect these
	streams to a Fuchsia log buffer.</p>

	<p>For more details on logging from your code, see
	<a href="/docs/development/diagnostics/logs/recording.md">Recording Logs</a>.</p>
	</aside>

	### Add to the build configuration

	Add your new component to the build configuration:

	```posix-terminal
	fx set workstation.qemu-x64 --with //vendor/fuchsia-codelab/echo-args
	```

	Run `fx build` and verify that the build completes successfully:

	```posix-terminal
	fx build
	```

	In the next section, you'll integrate this component into the build and test the
	output in the system log.