Zircon Public Headers

This directory is in the include path for all kernel and system modules in Zircon, and is also exported into the include directory of the generate sysroot.

Most headers should live with their respective libraries. These headers are ones that need to be global because they're a public API/ABI surface or a header needed by a large number of public headers (eg, zircon/compiler.h)

Headers in this directory are also used building Fuchsia host tools. These builds cannot get these headers from sysroot: sysroot is for target builds. Instead such tools need to add the following to their BUILD.gn:

executable("foo") {
  deps = [ ... ]
  if (!is_fuchsia) {
    deps += [ "//zircon/system/public" ]
  }
}

Some of these headers are generated by the build, and checked in and kept up to date via the platform's golden file framework. At build-time a diff is made between currently checked-in header and the one emitted by the build, and if there is a difference the build fails and prints out a cp command to update the former. If the update_goldens GN arg is true, then instead of failing, the files will automatically be updated in the build step.

There is further SDK logic that tracks the hash content of these headers in //zircon/public/sysroot_sdk/sysroot.api, which itself is kept up-to-date with the same golden file framework.