# Copyright 2018 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/config/fuchsia/target_api_level.gni")
import("//build/cpp/verify_pragma_once.gni")
import("//build/cpp/verify_public_headers.gni")
import("//build/cpp/verify_public_symbols.gni")
import("//build/cpp/verify_runtime_deps.gni")
import("//build/sdk/plasa/config.gni")
import("//build/sdk/plasa/plasa_fragment_cc.gni")
import("//build/sdk/sdk_atom.gni")
import("//build/sdk/sdk_atom_alias.gni")

# A shared library that can be exported to an SDK in binary form.
#
# Parameters
#
#   category (required)
#     Publication level of the library in SDKs.
#     See //build/sdk/sdk_atom.gni.
#
#   sdk_area (optional)
#     [string] The API area responsible for maintaining this library.
#     See //build/sdk/sdk_atom.gni.
#
#   api (optional)
#     Path to the file representing the API of this library.
#     This file is used to ensure modifications to the library's API are
#     explicitly acknowledged. It is mandatory for publication categories of
#     "partner" or "public".
#     Defaults to "<SDK name>.api".
#
#   symbols_api (optional)
#     Path to the ifs file containing the public symbols of this library.
#     This file is used to ensure modifications to the library's ABI are
#     explicitly acknowledged. It is mandatory for publication categories of
#     "partner" or "public".
#
#   no_headers (optional)
#     Whether to include the library's headers in the SDK.
#     Defaults to false.
#
#   libcxx_linkage (optional)
#     Whether or how to link libc++. SDK shared libraries cannot link libc++.so
#     dynamically because libc++.so does not have a stable ABI. Can be either
#     "none" or "static".
#     Defaults to "none".
#
#   sdk_name (optional)
#     Name of the library in the SDK.
#     Defaults to the library's output name.
#
#   include_base (optional)
#     Path to the root directory for includes.
#     Defaults to "include".
#
#   runtime_deps (optional)
#     List of labels representing the library's runtime dependencies. This is
#     Note that these labels should represent SDK targets. See note below.
#
#   sdk_headers_for_internal_use (optional)
#     Out of the headers specified in `public` or `sources`, some headers are
#     part of the SDK but not meant for direct inclusion by users, i.e. they are
#     only transitively included by other public headers. They usually contain
#     implementation details. Re-specify those headers here.
#
#     When enumerating the platform surface area (PlaSA), these headers will
#     be excluded. See /build/sdk/plasa/plasa_fragment_cc.gni.
#
#     See https://fxbug.dev/42068255 for more details about this field.
#
# TECHNICAL NOTE ON 'runtime_deps':
#
# The `runtime_deps` parameter is used to list the sdk_shared_library()
# targets that this one depends on at runtime. Unfortunately, this cannot be
# computed directly by GN. To better understand why, consider the following
# example:
#
#     sdk_shared_library("foo") {
#       ...
#       deps = [ ":bar" ]
#     }
#
#     sdk_shared_library("bar") {
#       ...
#     }
#
# These definitions end up creating at least four GN targets:
#
#  - a 'foo' and 'bar' target, which are real shared_library() targets
#    used to build libfoo.so and libbar.so respectively.
#
#    and due to the 'deps' value, 'foo' will depend on 'bar'.
#
#  - a 'foo_sdk' and a 'bar_sdk' targets that generate an sdk_atom() wrapping
#    each library, i.e. the target responsible for creating a meta.json file
#    for each library, and used to generate exported SDKs.
#
#    'foo_sdk' depends on 'foo', and 'bar_sdk' depends on 'bar', as in:
#
#
#     foo <--- foo_sdk
#      |
#      v
#     bar <--- bar_sdk
#
#
# However, without "runtime_deps", 'foo_sdk' will _not_ depend on 'bar_sdk',
# which means that if an sdk_collection() target depends on 'foo_sdk', the
# atom for the 'bar_sdk' target will be ignored. The result is a "broken"
# exported dir that will not include a prebuilt for libbar.so, even though
# it is needed at runtime by libfoo.so.
#
# To fix this, set 'runtime_deps' to point to the SDK atom target for bar,
# as in:
#
#    sdk_shared_library("foo") {
#      ...
#      deps = [ ":bar" ]
#      runtime_deps = [ ":bar_sdk" ]
#    }
#
#    sdk_shared_library("bar") {
#      ...
#    }
#
# Which results in the following (correct) dependency graph:
#
#     foo <--- foo_sdk
#      |          |
#      |          |--- this dependency added through runtime_deps!
#      v          v
#     bar <--- bar_sdk
#

# The defaults for a sdk_shared_library should match that of a shared_library.
set_defaults("sdk_shared_library") {
  configs = default_shared_library_configs
}

template("sdk_shared_library") {
  assert(defined(invoker.category), "Must define an SDK category")
  is_internal = invoker.category == "internal"

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

  if (defined(invoker.sdk_name)) {
    atom_name = invoker.sdk_name
  } else {
    atom_name = output_name
  }

  if (!is_internal) {
    sdk_root_path = "pkg/${atom_name}"
  } else {
    # For internal SDK libraries, the sdk_name is the fully qualified target name with some tweaks. For example:
    #    //src/lib/fxl:fxl            sdk_name = //src/lib/fxl_fxl          sdk_root_path= src/lib/fxl_fxl
    #    //src/lib/fxl:functional     sdk_name = //src/lib/fxl_functional   sdk_root_path= src/lib/fxl_functional
    #    //src/lib/fxl/files:files    sdk_name = //src/lib/fxl/files_files  sdk_root_path= src/lib/fxl/files_files
    full_label = get_label_info(":${invoker.target_name}", "label_no_toolchain")
    path = get_label_info(full_label, "dir")
    path = "${path}_${invoker.target_name}"

    atom_name = path
    sdk_root_path = string_replace(path, "//", "")
  }
  sdk_id = "sdk://${sdk_root_path}"

  no_headers = defined(invoker.no_headers) && invoker.no_headers

  if ((invoker.category == "partner" || invoker.category == "public") &&
      !no_headers) {
    api_reference = "${atom_name}.api"
    if (defined(invoker.api)) {
      api_reference = invoker.api
    }
  }

  main_target_name = target_name
  metadata_target_name = "${target_name}_sdk_metadata"
  manifest_target_name = "${target_name}_sdk_manifest"
  sdk_target_name = "${target_name}_sdk"

  shared_library(main_target_name) {
    forward_variables_from(invoker,
                           "*",
                           [
                             "api",
                             "category",
                             "sdk_area",
                             "include_base",
                             "no_headers",
                             "sdk_headers_for_internal_use",
                             "runtime_deps",
                             "sdk_name",
                             "symbols_api",
                           ])

    if (defined(visibility)) {
      visibility += [ ":${manifest_target_name}" ]
    }

    if (!defined(libcxx_linkage)) {
      libcxx_linkage = "none"
    }
    assert(libcxx_linkage == "none" || libcxx_linkage == "static")

    # Prebuilt shared libraries are eligible for inclusion in the SDK. We do not
    # want to dynamically link against libc++.so because we let clients bring
    # their own toolchain, which might have a different C++ Standard Library or
    # a different C++ ABI entirely.
    if (!defined(configs)) {
      configs = []
    }
    if (libcxx_linkage == "static") {
      configs += [ "//build/config/fuchsia:static_cpp_standard_library" ]
    } else if (!is_internal) {
      # Adding this linker flag keeps us honest about not committing to a
      # specific C++ ABI. If this flag is causing your library to not
      # compile, consider whether your library really ought to be in the SDK.
      # If so, consider including your library in the SDK as source rather than
      # precompiled. If you do require precompilation, you probably need to
      # find a way not to depend on dynamically linking C++ symbols because C++
      # does not have a sufficiently stable ABI for the purposes of our SDK.
      #
      # NOTE: This flag is not necessary for internal SDK libraries since they
      # are not intended to be consumed by SDK users.
      configs += [ "//build/config/fuchsia:no_cpp_standard_library" ]
    }

    metadata = {
      if (defined(invoker.metadata)) {
        forward_variables_from(invoker.metadata, "*")
      }
      if (is_fuchsia) {
        # Used by sdk_verify_runtime_deps() template.
        sdk_runtime_deps = [
          {
            sdk_id = sdk_id
            label = get_label_info(":${target_name}", "label_with_toolchain")
          },
        ]
      }
    }

    # Ensure that 'sdk_shared_library()' targets in the 'partner' or 'public'
    # category that are not testonly are included in the SDK shared_library
    # allowlist. The allowlist target's `visibility` list ensures that the
    # target using this template is in the allowlist.
    if (invoker.category == "partner" || invoker.category == "public") {
      deps += [ "//build/sdk:sdk_shared_libraries_allowlist" ]
    }
  }

  # Identify dependencies and their metadata files.
  sdk_deps = []
  sdk_metas = []
  all_deps = []
  if (defined(invoker.deps)) {
    all_deps += invoker.deps
  }
  if (defined(invoker.public_deps)) {
    all_deps += invoker.public_deps
  }

  # If a prebuilt library is only provided for packaging purposes (by not
  # exposing headers) then its dependencies need not be included in an SDK.
  if (defined(invoker.public_deps) && !no_headers) {
    foreach(dep, invoker.public_deps) {
      full_label = get_label_info(dep, "label_no_toolchain")
      sdk_dep = "${full_label}_sdk"
      sdk_deps += [ sdk_dep ]
      all_deps += [ sdk_dep ]
    }
  }

  # Runtime deps are already SDK targets.
  if (defined(invoker.runtime_deps)) {
    sdk_deps += invoker.runtime_deps
  }
  foreach(sdk_dep, sdk_deps) {
    gen_dir = get_label_info(sdk_dep, "target_gen_dir")
    name = get_label_info(sdk_dep, "name")
    sdk_metas += [ "${gen_dir}/${name}.meta.json" ]
  }

  # Process headers.
  all_headers = []
  if ((defined(invoker.public) || defined(invoker.sources)) && !no_headers) {
    if (defined(invoker.public)) {
      all_headers += invoker.public
    }

    if (defined(invoker.sources)) {
      # If public headers are not defined, pick them from `sources`.
      #
      # NOTE: If this is an internal SDK library, headers from `sources` are
      # always made available so Bazel can find them.
      if (is_internal || !defined(invoker.public)) {
        foreach(source_file, invoker.sources) {
          extension = get_path_info(source_file, "extension")
          if (extension == "h") {
            all_headers += [ source_file ]
          }
        }
      }
    }
  }

  sdk_metadata_headers = []
  sdk_header_files = []

  if (defined(invoker.include_base)) {
    include_base = invoker.include_base
  } else {
    if (is_internal) {
      # by default, we want internal SDK elements to have their include path similar when used through
      # an SDK (eg Bazel SDk) or directly (GN/Ninja), so that source code doesn't need to be changed
      # when switching from one to the other.
      include_base = "//"
    } else {
      include_base = "include"
    }
  }
  assert(include_base != "")  # Work around for unused variable warning when

  include_dest = "${sdk_root_path}/include"

  foreach(header, all_headers) {
    destination = rebase_path(header, include_base)
    header_dest = "${include_dest}/${destination}"
    sdk_metadata_headers += [ header_dest ]
    sdk_header_files += [
      {
        source = header
        dest = header_dest
      },
    ]
  }

  verify_public_headers_target = "${target_name}.verify_public_headers"
  verify_public_headers(verify_public_headers_target) {
    forward_variables_from(invoker, [ "testonly" ])
    target_label = ":${target_name}"
    headers = all_headers
  }

  # Add binaries.
  #
  # Select shared library binary from the proper toolchain.
  # See shlib_toolchain_no_default_variant_redirect documentation comment
  # in //build/config/BUILDCONFIG.gn to understand why this is needed.
  shared_lib_target =
      ":${main_target_name}(${shlib_toolchain_no_default_variant_redirect})"
  shared_out_dir = get_label_info(shared_lib_target, "root_out_dir")
  lib_name = "lib${output_name}.so"
  link_lib = "${sdk_prebuilt_base_for_target_api_level}/lib/${lib_name}"
  dist_lib = "${sdk_prebuilt_base_for_target_api_level}/dist/${lib_name}"
  sdk_files = sdk_header_files + [
                {
                  source = "${shared_out_dir}/link_stub/${lib_name}"
                  dest = link_lib
                },
                {
                  source = "${shared_out_dir}/${lib_name}"
                  dest = dist_lib
                },
              ]

  if (defined(invoker.symbols_api)) {
    sdk_files += [
      {
        source = get_path_info(invoker.symbols_api, "abspath")
        dest = "${sdk_root_path}/" + get_path_info(invoker.symbols_api, "file")
      },
    ]
  }

  if (generate_plasa_artifacts) {
    _plasa_artifacts_target_name = "${main_target_name}_plasa"
    plasa_fragment_cc(_plasa_artifacts_target_name) {
      forward_variables_from(invoker,
                             [
                               "source_dir",
                               "testonly",
                               "all_headers",
                               "all_deps",
                               "sdk_headers_for_internal_use",
                             ])
      file_base = sdk_root_path
    }
  } else {
    not_needed([
                 "all_deps",
                 "sdk_headers_for_internal_use",
               ])
  }

  metadata_file = "${target_gen_dir}/${metadata_target_name}.sdk_meta.json"
  debug_mapping_file = "${target_gen_dir}/${metadata_target_name}.mappings.txt"
  debug_lib_file = "${shared_out_dir}/lib.unstripped/${lib_name}"

  action(metadata_target_name) {
    forward_variables_from(invoker, [ "testonly" ])
    script = "//build/cpp/gen_sdk_prebuilt_meta_file.py"

    inputs = sdk_metas + [
               debug_lib_file,
               "//build/cpp/binaries.py",
               "//build/images/elfinfo.py",
             ]

    outputs = [
      debug_mapping_file,
      metadata_file,
    ]

    args = [
      "--out",
      rebase_path(metadata_file, root_build_dir),
      "--name",
      atom_name,
      "--format",
      "shared",
      "--root",
      sdk_root_path,
      "--include-dir",
      include_dest,
      "--dist-path",
      "lib/${lib_name}",
      "--arch",
      target_cpu,
      "--lib-link",
      link_lib,
      "--lib-dist",
      dist_lib,
      "--lib-debug-file",
      rebase_path(debug_lib_file, root_build_dir),
      "--debug-mapping",
      rebase_path(debug_mapping_file, root_build_dir),
    ]
    args += [ "--deps" ] + rebase_path(sdk_metas, root_build_dir)
    args += [ "--headers" ] + sdk_metadata_headers
    if (defined(invoker.symbols_api)) {
      args += [ "--ifs" ] + [ get_path_info(invoker.symbols_api, "file") ]
    }
    if (override_target_api_level != "PLATFORM") {
      args += [
        "--api-level",
        "${override_target_api_level}",
      ]
    }

    deps = sdk_deps + [ shared_lib_target ]
  }

  # Exempt internal libraries from pragma verification.
  should_verify_pragma = !is_internal && !no_headers
  if (should_verify_pragma) {
    verify_pragma_target_name = "${target_name}_sdk_pragma"
    verify_pragma_once(verify_pragma_target_name) {
      headers = all_headers
    }
  }

  # Don't verify the public symbols for non-publicized APIs.
  # TODO(abrachet): Make this required for all libraries.
  if (invoker.category == "partner" || invoker.category == "public") {
    assert(
        defined(invoker.symbols_api),
        "Must define path to an ifs file. See comment in //build/cpp/verify_public_symbols.gni")
    main_target_dir = get_label_info(":${main_target_name}", "dir")

    verify_public_symbols_target_name =
        "${target_name}_sdk_verify_public_symbols"
    verify_public_symbols(verify_public_symbols_target_name) {
      current = "${shared_out_dir}/lib${output_name}.ifs"
      reference = invoker.symbols_api
      library_name = main_target_dir

      deps = [ shared_lib_target ]
    }
  }

  sdk_atom(manifest_target_name) {
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "sdk_area",
                           ])

    id = sdk_id

    category = invoker.category

    if (defined(api_reference) && !no_headers) {
      api = api_reference

      api_contents = sdk_header_files
    }

    meta = {
      source = metadata_file
      dest = "${sdk_root_path}/meta.json"
      schema = "cc_prebuilt_library"
    }

    files = sdk_files

    file_list = debug_mapping_file

    deps = sdk_deps

    non_sdk_deps = [
      ":${metadata_target_name}",
      shared_lib_target,
    ]
    if (should_verify_pragma) {
      non_sdk_deps += [ ":${verify_pragma_target_name}" ]
    }
    if (generate_plasa_artifacts) {
      non_sdk_deps += [ ":${_plasa_artifacts_target_name}" ]
    }
    if (category == "partner" || category == "public") {
      non_sdk_deps += [ ":${verify_public_symbols_target_name}" ]
    }

    # Explicitly add non-public dependencies, in case some of the source files
    # are generated.
    if (defined(invoker.deps)) {
      non_sdk_deps += invoker.deps
    }
  }

  sdk_manifest_file = "${target_gen_dir}/${manifest_target_name}.sdk"

  verify_runtime_deps_target = "${target_name}_verify"

  sdk_verify_runtime_deps(verify_runtime_deps_target) {
    atom_target = ":$main_target_name"
    manifest_file = sdk_manifest_file
    manifest_target = ":$manifest_target_name"
  }

  sdk_atom_alias(sdk_target_name) {
    atom = ":${manifest_target_name}"

    non_sdk_deps = [
      ":${verify_public_headers_target}",
      ":${verify_runtime_deps_target}",
    ]

    if (generate_plasa_artifacts) {
      non_sdk_deps += [ ":${_plasa_artifacts_target_name}" ]
    }
  }
}