build/assembly/kernel_aib.gni

# Copyright 2023 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/assembly/assembly_input_bundle_archive.gni")
import("//build/assembly/assembly_input_bundle_package.gni")
import("//build/bazel/bazel_inputs.gni")
import("//build/info/info.gni")
import("//build/python/python_action.gni")

# Creates an Assembly Input Bundle for the kernel.
#
# This is a specialized template that is only used once, to define the AIB that
# includes the kernel image itself.
#
# For the standard (build-defined) kernel at //zircon/kernel, use this without
# any additional parameters.
#
# The following parameters are for when this template is being used to create a
# platform AIB for a non-standard kernel image (such as the "cuckoo" boot-test
# images).
#
# Parameters:
#
#   kernel_zbi (optional; default: "//zircon/kernel")
#     [label] Label of the zircon kernel to use.  This needs to use the `images`
#     metadata key to provide the `path` and `name` fields (see the
#     build_api_module("images")` in `//BUILD.gn`).  The default value is most likely
#     the correct one.  This should only be overridden in special circumstances.
#
#   kernel_image_name (optional; default: "kernel")
#     [string] The image name of the 'kernel_zbi' as seen in images.json. This is used
#     as an override, that in conjunction with 'kernel_zbi' allows selecting a custom zbi
#     image as the kernel zbi.
#
#   bundle_name [optional; default: legacy]
#     [string] A different name for the bundle, if not the name of the target.
#
#   bundles_dir [optional; default: target_out_dir]
#     [GN file path] path to a dir to use instead of $target_out_dir as the
#     parent of the legacy input bundle.
#
#  create_aib_package (optional; default: true)
#    [boolean] Set to true to also create a package that contains the contents
#    of the AIB.
#      target: '{$target_name}.pkg'
#      outputs: [
#                 '${bundle_dir}/${bundle_name}.pkg/meta.far',
#                 '${bundle_dir}/${bundle_name}.pkg/package_manifest.json',
#               ]
#
#  create_aib_archive (optional; default: true)
#    [boolean] Set to true to create a tgz archive that contains the contents of
#    the AIB.
#      target: '{$target_name}.tgz'
#      outputs: [ '${bundle_dir}/${bundle_name}.tgz' ]
#
#
#  Outputs
#    A directory structure and manifest that matches that documented in
#    //build/python/modules/assembly/assembly_input_bundle.py.
#
#   manifest path:
#   $target_out_dir/$target_name/assembly_config.json
#
template("kernel_assembly_input_bundle") {
  forward_variables_from(invoker,
                         [
                           "bundles_dir",
                           "bundle_name",
                           "create_aib_package",
                           "create_aib_archive",
                           "kernel_zbi",
                           "kernel_image_name",
                         ])

  if (!defined(kernel_zbi)) {
    # Default to the canonical kernel target.
    kernel_zbi = "//zircon/kernel"
  }

  if (!defined(kernel_image_name)) {
    kernel_image_name = "kernel"
  }

  if (!defined(bundles_dir)) {
    bundles_dir = target_out_dir
  }

  if (!defined(bundle_name)) {
    bundle_name = target_name
  }

  if (!defined(create_aib_package)) {
    create_aib_package = true
  }
  if (!defined(create_aib_archive)) {
    create_aib_archive = true
  }

  labels = {
    # The AIB itself
    assembly_input_bundle = "$target_name.bundle"

    # The assembly bundle package and archive labels
    assembly_input_bundle_package = "${target_name}.pkg"
    assembly_input_bundle_archive = "${target_name}.tgz"

    bazel_inputs = "${target_name}_bazel_inputs"

    kernel_image_metadata = "${target_name}_kernel_image_metadata"
  }

  files = {
    kernel_image_metadata =
        "$target_out_dir/${target_name}_kernel_image.gn_meta.json"

    # Outputs

    # The directory where all the bundle contents are written to
    assembly_input_bundle_dir = "${bundles_dir}/${bundle_name}"

    # The "official" outputs file that we create in that directory
    assembly_input_bundle_config =
        "${assembly_input_bundle_dir}/assembly_config.json"

    # The manifest of all files in the AIB, used to create pkgs and archives.
    assembly_input_bundle_manifest =
        "${assembly_input_bundle_dir}.fini_manifest"

    # The AIB package's meta.far (optionally used)
    assembly_input_bundle_package_metafar =
        "${assembly_input_bundle_dir}.pkg/meta.far"

    # The AIB archive and the manifest used to create it (optionally used)
    assembly_input_bundle_archive = "${assembly_input_bundle_dir}.tgz"
    assembly_input_bundle_archive_manifest =
        "${assembly_input_bundle_dir}.tgz.fini_manifest"
  }

  # Write the kernel image metadata to a file, as this is the only way to get
  # the path to the kernel ZBI.
  generated_file(labels.kernel_image_metadata) {
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "visibility",
                           ])

    data_keys = [ "images" ]
    walk_keys = [ "images_barrier" ]
    outputs = [ files.kernel_image_metadata ]
    output_conversion = "json"
    deps = [ kernel_zbi ]
  }

  python_action(labels.assembly_input_bundle) {
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "visibility",
                           ])

    binary_label = "//build/assembly/scripts:kernel_aib_tool"

    outputs = [ files.assembly_input_bundle_config ]
    args = [
      "--kernel-image-metadata",
      rebase_path(files.kernel_image_metadata, root_build_dir),
      "--kernel-image-name",
      kernel_image_name,
      "--outdir",
      rebase_path(files.assembly_input_bundle_dir, root_build_dir),
    ]

    # If packaging or archiving the AIB, write out the fini manifest needed to
    # do so.
    if (create_aib_package || create_aib_archive) {
      args += [
        "--export-manifest",
        rebase_path(files.assembly_input_bundle_manifest, root_build_dir),
      ]
      outputs += [ files.assembly_input_bundle_manifest ]
    }

    inputs = [ files.kernel_image_metadata ]
    deps = [ ":${labels.kernel_image_metadata}" ]

    metadata = {
      images_barrier = []
    }
  }

  # Optionally create the fuchsia-pkg for the AIB.
  if (create_aib_package) {
    assembly_input_bundle_package(labels.assembly_input_bundle_package) {
      forward_variables_from(invoker,
                             [
                               "testonly",
                               "visibility",
                             ])
      package_name = bundle_name
      package_outdir = "${bundles_dir}/${bundle_name}.pkg"
      manifest = files.assembly_input_bundle_manifest
      deps = [ ":${labels.assembly_input_bundle}" ]
    }
  }

  # Optionally create the archive for the AIB.
  if (create_aib_archive) {
    assembly_input_bundle_archive(labels.assembly_input_bundle_archive) {
      forward_variables_from(invoker,
                             [
                               "testonly",
                               "visibility",
                             ])
      archive_name = bundle_name
      archive_outdir = bundles_dir
      manifest = files.assembly_input_bundle_manifest
      deps = [ ":${labels.assembly_input_bundle}" ]

      # If the package was created, include it in the archive.
      if (create_aib_package) {
        meta_far = files.assembly_input_bundle_package_metafar
        deps += [ ":${labels.assembly_input_bundle_package}" ]
      }
    }
  }

  # Make generated AIBs available to Bazel builds.
  bazel_input_resource_directory(labels.bazel_inputs) {
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "visibility",
                           ])
    source_dir = files.assembly_input_bundle_dir
    dest_dir = rebase_path(files.assembly_input_bundle_dir, root_out_dir)
    deps = [ ":${labels.assembly_input_bundle}" ]
  }

  group(target_name) {
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "visibility",
                           ])
    deps = [ ":${labels.bazel_inputs}" ]
    public_deps = [ ":${labels.assembly_input_bundle}" ]
    if (create_aib_package) {
      public_deps += [ ":${labels.assembly_input_bundle_package}" ]
    }
    if (create_aib_archive) {
      public_deps += [ ":${labels.assembly_input_bundle_archive}" ]
    }
  }
}