blob: aa900c4b417243b1e0236d1a850a79d7281f9b03 [file] [log] [blame]
# Copyright 2020 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
import("fuchsia_package_with_single_component.gni")
# Defines a package that contains a single component with the default component
# manifest path: `default.cm`. See:
# https://fuchsia.dev/fuchsia-src/development/components/build
#
# Developers often define a package that contains a single component. This often
# results in a component URL that requires two names (the package name and the
# component name) to bundle a single software capability; for example:
#
# ```
# fuchsia-pkg://fuchsia.com/echo_server#meta/echo_server.cm
# ```
#
# To establish a convention, this template renames the component manifest
# `default.cm`, so a user of this packaged component only needs to know the
# package name, and can infer the component name if not explicitly provided.
#
# When using subpackages, separating components into independent packages is
# convenient, and encouraged for stronger software encapsulation. Hermetic
# tests can also be constructed as a test component with subpackaged component
# dependencies.
#
# Note that a package with a `default.cm` component does not imply the package
# contains no other components. Packages can define multiple components in the
# same package using the `fuchsia_component()` and `fuchsia_package()`
# templates, and within a multiple-component package, one of those components
# can still be designated as that packages "default" component, by giving the
# default component the `default.cm` manifest name.
#
# Example:
# ```
# executable("rot13_encoder_decoder") {
# sources = [ "rot13_encoder_decoder.cc" ]
# }
#
# fuchsia_package_with_default_component("rot13") {
# manifest = "meta/rot13.cml"
# deps = [ ":rot13_encoder_decoder" ]
# }
# ```
#
# The resulting absolute component URL would be something similar to:
#
# ```
# fuchsia-pkg://fuchsia.com/rot13#meta/default.cm
# ```
#
# As a relative subpackaged component URL, the component reference would
# typically be:
#
# ```
# rot13#meta/default.cm
# ```
#
# Parameters
#
# package_name (optional)
# The name of the package.
# Type: string
# Default: target_name
#
# manifest (must specify either manifest or cm_label)
# The component manifest.
# Type: path
#
# cm_label (must specify either manifest or cm_label)
# Use label of a fuchsia_component_manifest target instead of supplying the manifest source.
# Type: string, GN label e.g. `:my-manifest`
#
# restricted_features (optional)
# The set of restricted CML features to allow.
# The set of features is allowlisted here: //tools/cmc/build/restricted_features/BUILD.gn
# where each feature name is represented by a group of the same name.
# Type: list of strings
# Default: []
#
# renameable_subpackages (optional)
# A list of subpackages defined by scoped variables `package` (a
# `fuchsia_package()` target) and an optional `name`. See
# `fuchsia_package()` for more details.
# Type: list of scopes
#
# subpackages (optional)
# A list of `fuchsia_package` targets. See `fuchsia_package()` for more
# details.
# Type: list of targets
#
# check_includes (optional)
# Check against expect_includes() in deps.
# Warning: Do not disable this unless there is a good, documented reason.
# Type: boolean
# Default: true
#
# check_references (optional)
# Check component manifest references (e.g. "program.binary") against
# package manifest.
# Type: boolean
# Default: true
#
# experimental_force_runner (optional)
# Set the --experimental-force-runner flag to the given value.
# This flag is experimental and may be removed without warning.
# Type: string
#
# manifest_deps (optional)
# Dependencies for the component's manifest, in case it is generated by another target.
# Type: list of targets
#
# disable_elf_binaries_checks (optional)
# Set to true to disable ELF binaries verification checks. Useful
# if your package includes non-Fuchsia ELF binaries, or if some
# of them are unstripped.
# Type: boolean
# Default: false
#
# validate_structured_config (optional)
# If true, check that component manifests which declare config schemas have been
# packaged with the resources needed to resolve them at runtime. Only useful for
# those packages which fully generate their configuration during the build. If a
# component has configuration provided by assembly tooling, that happens after the
# package is built and this should be set to false to prevent spurious errors.
# Type: boolean
# Default: true
#
# repository (optional)
# The repository host name part of the package URL. Defaults to "fuchsia.com".
# See https://fuchsia.dev/fuchsia-src/concepts/packages/package_url#repository
# for more details.
# Type: string
# Default: fuchsia.com
#
# shell_commands (optional)
# An explicit list of dependencies included as part of the fuchsia package invocation that are
# shell command dependencies to include in the shell command distribution manifest and it's
# subsequent metadata walk
#
# is_shell_package (optional)
# Used internally to implement fuchsia_shell_package(). Use with caution, as this flag marks
# all the package's binaries as shell commands and includes them in the shell_commands package
# during the generation of the legacy_assembly_input_bundle
#
# data_deps
# deps
# testonly
# visibility
template("fuchsia_package_with_default_component") {
component_name = "default"
fuchsia_package_with_single_component(target_name) {
forward_variables_from(invoker,
[
"component_name",
"data_deps",
"deps",
"manifest",
"manifest_deps",
"restricted_features",
"check_includes",
"check_references",
"experimental_force_runner",
"cm_label",
"package_name",
"is_shell_package",
"shell_commands",
"disable_elf_binaries_checks",
"validate_structured_config",
"repository",
"renameable_subpackages",
"subpackages",
"testonly",
"visibility",
])
}
}