build/rust/rust_static_library.gni

# Copyright 2021 The Chromium 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/rust_target.gni")

# Defines a Rust static library which can be used by downstream Rust or C++
# targets. This is a single Rust compilation unit consisting of potentially
# multiple .rs files.
#
# We term this 'rust_static_library' because it is used most analogously
# to a C++ 'static_library' in Chromium. Like the C++ one, it can be compiled
# independently into an intermediate linking target. The output contains the
# object file(s) of the GN target's sources, and not its dependencies.
#
# Important: downstream C++ targets should NOT depend upon this
# type of target. Instead they should append the suffix "_cpp_bindings"
# when adding this to their deps:
#
#   deps += [ "//example:foo_bar_cpp_bindings" ]
#
# This arranges to ensure that any downstream C++ linker invocations
# are supplied with the required extra bits to include Rust code; for
# instance, the Rust standard library.
#
# Downstream Rust targets should depend on this rust_static_library directly.
#
# Parameters
#
#   sources
#     List of source files which this crate is allowed to compile, which is
#     used to determine the impact of source code changes on other GN targets.
#     This is not used by the Rust compiler, as it discovers source files by
#     following `mod` declarations starting at the `crate_root`. The
#     discovered source files must match this list. (This is not yet enforced,
#     but will be.)
#
#   epoch (optional)
#     The major version of the library, which is used to differentiate between
#     multiple versions of the same library name. This includes all leading 0s
#     and the first non-zero value in the crate's version. This should be left
#     as the default, which is "0", for first-party code unless there are
#     multiple versions of a crate present. For third-party code, the version
#     epoch (matching the directory it is found in) should be specified.
#
#     Examples:
#       1.0.2 => epoch = "1"
#       4.2.0 => epoch = "4"
#       0.2.7 => epoch = "0.2"
#       0.0.3 => epoch = "0.0.3"
#
#   edition (optional)
#     Edition of the Rust language to be used.
#     Options are "2015", "2018" and "2021". Defaults to "2021".
#
#   configs (optional)
#     A list of config labels (in the GN meaning) applying to this target.
#
#   rustflags (optional)
#     Explicit flags for rustc command line. (Use 'edition' or 'features'
#     where possible).
#
#   deps (optional)
#     List of GN targets on which this crate depends. These may be Rust
#     or non-Rust targets.
#
#   test_deps (optional)
#     List of GN targets on which this crate's tests depend, in addition
#     to deps.
#
#   mutually_dependent_target (optional)
#     If this Rust code is intrinsically paired with some C/C++ code,
#     with bidirectional calls between the two, then this would
#     be a circular dependency. GN does not allow circular dependencies,
#     (other than for header files per allow_circular_includes_from).
#     But this is common for a 'component' which has both Rust and C++
#     code. You should structure things such that the C++ code depends
#     on the Rust code in the normal way:
#        static_library("cpp_stuff") {
#          deps = [ "rust_stuff_cpp_bindings" ]
#          # ..
#        }
#     but that the Rust target also notes the C++ target using this
#     'mutually_dependent_target' parameter.
#        rust_static_library("rust_stuff") {
#          mutually_dependent_target = "cpp_stuff"
#          # ..
#        }
#
#     The resultant behavior:
#     * Downstream C++ targets should depend on the main C++ target
#       ("cpp_stuff" in the above example). They'll come to depend on
#       both Rust and C++ code (plus the Rust standard library,
#       noted above).
#     * Downstream Rust targets should depend on the Rust target
#       ("rust_stuff"). They'll come to depend on both Rust and C++
#       code, because this "mutually_dependent_target" will be put into
#       their dependency list.
#     * Rust unit tests, similarly, will depend on the Rust and C++
#       code.
#     Note that this arrangement carefully avoids actual circular
#     dependencies.
#
#   skip_unit_tests (optional)
#     Avoids building unit tests associated with this Rust crate. Normally,
#     this template will create a `<name>_unittests` executable in the output
#     directory; this behavior is suppressed if this flag is set to true.
#
#   unit_test_target (optional)
#     Overrides the default name for the unit tests target
#
#   crate_root (optional)
#     Location of the crate root.
#     This defaults to `./src/lib.rs` 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. Each feature in the list will be passed to rustc as
#     '--cfg feature=XXX'
#
#   cxx_bindings (optional)
#     A list of Rust files which contain #[cxx::bridge] mods and should
#     therefore have C++ bindings generated. See https://cxx.rs.
#     This will automatically add appropriate dependencies: there's no
#     need to depend on the cxx crate or any generated bindings.
#
#   native_header_deps (optional)
#     If cxx_bindings is defined, this dictates the C++ header
#     targets on which the generated C++ code depends.
#
#   visibility (optional)
#   rustflags (optional)
#   crate_name (optional)
#     Per the usual gn meaning for Rust targets.
#
# Example of usage:
#
#   rust_static_library("foo_bar") {
#     deps = [
#       "//boo/public/rust/bar",
#       "//third_party/rust/crates:argh",
#       "//third_party/rust/crates:serde",
#       "//third_party/rust/crates:slab",
#     ]
#     sources = [ "src/lib.rs" ]
#   }
#
# This template is intended to serve the same purpose as 'rustc_library'
# in Fuchsia.
template("rust_static_library") {
  exclude_forwards = TESTONLY_AND_VISIBILITY + [ "configs" ]
  rust_target(target_name) {
    forward_variables_from(invoker, "*", exclude_forwards)
    forward_variables_from(invoker, TESTONLY_AND_VISIBILITY)
    if (defined(invoker.configs)) {
      library_configs = []
      library_configs = invoker.configs
    }
    target_type = "rust_library"
    create_cpp_groups = true
  }
}

set_defaults("rust_static_library") {
  configs = default_compiler_configs
}