Understanding the GN build system in Fuchsia OS, what is `build_api_module`?

Question

GN stands for Generate Ninja. It generates ninja files which build things. The main file is BUILD.GN at the root of the fuchsia source tree

It contains a lot of build_api_module calls:

build_api_module("images") {
  testonly = true
  data_keys = [ "images" ]
  deps = [
    # XXX(46415): as the build is specialized by board (bootfs_only)
    # for bringup, it is not possible for this to be complete. As this
    # is used in the formation of the build API with infrastructure,
    # and infrastructure assumes that the board configuration modulates
    # the definition of `zircon-a` between bringup/non-bringup, we can
    # not in fact have a complete description. See the associated
    # conditional at this group also.
    "build/images",

    # This has the images referred to by $qemu_kernel_label entries.
    "//build/zircon/zbi_tests",
  ]
}

however, it's unclear for me what this does exactly. Looking at its definition on build/config/build_api_module.gn for example:

template("build_api_module") {
  if (current_toolchain == default_toolchain) {
    generated_file(target_name) {
      outputs = [ "$root_build_dir/$target_name.json" ]
      forward_variables_from(invoker,
                             [
                               "contents",
                               "data_keys",
                               "deps",
                               "metadata",
                               "testonly",
                               "visibility",
                               "walk_keys",
                               "rebase",
                             ])
      output_conversion = "json"
      metadata = {
        build_api_modules = [ target_name ]
        if (defined(invoker.metadata)) {
          forward_variables_from(invoker.metadata, "*", [ "build_api_modules" ])
        }
      }
    }
  } else {
    not_needed([ "target_name" ])
    not_needed(invoker, "*")
  }
}

it looks like it simply generates a file.

Can someone explain to me how build_api_module("images") ends up building all the zircon kernel images?

Answer 1

The build_api_module() targets generate JSON files that describe something about the current build system configuration. These files are typically consumed by other tools (in some cases dependencies to other build rules) that need to know about the current build.

One example is the tests target which generates the tests.json file. This file is used by fx test to determine which tests are available and match the test name you provide to the component URL to invoke.

Can someone explain to me how build_api_module("images") ends up building all the zircon kernel images?

It doesn't. These targets are descriptive of the current build configuration, they are not prescriptive of what artifacts the build generates. In this specific case, the images.json file is typically used by tools like FEMU and ffx to determine what system images to use on a target device.