blob: b53072aa7b2bf96f82fe96ed25b9374b4ea940b0 [file] [log] [blame]
# 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.
#
# 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",
"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")
},
]
}
}
# 'sdk_shared_library()' targets in the 'partner' or 'public' category that
# are not testonly must be tracked by
# //build/sdk:sdk_versioned_shared_libraries_allowlist for SDK consistency
# checks (see https://fxbug.dev/42057225).
if (invoker.category == "partner" || invoker.category == "public") {
deps += [ "//build/sdk:sdk_versioned_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 != -1) {
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" ])
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}" ]
}
}
}