build/rust/rustc_dylib.gni

# 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/rust/rustc_artifact.gni")
import("//build/rust/rustc_test.gni")

# Defines a Rust dynamic library.
#
# NOTE: Support for Rust dylibs is very limited. See https://fxbug.dev/42137337#c17.
#
# Parameters
#
#   name
#     Name of the crate as defined in its manifest file. If not specified, it is
#     assumed to be the same as the target name. All dashes will be replaced
#     with underscores in the library name: <name_underscored>
#
#   edition (optional)
#     Edition of the Rust language to be used.
#     Options are "2015" and "2018". Defaults to "2018".
#
#   configs (optional)
#     A list of config labels applying to this target.
#
#   enforce_source_listing (optional)
#     When true, enforces that any source files used by the Rust compiler are
#     listed in `sources`. Defaults to true.
#
#   sources (optional)
#     List of source files which this crate is allowed to compile. Only
#     allowed when `enforce_source_listing = true`.
#     The Rust compiler discovers source files by following `mod` declarations
#     starting at the `source_root`. The discovered source files must match this
#     list.
#
#   inputs (optional)
#     List of additional non-source files read by the compiler. These are typically
#     configuration or test-data files included in the build with the `include_str!`
#     macro. Only allowed when `enforce_source_listing = true`.
#
#   deps (optional)
#     List of GN targets on which this crate depends.
#     Third party crates can be included through paths like
#     "//third_party/rust_crates:<cratename>",
#
#   test_deps (optional)
#     List of GN targets on which this crate's tests depend.
#
#   data_deps (optional)
#     List of GN targets that are only needed at runtime.
#
#   with_unit_tests (optional)
#     Builds unit tests associated with the binary. This will create a
#     `<name>_lib_test` test file in the output directory. Equivalent
#     to adding a `rustc_test` target with that name and the same source_root.
#
#   test_environments (optional)
#     What environments unit tests, if provided, should target. Only used here
#     for linux and mac tests, with a default value of a general linux/mac
#     environment (as a function of $current_os).
#     See environments parameter on //build/testing/test_spec.gni for more
#     details.
#
#   source_root (optional)
#     Location of the crate root (e.g. `src/main.rs` or `src/lib.rs`).
#     This defaults to `./src/main.rs` for binaries and `./src/lib.rs` for libraries,
#     and should only be changed when absolutely necessary
#     (such as in the case of generated code).
#
#   features (optional)
#     A list of conditional compilation flags to enable. This can be used to set features for crates
#     built in-tree which are also published to crates.io. This would be passed to rustc as
#     '--cfg feature="XXX"'
#
#   output_dir (optional)
#     Directory that the resulting library should be placed in.
#     See: `gn help output_dir`
#
#   disable_rbe (optional)
#     Set to true to force this target to build locally, overriding the global `enable_rbe`.
#     If with_unit_tests is also true, this setting applies to the unit test as well.
#     There is currently no way to separately disable RBE for the library and test.
#
#   disable_clippy (optional)
#     Don't run clippy on this target.
#
#   exclude_toolchain_tags (optional)
#     [strings] A list of tags that corresponds to toolchain variants that
#     this target should not be built with.
#     See: //docs/development/build/concepts/build_system/internals/toolchains/build_variants.md.
#
#   original_target_name (optional)
#     The name of the target as it appears in the BUILD file. Enables tooling
#     to find the template invocation in a BUILD file where this target was defined.
#
# See //examples/rust/dylib/rust-shared/BUILD.gn for an example of using this template.
#
template("rustc_dylib") {
  if (defined(invoker.original_target_name)) {
    _original_target_name = invoker.original_target_name
  } else {
    _original_target_name = target_name
  }

  # if "with_unit_tests" is set to true, generate an additional rust test target
  # TODO(https://fxbug.dev/42152447): accept a string.
  if (defined(invoker.with_unit_tests) && invoker.with_unit_tests == true) {
    rustc_test_internal("${target_name}_test") {
      name = invoker.target_name + "_dylib_test"
      if (defined(invoker.name)) {
        name = invoker.name + "_dylib_test"
      }
      original_target_name = _original_target_name
      forward_variables_from(invoker, "*", [ "name" ])
    }
  }

  if (defined(invoker.source_root)) {
    source_root = invoker.source_root
  } else {
    source_root = "src/lib.rs"
  }

  if (defined(invoker.name)) {
    package_name = invoker.name
  } else {
    package_name = target_name
  }
  _crate_name = string_replace(package_name, "-", "_")

  rustc_artifact(target_name) {
    target_type = "shared_library"
    crate_root = source_root
    clippy_crate_type = "dylib"
    crate_name = _crate_name
    original_target_name = _original_target_name
    pass_through = {
      forward_variables_from(invoker,
                             [
                               "data_deps",
                               "exclude_toolchain_tags",
                               "output_dir",
                               "testonly",
                               "visibility",
                             ])

      # Due to what is arguably a bug in the Rust compiler, if it sees libfoo.so
      # in a dependency search directory, it assumes it is the same thing as the
      # foo Rust crate. This creates problems, so we use a different output_dir
      # to separate the libraries in build directories.
      if (!defined(output_dir)) {
        output_dir = "$root_out_dir/rust-shared"
      }
      assert(
          output_dir != root_out_dir,
          "Specifying root_out_dir as the output_dir of a Rust dylib is unsupported. Choose a directory that won't have libraries of the same name from other languages.")

      # TODO: maybe just use target_name instead?
      output_name = _crate_name
      crate_type = "dylib"

      # TODO(https://fxbug.dev/42069148): Remove "--undefined-version" logic when
      # issue resolved upstream.
      if (is_fuchsia) {
        rustflags = [ "-Clink-arg=--undefined-version" ]
      } else if (is_linux) {
        rustflags = [ "-Clink-arg=-Wl,--undefined-version" ]
      }
    }

    configs = []
    configs = invoker.configs

    deps = []
    if (defined(invoker.deps)) {
      deps += invoker.deps
    }

    forward_variables_from(invoker,
                           [
                             "disable_rbe",
                             "disable_clippy",
                             "edition",
                             "enforce_source_listing",
                             "features",
                             "inputs",
                             "sources",
                           ])

    # Avoid walking into data_deps when checking component manifest expected includes.
    metadata = {
      expect_includes_barrier = deps
    }
  }
}