# 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("//build/dist/fini_manifest.gni")
import("//build/dist/generated_resource.gni")
import("//build/images/args.gni")
import("//src/sys/pkg/bin/pm/pm.gni")
import("//tools/cmc/build/validate_component_manifest_references.gni")

# Defines a Fuchsia package.
# See: https://fuchsia.dev/fuchsia-src/development/components/build
#
# Fuchsia packages are a collection of any number of files (or resources), each
# with a unique path that is relative to the package's root.
# Package targets collect resources via their dependencies. These dependencies
# are typically fuchsia_component() targets, which provide their component
# manifest and other files that the component needs (such as an executable).
#
# Packages can be defined as a collection of pairs each representing a file in
# the package. Each pair consists of the path in the package that is assigned
# to the file, and a path relative to the build system's output directory where
# the contents of the file will be sourced from.
# This mapping is generated at build time, and is known as the package
# manifest.
#
# To view the package manifest, For instance assume you have defined
# a package at `path/to/project:my_package` and built it:
# ```
# $ fx build path/to/project:my_package
# ```
# You can then find the path to the generated manifest:
# ```
# $ fx gn outputs out/default path/to/project:my_package_manifest
# ```
#
# The package name is defined by the target name.
# Some rules apply to package names.
# See: https://fuchsia.dev/fuchsia-src/concepts/packages/package_url#package-name
#
# It's recommended for a package to depend on one or more `fuchsia_component()`
# targets. Typically no other dependencies are required.
#
# Example:
# ```
# fuchsia_package("my-package") {
#   deps = [
#     ":first_component",
#     ":second_component",
#   ]
# }
# ```
#
# Parameters
#
#   package_name (optional)
#     The name of the package.
#     Type: string
#     Default: target_name
#
#   deps
#   testonly
#   visibility
template("fuchsia_package") {
  package_name = target_name
  if (defined(invoker.package_name)) {
    package_name = invoker.package_name
  }
  assert(string_replace(package_name, "_", "-") == package_name,
         "fuchsia_package($target_name): must not have underscores in " +
             "`package_name`")

  # Generate the "meta/package" file
  meta_package_target = "${target_name}_meta_package"
  generated_resource(meta_package_target) {
    contents = "{\"name\":\"$package_name\",\"version\":\"0\"}"
    outputs = [ "meta/package" ]
    output_conversion = "string"
    visibility = [ ":*" ]
  }

  # Generate package manifest
  package_manifest_target = "${target_name}_manifest"
  package_manifest_file = "$target_out_dir/${target_name}_manifest"
  fini_manifest(package_manifest_target) {
    forward_variables_from(invoker,
                           [
                             "deps",
                             "testonly",
                           ])
    if (!defined(deps)) {
      deps = []
    }
    deps += [ ":$meta_package_target" ]
    visibility = [ ":*" ]
    outputs = [ package_manifest_file ]
  }

  # Validate component manifests against package manifest
  component_manifests_target = "${target_name}_component_manifests"
  component_manifests_rspfile =
      "$target_out_dir/${target_name}_component_manifests"
  generated_file(component_manifests_target) {
    forward_variables_from(invoker,
                           [
                             "deps",
                             "testonly",
                           ])
    visibility = [ ":*" ]
    data_keys = [ "component_manifests" ]
    walk_keys = [ "component_manifests_barrier" ]
    outputs = [ component_manifests_rspfile ]
  }

  validate_target = "${target_name}_validate_manifests"
  validate_component_manifest_references(validate_target) {
    forward_variables_from(invoker, [ "testonly" ])
    deps = [
      ":$component_manifests_target",
      ":$package_manifest_target",
    ]
    visibility = [ ":*" ]
    package_manifest = package_manifest_file
    component_manifests_rspfile = component_manifests_rspfile
  }

  # Build package
  pm_build(target_name) {
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "visibility",
                           ])
    manifest = ":$package_manifest_target"
    deps = [ ":$validate_target" ]
    metadata = {
      # Add barriers so that the contents of this package do not get
      # accidentally picked up by other packages via improper dependencies.
      component_manifests_barrier = []
      if (!bootfs_only) {
        # If the bringup configuration is being built, the contents need to be
        # exposed to other containers.
        # See fxbug.dev/45680 for more information.
        distribution_entries_barrier = []
      }
    }
  }
}