build/rust/rustc_library.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 library
#
# 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>
#
#   crate_name
#     Same as name. This param is set by auto-synced targets by bazel2gn. This
#     matches the name of the same field in Bazel.
#
#   version
#     Semver version of the crate as seen on crates.io.
#
#   edition
#     Edition of the Rust language to be used. See
#     https://doc.rust-lang.org/edition-guide/editions/index.html for more info on rust editions.
#
#   configs (optional)
#     A list of config labels applying to this target.
#
#   public_configs (optional)
#     A list of public 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>",
#
#   public_deps (optional)
#     List of GN targets on which this crate depends publicly.
#
#   test_configs (optional)
#     List of GN config targets to pass to the compilation of this crate's
#     tests.
#
#   test_vars (optional)
#     A scope of variables to forward to the test target.
#
#   test_deps (optional)
#     List of rust_library GN targets on which this crate's tests depend.
#
#   non_test_deps (optional)
#     List of rust_library GN targets on which this crate depends but not its
#     tests. This can be used to replace a dependency between the test and
#     library targets. It's an error to provide this when with_unit_tests is
#     false.
#
#   non_rust_deps (optional)
#     List of non-rust_library GN targets on which this crate depends.
#     Obsolete. Please use deps instead.
#
#   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"'
#
#   check_cfgs (optional)
#     A list of valid configurations for the target.
#     Passed to rustc as '--check-cfg=cfg(###)'.
#     Not specifying or using an empty list disables configuration checking.
#     See https://doc.rust-lang.org/nightly/rustc/check-cfg.html for the syntax.
#
#   rustenv (optional)
#     A list of environment variables that will be set when running the rust
#     compiler. These can be accessed at compile time with
#     [`std::env!`](https://doc.rust-lang.org/stable/std/macro.env.html)
#
#   output_dir (optional)
#     Directory that the resulting library should be placed in.
#     See: `gn help output_dir`
#
#   pool (optional)
#     Override the default concurrency pool when building the Rust library.
#     e.g. extremely high memory jobs run locally could use
#     "//build/config:highmem".
#
#   disable_rbe (optional)
#     Set to true to force this library to build locally, overriding the global `rust_rbe_enable`.
#     If with_unit_tests is also true, this setting applies to the unit test
#     as well, unless overridden by `test_disable_rbe`.
#
#   test_disable_rbe (optional)
#     Set to true to force the library's test to build locally, overriding
#     `disable_rbe` and the global `rust_rbe_enable`.
#
#   disable_clippy (optional)
#     Don't run clippy on this target.
#
#   quiet_clippy (boolean, optional)
#     Passed through to rustc_artifact(), see that template for documentation.
#
#   disable_rustdoc (optional)
#     Don't add this target to https://fuchsia.dev/go/rustdoc
#
#   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.
#
#   metadata (optional)
#     The usual GN meaning.
#
#   assert_no_deps (optional)
#     Ensure no deps on these targets, see [assert_no_deps](https://gn.googlesource.com/gn/+/main/docs/reference.md#var_assert_no_deps)
#
#   applicable_licenses (optional)
#     The usual GN meaning.
#
#
#   The following fields are only used by Bazel-converted targets.
#   See //build/tools/bazel2gn/README.md for details.
#
#      proc_macro_deps (optional)
#        For sources used by go:embed, has the same semantics as deps in GN.
#
#
# Example of usage:
#
#   rustc_library("foo-bar") {
#     deps = [
#       "//garnet/public/rust/bar",
#       "//third_party/rust_crates:argh",
#       "//third_party/rust_crates:serde",
#       "//third_party/rust_crates:slab",
#     ]
#     with_unit_tests = true
#     sources = [ "src/lib.rs" ]
#   }
#
# Example of using the outputs of the above:
#
#   test_package("foo-bar-tests") {
#     deps = [
#       ":foo-bar_test",
#     ]
#
#    tests = [
#      {
#        name = "foo_bar_lib_test"
#      }
#    ]
#
template("rustc_library") {
  not_needed(invoker, [ "version" ])
  if (defined(invoker.original_target_name)) {
    _original_target_name = invoker.original_target_name
  } else {
    _original_target_name = target_name
  }

  _crate_name = target_name
  assert(
      !(defined(invoker.name) && defined(invoker.crate_name)),
      "name and crate_name should not be defined at the same time, they mean the same thing")
  if (defined(invoker.name)) {
    _crate_name = invoker.name
  }
  if (defined(invoker.crate_name)) {
    _crate_name = invoker.crate_name
  }
  _crate_name = string_replace(_crate_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) {
    rustc_test_internal("${target_name}_test") {
      name = _crate_name + "_lib_test"
      original_target_name = target_name

      # It's valid for the test to use dependencies that were declared
      # `assert_no_deps`.
      forward_variables_from(invoker,
                             "*",
                             [
                               "assert_no_deps",
                               "disable_rustdoc",
                               "name",
                               "non_test_deps",
                               "output_name",
                               "public_configs",
                               "test_disable_rbe",
                             ])
      if (defined(invoker.test_disable_rbe)) {
        disable_rbe = invoker.test_disable_rbe
      }

      # Make sure any public configs on the library are applied to the test as
      # well, though no need at this time to forward them as public configs on
      # the test itself.
      if (defined(invoker.public_configs)) {
        if (!defined(configs)) {
          configs = []
        }
        configs += invoker.public_configs
      }
    }
  }

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

  rustc_artifact(target_name) {
    forward_variables_from(invoker,
                           [
                             "aliased_deps",
                             "applicable_licenses",
                             "assert_no_deps",
                             "check_cfgs",
                             "configs",
                             "data_deps",
                             "define_rustdoc_test_override",
                             "rustdoc_parts_dir",
                             "disable_clippy",
                             "disable_rbe",
                             "edition",
                             "enforce_source_listing",
                             "features",
                             "inputs",
                             "output_dir",
                             "output_name",
                             "pool",
                             "public_configs",
                             "public_deps",
                             "quiet_clippy",
                             "rustdoc_args",
                             "rustdoc_out_dir",
                             "rustenv",
                             "rustflags",
                             "sources",
                             "testonly",
                             "visibility",
                             "zip_rustdoc_to",
                           ])

    target_type = "rust_library"
    crate_root = source_root
    crate_type = "rlib"
    crate_name = _crate_name
    original_target_name = _original_target_name
    if (!defined(output_name)) {
      output_name = crate_name
    }

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

    if (defined(invoker.non_test_deps)) {
      assert(defined(invoker.with_unit_tests) && invoker.with_unit_tests,
             "use deps if not generating unit tests")
      deps += invoker.non_test_deps
    }

    # TODO(https://fxbug.dev/42120123) remove "non_rust_deps"
    if (defined(invoker.non_rust_deps)) {
      deps += invoker.non_rust_deps
    }

    if (defined(invoker.proc_macro_deps)) {
      deps += invoker.proc_macro_deps
    }

    # Avoid walking into data_deps when checking component manifest expected includes.
    metadata = {
      if (defined(invoker.metadata)) {
        forward_variables_from(invoker.metadata, "*")
      }
      if (defined(invoker.disable_rustdoc)) {
        disable_rustdoc = [ invoker.disable_rustdoc ]
      }
      expect_includes_barrier = deps
    }
  }
}