# Copyright 2020 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/cpp/sdk_shared_library.gni")
import("//build/cpp/sdk_source_set.gni")
import("//build/cpp/sdk_static_library.gni")
import("//build/unification/global_variables.gni")

# Build a zircon-specific library, possibly in several ways.
#
# This template should be used by Zircon build rules exclusively, and follows
# most of the conventions of the Zircon build `library()` template, which
# differ significantly from those of `library()` in the Fuchsia build.
#
# IMPORTANT NOTE: Due to historical reasons, its behaviour is very different,
# depending on the value of the `is_kernel` global variable.
#
# * If `is_kernel` is true, which means when building part of the kernel:
#   The template will assert if the `kernel` argument is not set to true.
#   It will create a source_set() if building part of the kernel, or
#   a static_library() for any other Zircon artefact. The values of `sdk`,
#   `sdk_publishable` and `sdk_headers` will be ignored entirely.
#
#   This will also create a :headers sub-target, a group used to give access
#   to the library's include directory from any dependent. Note that this
#   does *not* make the library's headers, listed in `sdk_headers` public.
#
#   This behaviour is needed to replicate the Zircon build's behaviour when
#   compiling Zircon artefacts.
#
# * If `is`_kernel` is false, which means that the library is built either as a
#   Fuchsia user binary or a host binary, then the `kernel` parameter is
#   ignored, and `sdk` must be set to determine the shape of the library,
#   as well as `sdk_headers to list the library's public headers, relative to
#   its `include` sub-directory.
#
#   If `sdk_publishable` is true, the library will be part of the Fuchsia SDK.
#
#   Any :headers sub-targets that appear in public_deps will be rewritten into
#   a dependency to the library itself, e.g.:
#
#     public_deps = [ "//zircon/system/ulib/foo:headers" ]
#
#   will be replaced by:
#
#     public_deps = [ "//zircon/system/ulib/foo" ]
#
#   Because the Fuchsia build doesn't support :headers sub-targets in
#   non-kernel libraries for several technical reasons.
#
# Parameters
#
#   kernel
#     Optional: True if this library can be used in the kernel.
#     Type: bool
#     Default: false
#
#   sdk
#     Optional: A value that indicates whether to build this library as a
#     source set, static library or shared library with the Fuchsia build.
#     This is required, except if the global `is_kernel` is true. Note that
#     this name is confusing for historical reasons, because using
#     this parameter does not make this library exported to the Fuchsia SDK
#     (see `sdk_publishable` below for this).
#     Type: "static" or "shared" or "source"
#
#   sdk_publishable
#     Optional: Indicates that this library can be added to the Fuchsia SDK.
#     When false, the library is not added to the SDK. When true, it is added
#     to the SDK with a "partner" category. Otherwise, a string value may be
#     used to specify another category (e.g. `sdk_publishable` = "cts"`).
#     Type: bool, or a string indicating an SDK category.
#     Default: false
#
#   sdk_headers
#     Optional: Required, except if the global `is_kernel` is true.
#     This must list all the public header files in the library's `include/`
#     directory; names should be relative to `include/`.
#     Type: list(string)
#
#   sdk_name
#     Optional: Name under which the library is published. This can be used
#     when $target_name is already used by another target in the Fuchsia build.
#     Type: string
#     Default: target_name
#
#   See source_set() for other parameters.
#
# The following parameters are ignored by this implementation. They are here
# to support zx_library() calls that are shared by BUILD.zircon.gn and BUILD.gn
# file. Support for these may be removed after build unification completes.
#
#   host
#     Optional: Was set to true if this library can be used in
#     host-side code, e.g. to be a dependency of a host_tool().
#     Type: bool
#     Default: false
#
#   static
#     Optional: True if this library can be statically linked in user code.
#     Type: bool
#     Default: !$kernel
#
#   shared
#     Optional: True if this library can be made a shared library for user code.
#     Type: bool
#     Default: false
#
#   sdk_migrated
#     Optional: Indicates that this library is built directly by the Fuchsia
#     build, and no longer needs to be exported as a legacy target. This is
#     used to ease build unification, and will disappear once it is completed.
#     Type: bool
#     Default: false
#
template("zx_library") {
  template_params = [
    "host",
    "kernel",
    "sdk",
    "sdk_headers",
    "sdk_publishable",
    "shared",
    "static",
  ]

  # `sdk_migrated` is only used by the Zircon build system.
  not_needed(invoker, [ "sdk_migrated" ])

  if (zircon_toolchain != false) {
    _library_name = target_name

    assert(
        !is_kernel || (defined(invoker.kernel) && invoker.kernel),
        "This zx_library() cannot be built with a Zircon-specific toolchain! " +
            "Consider adding `kernel = true` to its declaration.")

    if (defined(invoker.shared) && invoker.shared) {
      kernel_library_target_type = "shared_library"
    } else if (toolchain.environment == "kernel") {
      # In the kernel proper, zx_library() is always a source_set().
      # Everything goes into the kernel and anything unused gets linker GC.
      kernel_library_target_type = "source_set"
    } else {
      kernel_library_target_type = "static_library"
    }

    # If the library has the same name as its directory, just create
    # :headers and :headers.config sub-targets. Otherwise, create
    # :foo.headers and :foo.headers.config
    if (get_label_info(":$_library_name", "name") ==
        get_path_info(get_label_info(":$_library_name", "dir"), "file")) {
      _headers_target = "headers"
      _headers_config_target = "headers.config"
    } else {
      _headers_target = "$_library_name.headers"
      _headers_config_target = "$_library_name.headers.config"
    }

    target(kernel_library_target_type, _library_name) {
      if (kernel_library_target_type == "static_library") {
        complete_static_lib = true
      }
      forward_variables_from(invoker, "*", template_params)
      if (!defined(public_deps)) {
        public_deps = []
      }
      public_deps += [ ":$_headers_target" ]
    }

    group(_headers_target) {
      # Used to represent header dependencies.
      # Direct us of public_configs should be rare but is sometimes needed.
      forward_variables_from(invoker,
                             [
                               "public_configs",
                               "public_deps",
                               "testonly",
                               "visibility",
                             ])
      if (!defined(public_configs)) {
        public_configs = []
      }
      public_configs += [ ":${_headers_config_target}" ]
    }

    config(_headers_config_target) {
      include_dirs = [ "include" ]
    }
  } else {
    # The following parameters are just ignored, as in the GN build the shape of
    # a library is driven by the value of the "sdk" parameter.
    not_needed(invoker,
               [
                 "kernel",
                 "host",
                 "static",
                 "shared",
               ])

    assert(
        defined(invoker.sdk),
        "The `sdk` argument is needed to build a zx_library() with a Fuchsia or host toolchain ($current_toolchain)")
    shape = invoker.sdk

    sdkable =
        defined(invoker.sdk_publishable) && invoker.sdk_publishable != false
    if (sdkable) {
      if (invoker.sdk_publishable == true) {
        sdk_category = "partner"
      } else {
        sdk_category = invoker.sdk_publishable
      }
    }

    extra_target_args = {
    }
    if (shape == "source") {
      if (sdkable) {
        target_type = "sdk_source_set"
        extra_target_args = {
          category = sdk_category
          api = "//sdk/lib/$target_name/$target_name.api"
          sdk_name = target_name
          build_as_static = true
        }
      } else {
        target_type = "static_library"
      }
    } else if (shape == "static") {
      if (sdkable) {
        target_type = "sdk_static_library"
        extra_target_args = {
          category = sdk_category
          api = "//sdk/lib/$target_name/$target_name.api"
          sdk_name = target_name
          libcxx_linkage = "static"
        }
      } else {
        target_type = "static_library"
      }
    } else if (shape == "shared") {
      if (sdkable) {
        target_type = "sdk_shared_library"
        extra_target_args = {
          category = sdk_category
          api = "//sdk/lib/$target_name/$target_name.api"
          symbols_api = "//sdk/lib/$target_name/$target_name.symbols.api"
          sdk_name = target_name
          libcxx_linkage = "static"
        }
      } else {
        target_type = "shared_library"
      }
    } else {
      assert(false, "Unknown library type: $shape")
    }

    main_target_name = target_name
    if (defined(invoker.sdk_name)) {
      main_target_name = invoker.sdk_name
    }
    config_target_name = "$target_name.config"

    config(config_target_name) {
      include_dirs = [ "include" ]
    }

    # IMPORTANT: Rewrite header dependencies in public_deps
    #
    # For each zx_library(), the Zircon build used to produce a 'headers'
    # group that adds a 'headers.config' public config. This is done to allow
    # other targets to depend on the library's headers, but not the library
    # itself.
    #
    # In practice, this means it is common for targets to list these headers
    # groups in their public_deps, as in:
    #
    #    public_deps = [ "//sdk/lib/fit:headers" ]
    #
    # However, these groups do not mix well with the Fuchsia build, and
    # especially with sdk_source_set() or sdk_static_library().
    #
    # To work around this, rewrite the headers public dependencies into
    # regular dependencies into the libraries themselves.
    #
    lib_deps = []
    if (defined(invoker.deps)) {
      lib_deps = invoker.deps
    }
    lib_public_deps = []
    if (defined(invoker.public_deps)) {
      foreach(dep, invoker.public_deps) {
        if (get_label_info(dep, "name") == "headers") {
          # Format //zircon/.../foo:headers  -> //zircon/.../foo
          dep = get_label_info(dep, "dir")
        } else if (get_path_info(get_label_info(dep, "name"), "extension") ==
                   "headers") {
          # Format //zircon/.../foo:bar.headers -> //zircon/.../foo:bar
          dep = get_label_info(dep, "dir") + ":" +
                get_path_info(get_label_info(dep, "name"), "name")
        }
        lib_public_deps += [ dep ]
      }
    }

    # Remove references to a libzircon dependency, as it is provided by the
    # sysroot in the present build.

    lib_libs = []
    if (defined(invoker.libs)) {
      lib_libs = invoker.libs
    }

    if (!is_fuchsia) {
      lib_public_deps += [ "//zircon/system/public" ]
    }

    _has_public_headers =
        defined(invoker.sdk_headers) && invoker.sdk_headers != []

    target(target_type, main_target_name) {
      forward_variables_from(invoker,
                             "*",
                             template_params + [
                                   "deps",
                                   "libs",
                                   "public_deps",
                                 ])

      deps = lib_deps
      libs = lib_libs
      public_deps = lib_public_deps

      forward_variables_from(extra_target_args, "*")

      if (_has_public_headers) {
        public = []
        foreach(header, invoker.sdk_headers) {
          public += [ "include/$header" ]
        }
      } else if (defined(invoker.sdk_headers) && sdkable) {
        # Add the headers to `sources` to ensure sdk_atom checks the API properly.
        extra_headers = []
        foreach(header, invoker.sdk_headers) {
          extra_headers += [ "include/$header" ]
        }
      }

      if (!defined(public_configs)) {
        public_configs = []
      }
      public_configs += [ ":$config_target_name" ]

      if (!defined(defines)) {
        defines = []
      }
      defines += [ "_ALL_SOURCE" ]

      if (!defined(data_deps)) {
        data_deps = []
      }

      # Add allowlist to data_deps rather than deps to not trigger SDK deps logic
      data_deps += [ "//build:deprecated_zx_wrapper_allowlist" ]
    }
  }

  # Uncomment the below to generate the allowlist
  #print("\"" + get_label_info(":$target_name", "dir") + "/*\",")
}

set_defaults("zx_library") {
  configs = default_common_binary_configs
}