build/sdk/plasa/plasa_fragment_cc.gni

# 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/compiled_action.gni")
import("//build/sdk/plasa/clang_doc.gni")

# Generates a Plasa fragment for a C++ SDK target.
#
# Parameters
#
#   source_dir (optional)
#     If set, path to the base directory of the sources.
#     This is useful if the sources are generated and therefore not hosted
#     directly under the directory where the GN rules are declared.
#
#   include_base (optional)
#     Path to the root directory for includes.
#     Defaults to "include".
#
#   testonly (optional)
#     Set to true if the artifacts are generated for a test-only target.
#
#   all_deps
#     All dependencies to be used in generating the build artifact.
#
#   sdk_headers_for_internal_use
#     Headers that should not be included in the stub generation.
#
#   file_base
#     The base path to which the files should be packaged.

template("plasa_fragment_cc") {
  forward_variables_from(invoker,
                         [
                           "all_deps",
                           "all_headers",
                           "file_base",
                           "include_base",
                           "main_target_name",
                           "sdk_headers_for_internal_use",
                           "source_dir",
                         ])

  assert(defined(invoker.file_base), "file_base is required")

  _cc_stub_file = "$target_gen_dir/${main_target_name}.api_stub.cc"

  # Build a stub file that demonstrates the use of the library. This file is
  # an input into API extraction.
  _stub_cc_target_name = "${main_target_name}_cc_stub"
  _includable_headers = all_headers
  if (defined(sdk_headers_for_internal_use)) {
    # Some headers published with the SDK library will error out (on purpose)
    # if included directly.  To build an API stub file, we must include all
    # headers except such headers.
    _includable_headers += sdk_headers_for_internal_use
    _includable_headers -= sdk_headers_for_internal_use
  }
  source_set(_stub_cc_target_name) {
    forward_variables_from(invoker, [ "testonly" ])

    # Write out the stub file that will be compiled thereafter.
    _contents = []
    foreach(_header, _includable_headers) {
      _src_dir = rebase_path(".", target_gen_dir)
      _contents += [ "#include \"${_src_dir}/${_header}\"" ]
    }
    _contents += [ "namespace {}" ]
    write_file(_cc_stub_file, _contents, "list lines")

    if (defined(include_base)) {
      _src_dir = rebase_path(".")
      include_dirs = [ "${_src_dir}/${include_base}" ]
    }
    sources = [ _cc_stub_file ]
    deps = all_deps + [
             # The library dependencies.
             ":${main_target_name}",
           ]
  }

  # Currently we use clang-doc to extract the C++ API.
  _clang_doc_target_name = "${main_target_name}_api"
  clang_doc(_clang_doc_target_name) {
    forward_variables_from(invoker, [ "testonly" ])
    stub_file = _cc_stub_file
    deps = [ ":${_stub_cc_target_name}" ]
  }

  # This target directory is generated inside clang_doc.
  _clang_doc_api_d =
      "${target_gen_dir}/${main_target_name}_api_filter_compdb.api.d"
  _plasa_api_output_file =
      "${target_gen_dir}/${main_target_name}.fragment.plasa.json"
  _plasa_target_name = "${main_target_name}_plasa_api"
  compiled_action(_plasa_target_name) {
    forward_variables_from(invoker, [ "testonly" ])
    tool = "//sdk/ctf/plasa/clang_doc_filter"
    outputs = [ _plasa_api_output_file ]
    sources = [ _clang_doc_api_d ]
    args = [
      # TODO(https://fxbug.dev/42166687): Remove leniency when bug is fixed.
      "--lenient",
      "--input-dir",
      rebase_path(_clang_doc_api_d, root_build_dir),
      "--output-file",
      rebase_path(_plasa_api_output_file, root_build_dir),
    ]
    deps = [
      ":${_clang_doc_target_name}",
      ":${_clang_doc_target_name}_clang_doc_invoke",
    ]
    metadata = {
      plasa = [
        {
          # 'kind' specifies the type of the data in the file. Knowing 'kind'
          # should be enough to know which data schema to use to read and
          # interpret it.
          kind = "api_cc"

          # 'file' is the label of the file, i.e. a string starting with '//'.
          file = _plasa_api_output_file

          # 'path' is the path to the file relative to `$root_build_dir`.
          path = rebase_path(_plasa_api_output_file, root_build_dir)

          # 'dest' is the packaging destination should this file be packaged
          # anywhere in particular.
          dest = "${file_base}/" +
                 rebase_path(_plasa_api_output_file, target_gen_dir)
        },
      ]
    }
  }

  group("${target_name}") {
    forward_variables_from(invoker, [ "testonly" ])
    deps = [
      ":${_clang_doc_target_name}",
      ":${_plasa_target_name}",
    ]
  }
}