blob: 664e440d79720f162fd5bfe2772256fcfa880ed7 [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_component.gni")
import("fuchsia_package.gni")
# Defines a package that contains a single component.
# See: https://fuchsia.dev/fuchsia-src/development/components/build
#
# Developers often define a package that contains a single component.
# This template fuses together fuchsia_package() and fuchsia_component() as a
# convenience.
#
# Packages are units of distribution. It is beneficial to define multiple
# components in the same package if you need to guarantee that several
# components are always co-present, or if you'd like to be able to update
# several components at once (by updating a single package).
# This pattern is also commonly used to create hermetic integration tests.
# For instance an integration test between two components where one is a client
# of a service implemented in another component would include both the client
# and server components.
# However for the sake of simplicity, if you're developing a package with just
# a single component then this template will save you some boilerplate.
#
# Example:
# ```
# executable("rot13_encoder_decoder") {
# sources = [ "rot13_encoder_decoder.cc" ]
# }
#
# fuchsia_package_with_single_component("rot13") {
# manifest = "meta/rot13.cmx"
# deps = [ ":rot13_encoder_decoder" ]
# }
# ```
#
# Parameters
#
# package_name (optional)
# The name of the package.
# Type: string
# Default: target_name
#
# component_name (optional)
# The name of the component.
# Type: string
# Default: package_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: []
#
# 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
#
# subpackages (optional)
# A list of `fuchsia_package` targets. Each target is converted into the
# equivalent of a `renameable_targets` entry with its `package` property set
# to the target, and no `name` override. All included `package` entries will
# be added as `deps` of the generated meta file, and do not need to be
# listed as additional `deps` of the `fuchsia_package` target.
# Subpackage names must be unique (relative to the containing package), but
# both `renameable_subpackages` and `subpackages` may be included,
# additively.
# Type: list of targets
#
# renameable_subpackages (optional)
# A list of subpackages defined by scoped variables `package` and an
# optional `name`. If `name` is omitted, the subpackage target's package
# name is used by default. The generated package will include a
# `subpackages` meta file that declares dependencies on the listed packages,
# using the current package hash of each package. All included `package`
# entries will be added as `deps` of the generated meta file, and do not
# need to be listed as additional `deps` of the `fuchsia_package` target.
# Subpackage names must be unique (relative to the containing package), but
# both `renameable_subpackages` and `subpackages` may be included,
# additively.
# Type: list of scopes
#
# 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_single_component") {
package_name = target_name
if (defined(invoker.package_name)) {
package_name = invoker.package_name
}
component_name = package_name
if (defined(invoker.component_name)) {
component_name = invoker.component_name
}
component_target = "${target_name}_component"
fuchsia_component(component_target) {
forward_variables_from(invoker,
[
"deps",
"data_deps",
"manifest",
"manifest_deps",
"restricted_features",
"check_includes",
"check_references",
"experimental_force_runner",
"cm_label",
"testonly",
])
if (!defined(deps)) {
deps = []
}
if (defined(invoker.shell_commands)) {
deps += invoker.shell_commands
}
component_name = component_name
visibility = [ ":*" ]
}
fuchsia_package(target_name) {
forward_variables_from(invoker,
[
"is_shell_package",
"shell_commands",
"disable_elf_binaries_checks",
"validate_structured_config",
"repository",
"renameable_subpackages",
"subpackages",
"testonly",
"visibility",
])
package_name = package_name
deps = [ ":$component_target" ]
}
}