build/assembly/assembly_input_bundle.gni - fuchsia - Git at Google

 # Copyright 2021 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/bazel/bazel_inputs.gni")
 import("//build/python/python_action.gni")
 import("//src/sys/pkg/bin/pm/pm.gni")

 # Creates a Fuchsia Package for an Assembly Input Bundle.  For the format
 # of the created package, see the AssemblyInputBundle documentation at:
 #  //build/python/modules/assembly/assembly_input_bundle.py
 #
 # Parameters
 #
 #   manifest
 #     [path] The path to the FINI manifest created by the assembly input bundle
 #
 #   package_name (optional; default: target_name)
 #     [string] The name of the package, if not $target_name
 #
 #   package_outdir (optional; default: target_out_dir)
 #     [path] A different directory to write the bundle into, if not to write it
 #     to '$target_out_dir/$bundle_name'.
 #
 # GN usual meanings
 #   deps, testonly, visibility
 #
 template("assembly_input_bundle_package") {
   assert(defined(invoker.manifest),
          "A manifest path must be specified: " +
              get_label_info(target_name, "label_with_toolchain"))

   package_outdir = target_out_dir
   if (defined(invoker.package_outdir)) {
     package_outdir = invoker.package_outdir
   }

   package_name = target_name
   if (defined(invoker.bundle_name)) {
     package_name = invoker.package_name
   }

   labels = {
     package_manifest_creation = "${target_name}.creation_manifest.fini"
     package = target_name
   }

   files = {
     meta_package_file = "$package_outdir/meta_package"
     creation_manifest = "$package_outdir/creation_manifest.fini"
   }

   # Build a package PackageBuildManifest that includes the contents in
   # |invoker.manifest| and a generated meta/package file.
   python_action(labels.package_manifest_creation) {
     forward_variables_from(invoker,
                            [
                              "deps",
                              "testonly",
                            ])
     visibility = [ ":${labels.package}" ]
     binary_label = "//build/assembly/scripts:assembly_input_bundle_tool"
     inputs = [ invoker.manifest ]
     outputs = [
       files.creation_manifest,  # must be the first output, for passing to
                                 # pm_build
       files.meta_package_file,
     ]
     args = [
       "generate-package-creation-manifest",
       "--name",
       package_name,
       "--contents-manifest",
       rebase_path(invoker.manifest, root_build_dir),
       "--meta-package",
       rebase_path(files.meta_package_file, root_build_dir),
       "--output",
       rebase_path(files.creation_manifest, root_build_dir),
     ]
   }

   pm_build(target_name) {
     forward_variables_from(invoker,
                            [
                              "deps",
                              "testonly",
                              "visibility",
                            ])
     package_name = package_name
     package_out_dir = package_outdir
     manifest = ":${labels.package_manifest_creation}"
     metadata = {
       if (defined(invoker.metadata)) {
         forward_variables_from(invoker.metadata, "*")
       }

       # These are a bunch of barriers to make sure that if this target gets
       # included anywhere, it's dependencies don't end up getting gathered
       # in metadata walks.
       distribution_entries_barrier = []
       package_barrier = []
       assembly_package_barrier = []
       driver_package_barrier = []
       system_image_package_barrier = []
       system_image_extra_package_manifest_barrier = []
       test_component_manifest_barrier = []
       test_component_manifest_program_barrier = []
     }
   }
 }

 # Creates an archive for the Fuchsia Package for an Assembly Input Bundle.
 #
 # This is a tgz that contains the entire contents of the AIB, including the
 # meta.far file as well.  See the AssemblyInputBundle documentation at:
 #  //build/python/modules/assembly/assembly_input_bundle.py
 #
 # Parameters
 #
 #   archive_name (optional; default: target_name)
 #     [string] A different name for the archive, if not the name of the target.
 #
 #   archive_outdir (optional; default: target_out_dir)
 #     [path] A different directory to write the archive into.
 #
 #   manifest
 #     [path] The path to the FINI manifest created for the
 #     assembly input bundle
 #
 #   meta_far
 #     [path] The path to the meta far created for the assembly input bundle's package
 #
 template("assembly_input_bundle_archive") {
   assert(defined(invoker.manifest),
          "A manifest path must be specified: " +
              get_label_info(target_name, "label_with_toolchain"))

   archive_outdir = target_out_dir
   if (defined(invoker.archive_outdir)) {
     archive_outdir = invoker.archive_outdir
   }

   archive_name = target_name
   if (defined(invoker.archive_name)) {
     archive_name = invoker.archive_name
   }

   labels = {
     tarmaker = "//build/tools/tarmaker($host_toolchain)"
   }

   files = {
     tarmaker = host_out_dir + "/tarmaker"

     archive = "${archive_outdir}/${archive_name}.tgz"
     archive_creation_manifest = "${archive}.creation_manifest.fini"
     depfile = "${archive}.d"
   }

   python_action(target_name) {
     forward_variables_from(invoker,
                            [
                              "testonly",
                              "visibility",
                            ])
     binary_label = "//build/assembly/scripts:assembly_input_bundle_tool"
     inputs = [
       invoker.manifest,
       files.tarmaker,
     ]
     outputs = [
       files.archive,
       files.archive_creation_manifest,
     ]
     depfile = files.depfile
     args = [
       "generate-archive",
       "--tarmaker",
       rebase_path(files.tarmaker, root_build_dir),
       "--contents-manifest",
       rebase_path(invoker.manifest, root_build_dir),
       "--creation-manifest",
       rebase_path(files.archive_creation_manifest, root_build_dir),
       "--output",
       rebase_path(files.archive, root_build_dir),
       "--depfile",
       rebase_path(files.depfile, root_build_dir),
     ]
     deps = [ labels.tarmaker ]
     if (defined(invoker.deps)) {
       deps += invoker.deps
     }
     if (defined(invoker.meta_far)) {
       args += [
         "--meta-far",
         rebase_path(invoker.meta_far, root_build_dir),
       ]
     }
     metadata = {
       assembly_input_archives = [
         {
           path = rebase_path(files.archive, root_build_dir)
           label = get_label_info(":$target_name", "label_with_toolchain")
         },
       ]
     }
   }
 }

 # Creates an Assembly Input Bundle from sets of deps.
 #
 # NOTE: This is not yet able to support all categories of inputs that are in an
 #       AIB.  That support will be added in future CLs.  See the parameters
 #       below for the categories that are currently supported.
 #
 # NOTE: This template DOES NOT use GN metadata, all labels for packages must be
 # the actual target that creates the package.
 #
 # Parameters
 #
 #  bundle_name (optional; default: target_name)
 #    [string] A different name for the bundle, if not the name of the target.
 #
 #  bundle_dir (optional; default: target_out_dir)
 #    [path] A different directory to write the bundle into, if not to write it
 #    to '$target_out_dir/$bundle_name'.
 #
 #  base_packages [optional]
 #    [list, GN labels] A list of GN labels of fuchsia_package targets to
 #    include in the base package set.
 #
 #    Note: These are direct labels for specific targets, not deps to walk for
 #    metadata.  If the target isn't a package target, it will cause an error
 #    like:
 #      "no dependency provides the input <package_name>/package_manifest.json"
 #
 #   base_driver_packages (optional)
 #     [list, GN scopes] A list of GN scopes that hold the driver packages to
 #     include in the base package set. Packages listed here should not be
 #     listed in the base_packages and will be included automatically in
 #     the base package set as driver packages. The scope must have a
 #     `package_target` field pointing to the GN target of the fuchsia_package,
 #     and `driver_components` field containing a list of relative paths to
 #     driver components provided by the package, e.g. "meta/driver.cm"
 #
 #  cache_packages [optional]
 #    [list, GN labels] A list of GN labels of fuchsia_package targets to
 #    include in the cache package set.
 #
 #  bootfs_packages [optional]
 #    [list, GN labels] A list of GN labels of fuchsia_package targets to
 #    include in the bootfs package set.
 #
 #    Note: These are direct labels for specific targets, not deps to walk for
 #    metadata.  If the target isn't a package target, it will cause an error
 #    like:
 #      "no dependency provides the input <package_name>/package_manifest.json"
 #
 #  qemu_kernel (optional; default: false)
 #    [path] Path to the qemu kernel.
 #
 #  create_aib_package (optional; default: false)
 #    [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: false)
 #    [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
 #
 #
 # GN usual meanings
 #  testonly, visibility
 template("assembly_input_bundle") {
   bundles_dir = target_out_dir
   if (defined(invoker.bundles_dir)) {
     bundles_dir = invoker.bundles_dir
   }

   bundle_name = target_name
   if (defined(invoker.bundle_name)) {
     bundle_name = invoker.bundle_name
   }

   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"
   }

   files = {
     # 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 files that we create as book-keeping between our tasks.
     assembly_input_bundle_depfile = "${assembly_input_bundle_dir}.d"

     # 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"
   }

   create_aib_package =
       defined(invoker.create_aib_package) && invoker.create_aib_package
   create_aib_archive =
       defined(invoker.create_aib_archive) && invoker.create_aib_archive

   creation_args = []
   creation_inputs = []
   creation_deps = []
   if (defined(invoker.deps)) {
     creation_deps += invoker.deps
   }

   # Convert each set of package targets into:
   #  1) a set of manifests paths in a file
   #  2) add that file as an input and argument to the AIB creation action
   #  3) add the target labels as dependencies of the AIB creation action

   # This defines a set of package sets that can be looped over by name to find
   # process.  This use of defined() and the invoker is to tolerate undefined,
   # optional, parameters to the template, as `invoker[name]` is not supported
   # with defined
   package_sets = {
     base = []
     if (defined(invoker.base_packages)) {
       foreach(_target, invoker.base_packages) {
         base += [
           {
             package_target = _target
           },
         ]
       }
     }
     cache = []
     if (defined(invoker.cache_packages)) {
       foreach(_target, invoker.cache_packages) {
         cache += [
           {
             package_target = _target
           },
         ]
       }
     }
     bootfs = []
     if (defined(invoker.bootfs_packages)) {
       foreach(_target, invoker.bootfs_packages) {
         bootfs += [
           {
             package_target = _target
           },
         ]
       }
     }

     drivers = []
     if (defined(invoker.base_driver_packages)) {
       drivers = invoker.base_driver_packages
     }
   }

   # Loop over the above sets of packages
   foreach(set_name,
           [
             "base",
             "cache",
             "drivers",
             "bootfs",
           ]) {
     _package_target_details = package_sets[set_name]
     _package_targets = []
     _manifest_entries = []

     # Skip empty package sets
     if (_package_target_details != []) {
       # 1a) Calculate the manifest path for each package target
       foreach(details, _package_target_details) {
         assert(
             defined(details.package_target),
             "A target must be defined for each package. (this should be unreachable)")
         _package_targets += [ details.package_target ]
         _package_out_dir =
             get_label_info(details.package_target, "target_out_dir")
         _package_name = get_label_info(details.package_target, "name")
         _manifest_path =
             "${_package_out_dir}/${_package_name}/package_manifest.json"
         _manifest_path_rebased = rebase_path(_manifest_path, root_build_dir)

         if (set_name == "drivers") {
           assert(defined(details.driver_components),
                  "driver_components must be specified for driver targets")
           _manifest_entries += [
             {
               package_target = _manifest_path_rebased
               driver_components = details.driver_components
             },
           ]
         } else {
           _manifest_entries += [ _manifest_path_rebased ]
         }
       }

       _manifest_list = "${target_name}.${set_name}_packages.list"
       _manifest_list_file = "${target_gen_dir}/${_manifest_list}"

       # 1b) Generate a file containing that list
       # For base packages this will be a list of package manifests.
       # For drivers, this will be a list of DriverDetails, containing
       # the package manifests and component file paths.
       generated_file(_manifest_list) {
         forward_variables_from(invoker, [ "testonly" ])
         deps = _package_targets
         outputs = [ "${_manifest_list_file}" ]
         output_conversion = "json"
         contents = _manifest_entries
       }

       # 2) add the file as an input and argument to the AIB creation action
       creation_args += [
         "--${set_name}-pkg-list",
         rebase_path(_manifest_list_file, root_build_dir),
       ]
       creation_inputs += [ _manifest_list_file ]

       # 3) add the file as a dependency of the AIB creation action (linking the
       #    actual package deps transitively, to preserve the route by which they
       #    are added to the AIB:
       #      AIB
       #       +-> AIB.base_packages_list
       #            +-> [ base package deps ]
       #       +-> AIB.cache_packages_list
       #            +-> [ cache package deps ]
       creation_deps += [ ":${_manifest_list}" ]
     }
   }

   if (defined(invoker.qemu_kernel)) {
     creation_args += [
       "--qemu-kernel",
       rebase_path(invoker.qemu_kernel, root_build_dir),
     ]
   }

   # Create the out-of-tree-usable Assembly Input Bundle
   python_action(labels.assembly_input_bundle) {
     forward_variables_from(invoker,
                            [
                              "testonly",
                              "visibility",
                            ])

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

     # The contents of these folders is dynamic, and managed entirely by this
     # action.  Further, this action will need to delete items from these
     # directories that are not added back (on an incremental build, if an item
     # is removed from one of these sets)
     #
     # These folders would grow in size forever, if it was not cleaned out on
     # each incremental build.
     hermetic_action_ignored_prefixes = [
       "${files.assembly_input_bundle_dir}/packages",
       "${files.assembly_input_bundle_dir}/subpackages",
       "${files.assembly_input_bundle_dir}/blobs",
       "${files.assembly_input_bundle_dir}/config_data",
       "${files.assembly_input_bundle_dir}/bootfs",
       "${files.assembly_input_bundle_dir}/kernel",
     ]

     outputs = [ files.assembly_input_bundle_config ]
     depfile = files.assembly_input_bundle_depfile

     args = [
       "create",
       "--outdir",
       rebase_path(files.assembly_input_bundle_dir, root_build_dir),
       "--depfile",
       rebase_path(files.assembly_input_bundle_depfile, root_build_dir),
     ]
     args += creation_args

     # 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 = creation_inputs
     deps = creation_deps

     metadata = {
       # We insert these barriers to prevent the dependencies of the input bundle
       # from leaking into images "higher up" in the dependency chain.
       package_barrier = []
       assembly_package_barrier = []
       config_package_barrier = []
       distribution_entries_barrier = []
       driver_package_component_files_barrier = []
       system_image_package_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}" ]
     }
   }
 }
	# Copyright 2021 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/bazel/bazel_inputs.gni")
	import("//build/python/python_action.gni")
	import("//src/sys/pkg/bin/pm/pm.gni")

	# Creates a Fuchsia Package for an Assembly Input Bundle. For the format
	# of the created package, see the AssemblyInputBundle documentation at:
	# //build/python/modules/assembly/assembly_input_bundle.py
	#
	# Parameters
	#
	# manifest
	# [path] The path to the FINI manifest created by the assembly input bundle
	#
	# package_name (optional; default: target_name)
	# [string] The name of the package, if not $target_name
	#
	# package_outdir (optional; default: target_out_dir)
	# [path] A different directory to write the bundle into, if not to write it
	# to '$target_out_dir/$bundle_name'.
	#
	# GN usual meanings
	# deps, testonly, visibility
	#
	template("assembly_input_bundle_package") {
	assert(defined(invoker.manifest),
	"A manifest path must be specified: " +
	get_label_info(target_name, "label_with_toolchain"))

	package_outdir = target_out_dir
	if (defined(invoker.package_outdir)) {
	package_outdir = invoker.package_outdir
	}

	package_name = target_name
	if (defined(invoker.bundle_name)) {
	package_name = invoker.package_name
	}

	labels = {
	package_manifest_creation = "${target_name}.creation_manifest.fini"
	package = target_name
	}

	files = {
	meta_package_file = "$package_outdir/meta_package"
	creation_manifest = "$package_outdir/creation_manifest.fini"
	}

	# Build a package PackageBuildManifest that includes the contents in
	# \|invoker.manifest\| and a generated meta/package file.
	python_action(labels.package_manifest_creation) {
	forward_variables_from(invoker,
	[
	"deps",
	"testonly",
	])
	visibility = [ ":${labels.package}" ]
	binary_label = "//build/assembly/scripts:assembly_input_bundle_tool"
	inputs = [ invoker.manifest ]
	outputs = [
	files.creation_manifest, # must be the first output, for passing to
	# pm_build
	files.meta_package_file,
	]
	args = [
	"generate-package-creation-manifest",
	"--name",
	package_name,
	"--contents-manifest",
	rebase_path(invoker.manifest, root_build_dir),
	"--meta-package",
	rebase_path(files.meta_package_file, root_build_dir),
	"--output",
	rebase_path(files.creation_manifest, root_build_dir),
	]
	}

	pm_build(target_name) {
	forward_variables_from(invoker,
	[
	"deps",
	"testonly",
	"visibility",
	])
	package_name = package_name
	package_out_dir = package_outdir
	manifest = ":${labels.package_manifest_creation}"
	metadata = {
	if (defined(invoker.metadata)) {
	forward_variables_from(invoker.metadata, "*")
	}

	# These are a bunch of barriers to make sure that if this target gets
	# included anywhere, it's dependencies don't end up getting gathered
	# in metadata walks.
	distribution_entries_barrier = []
	package_barrier = []
	assembly_package_barrier = []
	driver_package_barrier = []
	system_image_package_barrier = []
	system_image_extra_package_manifest_barrier = []
	test_component_manifest_barrier = []
	test_component_manifest_program_barrier = []
	}
	}
	}

	# Creates an archive for the Fuchsia Package for an Assembly Input Bundle.
	#
	# This is a tgz that contains the entire contents of the AIB, including the
	# meta.far file as well. See the AssemblyInputBundle documentation at:
	# //build/python/modules/assembly/assembly_input_bundle.py
	#
	# Parameters
	#
	# archive_name (optional; default: target_name)
	# [string] A different name for the archive, if not the name of the target.
	#
	# archive_outdir (optional; default: target_out_dir)
	# [path] A different directory to write the archive into.
	#
	# manifest
	# [path] The path to the FINI manifest created for the
	# assembly input bundle
	#
	# meta_far
	# [path] The path to the meta far created for the assembly input bundle's package
	#
	template("assembly_input_bundle_archive") {
	assert(defined(invoker.manifest),
	"A manifest path must be specified: " +
	get_label_info(target_name, "label_with_toolchain"))

	archive_outdir = target_out_dir
	if (defined(invoker.archive_outdir)) {
	archive_outdir = invoker.archive_outdir
	}

	archive_name = target_name
	if (defined(invoker.archive_name)) {
	archive_name = invoker.archive_name
	}

	labels = {
	tarmaker = "//build/tools/tarmaker($host_toolchain)"
	}

	files = {
	tarmaker = host_out_dir + "/tarmaker"

	archive = "${archive_outdir}/${archive_name}.tgz"
	archive_creation_manifest = "${archive}.creation_manifest.fini"
	depfile = "${archive}.d"
	}

	python_action(target_name) {
	forward_variables_from(invoker,
	[
	"testonly",
	"visibility",
	])
	binary_label = "//build/assembly/scripts:assembly_input_bundle_tool"
	inputs = [
	invoker.manifest,
	files.tarmaker,
	]
	outputs = [
	files.archive,
	files.archive_creation_manifest,
	]
	depfile = files.depfile
	args = [
	"generate-archive",
	"--tarmaker",
	rebase_path(files.tarmaker, root_build_dir),
	"--contents-manifest",
	rebase_path(invoker.manifest, root_build_dir),
	"--creation-manifest",
	rebase_path(files.archive_creation_manifest, root_build_dir),
	"--output",
	rebase_path(files.archive, root_build_dir),
	"--depfile",
	rebase_path(files.depfile, root_build_dir),
	]
	deps = [ labels.tarmaker ]
	if (defined(invoker.deps)) {
	deps += invoker.deps
	}
	if (defined(invoker.meta_far)) {
	args += [
	"--meta-far",
	rebase_path(invoker.meta_far, root_build_dir),
	]
	}
	metadata = {
	assembly_input_archives = [
	{
	path = rebase_path(files.archive, root_build_dir)
	label = get_label_info(":$target_name", "label_with_toolchain")
	},
	]
	}
	}
	}

	# Creates an Assembly Input Bundle from sets of deps.
	#
	# NOTE: This is not yet able to support all categories of inputs that are in an
	# AIB. That support will be added in future CLs. See the parameters
	# below for the categories that are currently supported.
	#
	# NOTE: This template DOES NOT use GN metadata, all labels for packages must be
	# the actual target that creates the package.
	#
	# Parameters
	#
	# bundle_name (optional; default: target_name)
	# [string] A different name for the bundle, if not the name of the target.
	#
	# bundle_dir (optional; default: target_out_dir)
	# [path] A different directory to write the bundle into, if not to write it
	# to '$target_out_dir/$bundle_name'.
	#
	# base_packages [optional]
	# [list, GN labels] A list of GN labels of fuchsia_package targets to
	# include in the base package set.
	#
	# Note: These are direct labels for specific targets, not deps to walk for
	# metadata. If the target isn't a package target, it will cause an error
	# like:
	# "no dependency provides the input <package_name>/package_manifest.json"
	#
	# base_driver_packages (optional)
	# [list, GN scopes] A list of GN scopes that hold the driver packages to
	# include in the base package set. Packages listed here should not be
	# listed in the base_packages and will be included automatically in
	# the base package set as driver packages. The scope must have a
	# `package_target` field pointing to the GN target of the fuchsia_package,
	# and `driver_components` field containing a list of relative paths to
	# driver components provided by the package, e.g. "meta/driver.cm"
	#
	# cache_packages [optional]
	# [list, GN labels] A list of GN labels of fuchsia_package targets to
	# include in the cache package set.
	#
	# bootfs_packages [optional]
	# [list, GN labels] A list of GN labels of fuchsia_package targets to
	# include in the bootfs package set.
	#
	# Note: These are direct labels for specific targets, not deps to walk for
	# metadata. If the target isn't a package target, it will cause an error
	# like:
	# "no dependency provides the input <package_name>/package_manifest.json"
	#
	# qemu_kernel (optional; default: false)
	# [path] Path to the qemu kernel.
	#
	# create_aib_package (optional; default: false)
	# [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: false)
	# [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
	#
	#
	# GN usual meanings
	# testonly, visibility
	template("assembly_input_bundle") {
	bundles_dir = target_out_dir
	if (defined(invoker.bundles_dir)) {
	bundles_dir = invoker.bundles_dir
	}

	bundle_name = target_name
	if (defined(invoker.bundle_name)) {
	bundle_name = invoker.bundle_name
	}

	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"
	}

	files = {
	# 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 files that we create as book-keeping between our tasks.
	assembly_input_bundle_depfile = "${assembly_input_bundle_dir}.d"

	# 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"
	}

	create_aib_package =
	defined(invoker.create_aib_package) && invoker.create_aib_package
	create_aib_archive =
	defined(invoker.create_aib_archive) && invoker.create_aib_archive

	creation_args = []
	creation_inputs = []
	creation_deps = []
	if (defined(invoker.deps)) {
	creation_deps += invoker.deps
	}

	# Convert each set of package targets into:
	# 1) a set of manifests paths in a file
	# 2) add that file as an input and argument to the AIB creation action
	# 3) add the target labels as dependencies of the AIB creation action

	# This defines a set of package sets that can be looped over by name to find
	# process. This use of defined() and the invoker is to tolerate undefined,
	# optional, parameters to the template, as `invoker[name]` is not supported
	# with defined
	package_sets = {
	base = []
	if (defined(invoker.base_packages)) {
	foreach(_target, invoker.base_packages) {
	base += [
	{
	package_target = _target
	},
	]
	}
	}
	cache = []
	if (defined(invoker.cache_packages)) {
	foreach(_target, invoker.cache_packages) {
	cache += [
	{
	package_target = _target
	},
	]
	}
	}
	bootfs = []
	if (defined(invoker.bootfs_packages)) {
	foreach(_target, invoker.bootfs_packages) {
	bootfs += [
	{
	package_target = _target
	},
	]
	}
	}

	drivers = []
	if (defined(invoker.base_driver_packages)) {
	drivers = invoker.base_driver_packages
	}
	}

	# Loop over the above sets of packages
	foreach(set_name,
	[
	"base",
	"cache",
	"drivers",
	"bootfs",
	]) {
	_package_target_details = package_sets[set_name]
	_package_targets = []
	_manifest_entries = []

	# Skip empty package sets
	if (_package_target_details != []) {
	# 1a) Calculate the manifest path for each package target
	foreach(details, _package_target_details) {
	assert(
	defined(details.package_target),
	"A target must be defined for each package. (this should be unreachable)")
	_package_targets += [ details.package_target ]
	_package_out_dir =
	get_label_info(details.package_target, "target_out_dir")
	_package_name = get_label_info(details.package_target, "name")
	_manifest_path =
	"${_package_out_dir}/${_package_name}/package_manifest.json"
	_manifest_path_rebased = rebase_path(_manifest_path, root_build_dir)

	if (set_name == "drivers") {
	assert(defined(details.driver_components),
	"driver_components must be specified for driver targets")
	_manifest_entries += [
	{
	package_target = _manifest_path_rebased
	driver_components = details.driver_components
	},
	]
	} else {
	_manifest_entries += [ _manifest_path_rebased ]
	}
	}

	_manifest_list = "${target_name}.${set_name}_packages.list"
	_manifest_list_file = "${target_gen_dir}/${_manifest_list}"

	# 1b) Generate a file containing that list
	# For base packages this will be a list of package manifests.
	# For drivers, this will be a list of DriverDetails, containing
	# the package manifests and component file paths.
	generated_file(_manifest_list) {
	forward_variables_from(invoker, [ "testonly" ])
	deps = _package_targets
	outputs = [ "${_manifest_list_file}" ]
	output_conversion = "json"
	contents = _manifest_entries
	}

	# 2) add the file as an input and argument to the AIB creation action
	creation_args += [
	"--${set_name}-pkg-list",
	rebase_path(_manifest_list_file, root_build_dir),
	]
	creation_inputs += [ _manifest_list_file ]

	# 3) add the file as a dependency of the AIB creation action (linking the
	# actual package deps transitively, to preserve the route by which they
	# are added to the AIB:
	# AIB
	# +-> AIB.base_packages_list
	# +-> [ base package deps ]
	# +-> AIB.cache_packages_list
	# +-> [ cache package deps ]
	creation_deps += [ ":${_manifest_list}" ]
	}
	}

	if (defined(invoker.qemu_kernel)) {
	creation_args += [
	"--qemu-kernel",
	rebase_path(invoker.qemu_kernel, root_build_dir),
	]
	}

	# Create the out-of-tree-usable Assembly Input Bundle
	python_action(labels.assembly_input_bundle) {
	forward_variables_from(invoker,
	[
	"testonly",
	"visibility",
	])

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

	# The contents of these folders is dynamic, and managed entirely by this
	# action. Further, this action will need to delete items from these
	# directories that are not added back (on an incremental build, if an item
	# is removed from one of these sets)
	#
	# These folders would grow in size forever, if it was not cleaned out on
	# each incremental build.
	hermetic_action_ignored_prefixes = [
	"${files.assembly_input_bundle_dir}/packages",
	"${files.assembly_input_bundle_dir}/subpackages",
	"${files.assembly_input_bundle_dir}/blobs",
	"${files.assembly_input_bundle_dir}/config_data",
	"${files.assembly_input_bundle_dir}/bootfs",
	"${files.assembly_input_bundle_dir}/kernel",
	]

	outputs = [ files.assembly_input_bundle_config ]
	depfile = files.assembly_input_bundle_depfile

	args = [
	"create",
	"--outdir",
	rebase_path(files.assembly_input_bundle_dir, root_build_dir),
	"--depfile",
	rebase_path(files.assembly_input_bundle_depfile, root_build_dir),
	]
	args += creation_args

	# 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 = creation_inputs
	deps = creation_deps

	metadata = {
	# We insert these barriers to prevent the dependencies of the input bundle
	# from leaking into images "higher up" in the dependency chain.
	package_barrier = []
	assembly_package_barrier = []
	config_package_barrier = []
	distribution_entries_barrier = []
	driver_package_component_files_barrier = []
	system_image_package_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}" ]
	}
	}
	}