Help/prop_sf/Rust_EMIT.rst

Rust_EMIT
---------

.. versionadded:: 4.4

.. note::
   Experimental. Gated by ``CMAKE_EXPERIMENTAL_RUST``.

This property controls the type of output generated by the Rust compiler. Can
be one of several values:

``link``
  This is the default if the property is not set. The crate will be compiled
  into an `rlib` file, e.g.: ``libfile.rs.rlib``

  .. note::
     CMake will automatically prefix the generated ``rlib`` file
     with ``lib`` as the Rust compiler always requires such a
     prefix for external crates.

``obj``
  Generate a native object file, e.g.: ``file.rs.o``

``asm``
  Generate an assembly file, e.g.: ``file.rs.s``

.. note::
    The ``obj`` and ``asm`` output types are known to have the following
    limitations:

    * When enabled, the Rust compiler disables multiple codegen units and
      ThinLTO. Depending on the situation, this can affect the generated code,
      optimizations. It also reduce the internal parallelism inside and the
      compiler and can reduce the effectiveness of incremental rebuilds.
    * The generated ``obj`` files cannot be used as external crates, so other
      Rust code can only use C-style API from them.
    * The generated ``obj`` files cannot be linked as-is with native linkers,
      additional crates from the Rust toolchain needs to linked too. The actual
      crates to link depend on the code and compiler options.