build/components/fuchsia_package_with_default_component.gni

# 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. Only applicable to v2 components.
#     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",
                           ])
  }
}