zircon/public/gn/resource.gni

# Copyright 2019 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.

# Declare a data file to be accessible at runtime on the target device.
#
# A resource() target looks just like a copy() target but $outputs are
# relative target paths.  Using $data_deps to this resource() target in
# each target whose code uses $outputs at runtime ensures that the files
# will be present on the system.
#
# If the file is not in the source tree, it should be generated by another
# target in the build listed in $deps.  If that would be a generated_file()
# target, then use generated_resource() instead of resource().
#
# Parameters
#
#   data_deps
#     Optional: Additional dependencies for the runtime image.  These are
#     included in the image if this target is, but are not related to the
#     $sources list.
#     Type: list(label)
#
#   deps
#     Optional: Targets that produce $sources.  Any files listed in
#     $sources that are produced by the build should be produced by a
#     target listed here.  This is the only thing that guarantees those
#     files will have been built by the time the image is being packed.
#     Targets reached only via this $deps list will *not* contribute their
#     own contents to the image directly.  For that, list them in $data_deps.
#     Targets listed here are used only to produce the $sources files.
#     Type: list(label)
#
#   outputs
#     Required: List of one runtime path.  This must be a relative path (no
#     leading `/`).  It can use placeholders based on $sources; see copy()
#     and `gn help source_expansion`.  When this resource() target is in
#     the dependency graph of a zbi() target, then this is the path within
#     the BOOTFS, which appears at /boot in the namespace of early-boot and
#     standalone Zircon processes.  When it's instead in the dependency graph
#     of a package, then this is the path within the package's file namespace.
#     TODO(mcgrathr): Clarify package case when actually implemented.
#     Type: list(path)
#
#   sources
#     Required: List of files in the source tree or build that become $outputs.
#     See copy() for details.
#     Type: list(file)
#
# See copy() for other parameters.
#
template("resource") {
  group(target_name) {
    forward_variables_from(invoker,
                           "*",
                           [
                             "metadata",
                             "outputs",
                             "sources",
                           ])
    metadata = {
      manifest_barrier = []
      manifest_lines = []
      zbi_barrier = []

      if (defined(invoker.metadata)) {
        forward_variables_from(invoker.metadata, "*")
      }

      # Stop manifest_file() and zbi() from picking up files or zbi_input()
      # items from the deps, but let them reach the data_deps.
      if (defined(data_deps)) {
        manifest_barrier += data_deps
        zbi_barrier += data_deps
      }

      foreach(source, invoker.sources) {
        foreach(target, process_file_template([ source ], invoker.outputs)) {
          assert(rebase_path(target, "foo") != target,
                 "`outputs` in resource() cannot start with /")
          manifest_lines +=
              [ target + "=" + rebase_path(source, root_build_dir) ]
        }
      }
    }
  }
}

# Looks just like a generated_file() target but $outputs is like resource().
#
# A generated_resource() target is like a resource() target whose $sources
# matches the $outputs of a generated_file() target, but rolled into one.
# Using $data_deps to this generated_resource() target in each target whose
# code uses $outputs at runtime ensures that the files will be present on
# the system.  The files can have fixed contents given directly in the
# target or be generated from metadata collection, as in generated_file().
#
# Parameters
#
#   outputs
#     Required: See resource().
#
# See generated_file() for other parameters.
#
template("generated_resource") {
  generated_file(target_name) {
    forward_variables_from(invoker, "*", [ "metadata" ])
    assert(outputs == [ outputs[0] ],
           "generated_resource() requires a single element in `outputs")

    # Select a place to generate the contents at `gn gen` time.
    file = "$target_gen_dir/$target_name"
    if (defined(output_conversion) && output_conversion == "json") {
      file += ".json"
    } else {
      file += ".txt"
    }

    # Add metadata to add that file to a filesystem image.
    metadata = {
      manifest_barrier = []
      manifest_lines = []
      zbi_barrier = []

      if (defined(invoker.metadata)) {
        forward_variables_from(invoker.metadata, "*")
      }

      if (defined(data_deps)) {
        manifest_barrier += data_deps
        zbi_barrier += data_deps
      }

      manifest_lines += [ "${outputs[0]}=" + rebase_path(file, root_build_dir) ]
    }

    # That static file is the actual output of this target.
    outputs = []
    outputs = [ file ]
  }
}