src/doc/reference/src/linkage.md

   1 # Linkage
   2
   3 The Rust compiler supports various methods to link crates together both
   4 statically and dynamically. This section will explore the various methods to
   5 link Rust crates together, and more information about native libraries can be
   6 found in the [FFI section of the book][ffi].
   7
   8 [ffi]: ../book/ffi.html
   9
  10 In one session of compilation, the compiler can generate multiple artifacts
  11 through the usage of either command line flags or the `crate_type` attribute.
  12 If one or more command line flags are specified, all `crate_type` attributes will
  13 be ignored in favor of only building the artifacts specified by command line.
  14
  15 * `--crate-type=bin`, `#[crate_type = "bin"]` - A runnable executable will be
  16   produced. This requires that there is a `main` function in the crate which
  17   will be run when the program begins executing. This will link in all Rust and
  18   native dependencies, producing a distributable binary.
  19
  20 * `--crate-type=lib`, `#[crate_type = "lib"]` - A Rust library will be produced.
  21   This is an ambiguous concept as to what exactly is produced because a library
  22   can manifest itself in several forms. The purpose of this generic `lib` option
  23   is to generate the "compiler recommended" style of library. The output library
  24   will always be usable by rustc, but the actual type of library may change from
  25   time-to-time. The remaining output types are all different flavors of
  26   libraries, and the `lib` type can be seen as an alias for one of them (but the
  27   actual one is compiler-defined).
  28
  29 * `--crate-type=dylib`, `#[crate_type = "dylib"]` - A dynamic Rust library will
  30   be produced. This is different from the `lib` output type in that this forces
  31   dynamic library generation. The resulting dynamic library can be used as a
  32   dependency for other libraries and/or executables. This output type will
  33   create `*.so` files on linux, `*.dylib` files on osx, and `*.dll` files on
  34   windows.
  35
  36 * `--crate-type=staticlib`, `#[crate_type = "staticlib"]` - A static system
  37   library will be produced. This is different from other library outputs in that
  38   the Rust compiler will never attempt to link to `staticlib` outputs. The
  39   purpose of this output type is to create a static library containing all of
  40   the local crate's code along with all upstream dependencies. The static
  41   library is actually a `*.a` archive on linux and osx and a `*.lib` file on
  42   windows. This format is recommended for use in situations such as linking
  43   Rust code into an existing non-Rust application because it will not have
  44   dynamic dependencies on other Rust code.
  45
  46 * `--crate-type=cdylib`, `#[crate_type = "cdylib"]` - A dynamic system
  47   library will be produced.  This is used when compiling Rust code as
  48   a dynamic library to be loaded from another language.  This output type will
  49   create `*.so` files on Linux, `*.dylib` files on macOS, and `*.dll` files on
  50   Windows.
  51
  52 * `--crate-type=rlib`, `#[crate_type = "rlib"]` - A "Rust library" file will be
  53   produced. This is used as an intermediate artifact and can be thought of as a
  54   "static Rust library". These `rlib` files, unlike `staticlib` files, are
  55   interpreted by the Rust compiler in future linkage. This essentially means
  56   that `rustc` will look for metadata in `rlib` files like it looks for metadata
  57   in dynamic libraries. This form of output is used to produce statically linked
  58   executables as well as `staticlib` outputs.
  59
  60 * `--crate-type=proc-macro`, `#[crate_type = "proc-macro"]` - The output
  61   produced is not specified, but if a `-L` path is provided to it then the
  62   compiler will recognize the output artifacts as a macro and it can be loaded
  63   for a program. If a crate is compiled with the `proc-macro` crate type it
  64   will forbid exporting any items in the crate other than those functions
  65   tagged `#[proc_macro_derive]` and those functions must also be placed at the
  66   crate root. Finally, the compiler will automatically set the
  67   `cfg(proc_macro)` annotation whenever any crate type of a compilation is the
  68   `proc-macro` crate type.
  69
  70 Note that these outputs are stackable in the sense that if multiple are
  71 specified, then the compiler will produce each form of output at once without
  72 having to recompile. However, this only applies for outputs specified by the
  73 same method. If only `crate_type` attributes are specified, then they will all
  74 be built, but if one or more `--crate-type` command line flags are specified,
  75 then only those outputs will be built.
  76
  77 With all these different kinds of outputs, if crate A depends on crate B, then
  78 the compiler could find B in various different forms throughout the system. The
  79 only forms looked for by the compiler, however, are the `rlib` format and the
  80 dynamic library format. With these two options for a dependent library, the
  81 compiler must at some point make a choice between these two formats. With this
  82 in mind, the compiler follows these rules when determining what format of
  83 dependencies will be used:
  84
  85 1. If a static library is being produced, all upstream dependencies are
  86    required to be available in `rlib` formats. This requirement stems from the
  87    reason that a dynamic library cannot be converted into a static format.
  88
  89    Note that it is impossible to link in native dynamic dependencies to a static
  90    library, and in this case warnings will be printed about all unlinked native
  91    dynamic dependencies.
  92
  93 2. If an `rlib` file is being produced, then there are no restrictions on what
  94    format the upstream dependencies are available in. It is simply required that
  95    all upstream dependencies be available for reading metadata from.
  96
  97    The reason for this is that `rlib` files do not contain any of their upstream
  98    dependencies. It wouldn't be very efficient for all `rlib` files to contain a
  99    copy of `libstd.rlib`!
 100
 101 3. If an executable is being produced and the `-C prefer-dynamic` flag is not
 102    specified, then dependencies are first attempted to be found in the `rlib`
 103    format. If some dependencies are not available in an rlib format, then
 104    dynamic linking is attempted (see below).
 105
 106 4. If a dynamic library or an executable that is being dynamically linked is
 107    being produced, then the compiler will attempt to reconcile the available
 108    dependencies in either the rlib or dylib format to create a final product.
 109
 110    A major goal of the compiler is to ensure that a library never appears more
 111    than once in any artifact. For example, if dynamic libraries B and C were
 112    each statically linked to library A, then a crate could not link to B and C
 113    together because there would be two copies of A. The compiler allows mixing
 114    the rlib and dylib formats, but this restriction must be satisfied.
 115
 116    The compiler currently implements no method of hinting what format a library
 117    should be linked with. When dynamically linking, the compiler will attempt to
 118    maximize dynamic dependencies while still allowing some dependencies to be
 119    linked in via an rlib.
 120
 121    For most situations, having all libraries available as a dylib is recommended
 122    if dynamically linking. For other situations, the compiler will emit a
 123    warning if it is unable to determine which formats to link each library with.
 124
 125 In general, `--crate-type=bin` or `--crate-type=lib` should be sufficient for
 126 all compilation needs, and the other options are just available if more
 127 fine-grained control is desired over the output format of a Rust crate.