rust_static_library.gni 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159
  1. # Copyright 2021 The Chromium Authors. All rights reserved.
  2. # Use of this source code is governed by a BSD-style license that can be
  3. # found in the LICENSE file.
  4. import("//build/rust/rust_target.gni")
  5. # Defines a Rust static library which can be used by downstream Rust or C++
  6. # targets. This is a single Rust compilation unit consisting of potentially
  7. # multiple .rs files.
  8. #
  9. # We term this 'rust_static_library' because it is used most analogously
  10. # to a C++ 'static_library' in Chromium. Like the C++ one, it can be compiled
  11. # independently into an intermediate linking target. The output contains the
  12. # object file(s) of the GN target's sources, and not its dependencies.
  13. #
  14. # Parameters
  15. #
  16. # sources
  17. # List of source files which this crate is allowed to compile, which is
  18. # used to determine the impact of source code changes on other GN targets.
  19. # This is not used by the Rust compiler, as it discovers source files by
  20. # following `mod` declarations starting at the `crate_root`. The
  21. # discovered source files must match this list. (This is not yet enforced,
  22. # but will be.)
  23. #
  24. # epoch (optional)
  25. # The major version of the library, which is used to differentiate between
  26. # multiple versions of the same library name. This includes all leading 0s
  27. # and the first non-zero value in the crate's version. This should be left
  28. # as the default, which is "0", for first-party code unless there are
  29. # multiple versions of a crate present. For third-party code, the version
  30. # epoch (matching the directory it is found in) should be specified.
  31. #
  32. # Examples:
  33. # 1.0.2 => epoch = "1"
  34. # 4.2.0 => epoch = "4"
  35. # 0.2.7 => epoch = "0.2"
  36. # 0.0.3 => epoch = "0.0.3"
  37. #
  38. # edition (optional)
  39. # Edition of the Rust language to be used.
  40. # Options are "2015", "2018" and "2021". Defaults to "2021".
  41. #
  42. # configs (optional)
  43. # A list of config labels (in the GN meaning) applying to this target.
  44. #
  45. # rustflags (optional)
  46. # Explicit flags for rustc command line. (Use 'edition' or 'features'
  47. # where possible).
  48. #
  49. # deps (optional)
  50. # List of GN targets on which this crate depends. These may be Rust
  51. # or non-Rust targets.
  52. #
  53. # public_deps (optional)
  54. # List of GN targets on which this crate depends, and which are exported
  55. # into the dependency list of any crate that depends on it. Dependency
  56. # crates that appear in the public API should be included here.
  57. #
  58. # test_deps (optional)
  59. # List of GN targets on which this crate's tests depend, in addition
  60. # to deps.
  61. #
  62. # mutually_dependent_target (optional)
  63. # mutually_dependent_public_deps (optional)
  64. # These is for use by the mixed_target() template.
  65. #
  66. # If this Rust code is intrinsically paired with some C/C++ code,
  67. # with bidirectional calls between the two, then this would
  68. # be a circular dependency. GN does not allow circular dependencies,
  69. # (other than for header files per allow_circular_includes_from).
  70. # But this is common for a 'component' which has both Rust and C++
  71. # code. You should structure things such that the C++ code depends
  72. # on the Rust code in the normal way:
  73. # static_library("cpp_stuff") {
  74. # deps = [ "rust_stuff" ]
  75. # # ..
  76. # }
  77. # but that the Rust target also notes the C++ target using this
  78. # 'mutually_dependent_target' parameter.
  79. # rust_static_library("rust_stuff") {
  80. # mutually_dependent_target = "cpp_stuff"
  81. # mutually_dependent_public_deps = _cpp_stuff_public_deps
  82. # # ..
  83. # }
  84. #
  85. # This causes the Rust unit tests, if generated, to depend on the mutually
  86. # dependent target, since depending on the Rust code only would be
  87. # insufficient. And it allows any C++ bindings generated from the Rust code
  88. # to include headers from the mutually_dependent_target by depending on its
  89. # public_deps.
  90. #
  91. # build_native_rust_unit_tests (optional)
  92. # Builds native unit tests (under #[cfg(test)]) written inside the Rust
  93. # crate. This will create a `<name>_unittests` executable in the output
  94. # directory when set to true.
  95. #
  96. # unit_test_target (optional)
  97. # Overrides the default name for the unit tests target
  98. #
  99. # crate_root (optional)
  100. # Location of the crate root.
  101. # This defaults to `./src/lib.rs` and should only be changed when
  102. # absolutely necessary (such as in the case of generated code).
  103. #
  104. # features (optional)
  105. # A list of conditional compilation flags to enable. This can be used
  106. # to set features for crates built in-tree which are also published to
  107. # crates.io. Each feature in the list will be passed to rustc as
  108. # '--cfg feature=XXX'
  109. #
  110. # cxx_bindings (optional)
  111. # A list of Rust files which contain #[cxx::bridge] mods or
  112. # autocxx::include_cpp! macros and should therefore have C++ bindings
  113. # generated. See https://cxx.rs or https://google.github.io/autocxx/.
  114. # This will automatically add appropriate dependencies: there's no
  115. # need to depend on the cxx crate or any generated bindings.
  116. #
  117. # visibility (optional)
  118. # rustflags (optional)
  119. # crate_name (optional)
  120. # Per the usual gn meaning for Rust targets.
  121. #
  122. # inputs (optional)
  123. # Additional input files needed for compilation (such as `include!`ed files)
  124. #
  125. # test_inputs (optional)
  126. # Same as above but for the unit tests target
  127. #
  128. # Example of usage:
  129. #
  130. # rust_static_library("foo_bar") {
  131. # deps = [
  132. # "//boo/public/rust/bar",
  133. # "//third_party/rust/crates:argh",
  134. # "//third_party/rust/crates:serde",
  135. # "//third_party/rust/crates:slab",
  136. # ]
  137. # sources = [ "src/lib.rs" ]
  138. # }
  139. #
  140. # This template is intended to serve the same purpose as 'rustc_library'
  141. # in Fuchsia.
  142. template("rust_static_library") {
  143. exclude_forwards = TESTONLY_AND_VISIBILITY + [ "configs" ]
  144. rust_target(target_name) {
  145. forward_variables_from(invoker, "*", exclude_forwards)
  146. forward_variables_from(invoker, TESTONLY_AND_VISIBILITY)
  147. if (defined(invoker.configs)) {
  148. library_configs = []
  149. library_configs = invoker.configs
  150. }
  151. target_type = "rust_library"
  152. }
  153. }
  154. set_defaults("rust_static_library") {
  155. configs = default_compiler_configs
  156. }