rust/src/doc/trpl/advanced-linking.md

% Advanced Linking

The common cases of linking with Rust have been covered earlier in this book,
but supporting the range of linking possibilities made available by other
languages is important for Rust to achieve seamless interaction with native
libraries.

# Link args

There is one other way to tell `rustc` how to customize linking, and that is via
the `link_args` attribute. This attribute is applied to `extern` blocks and
specifies raw flags which need to get passed to the linker when producing an
artifact. An example usage would be:

``` no_run
#![feature(link_args)]

#[link_args = "-foo -bar -baz"]
extern {}
# fn main() {}
```

Note that this feature is currently hidden behind the `feature(link_args)` gate
because this is not a sanctioned way of performing linking. Right now `rustc`
shells out to the system linker, so it makes sense to provide extra command line
arguments, but this will not always be the case. In the future `rustc` may use
LLVM directly to link native libraries, in which case `link_args` will have no
meaning.

It is highly recommended to *not* use this attribute, and rather use the more
formal `#[link(...)]` attribute on `extern` blocks instead.

# Static linking

Static linking refers to the process of creating output that contain all
required libraries and so don't need libraries installed on every system where
you want to use your compiled project. Pure-Rust dependencies are statically
linked by default so you can use created binaries and libraries without
installing the Rust everywhere. By contrast, native libraries
(e.g. `libc` and `libm`) usually dynamically linked, but it is possible to
change this and statically link them as well.

Linking is a very platform dependent topic - on some platforms, static linking
may not be possible at all! This section assumes some basic familiarity with
linking on your platform on choice.

## Linux

By default, all Rust programs on Linux will link to the system `libc` along with
a number of other libraries. Let's look at an example on a 64-bit linux machine
with GCC and `glibc` (by far the most common `libc` on Linux):

``` text
$ cat example.rs
fn main() {}
$ rustc example.rs
$ ldd example
        linux-vdso.so.1 =>  (0x00007ffd565fd000)
        libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007fa81889c000)
        libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007fa81867e000)
        librt.so.1 => /lib/x86_64-linux-gnu/librt.so.1 (0x00007fa818475000)
        libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007fa81825f000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fa817e9a000)
        /lib64/ld-linux-x86-64.so.2 (0x00007fa818cf9000)
        libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007fa817b93000)
```

Dynamic linking on Linux can be undesirable if you wish to use new library
features on old systems or target systems which do not have the required
dependencies for your program to run.

The first step in using static linking is examining the Rust linking arguments
with an option to rustc. Newlines have been added for readability:

``` text
$ rustc example.rs -Z print-link-args
"cc"
    "-Wl,--as-needed"
    "-m64"
    [...]
    "-o" "example"
    "example.o"
    "-Wl,--whole-archive" "-lmorestack" "-Wl,--no-whole-archive"
    "-Wl,--gc-sections"
    "-pie"
    "-nodefaultlibs"
    [...]
    "-Wl,--whole-archive" "-Wl,-Bstatic"
    "-Wl,--no-whole-archive" "-Wl,-Bdynamic"
    "-ldl" "-lpthread" "-lrt" "-lgcc_s" "-lpthread" "-lc" "-lm" "-lcompiler-rt"
```

Arguments with a `-L` before them set up the linker search path and arguments
ending with `.rlib` are linking Rust crates statically into your application.
Neither of these are relevent for static linking so have been ommitted.

The first step in being able to statically link is to obtain an object file.
This can be achieved with `rustc --emit obj example.rs`, and creates a file
called `example.o`, which you can see being passed in the command line above -
rustc automatically deletes it when finished with it by default. As you now have
the object file, you should be able to run the link command obtained with
`print-link-args` to create perform the linking stage yourself.

In order to statically link, there are a number of changes you must make. Below
is the command required to perform a static link; we will go through them each
in turn.

``` text
$ rustc example.rs -Z print-link-args
"cc"
    "-static"
    "-m64"
    [...]
    "-o" "example"
    "example.o"
    "-Wl,--whole-archive" "-lmorestack" "-Wl,--no-whole-archive"
    "-Wl,--gc-sections"
    "-nodefaultlibs"
    [...]
    "-Wl,--whole-archive"
    "-Wl,--no-whole-archive"
    "-ldl" "-lpthread" "-lrt" "-lgcc_eh" "-lpthread" "-lc" "-lm" "-lcompiler-rt"
```

 - `-static` was added - this is the signal to the compiler to use a static
   glibc, among other things
 - `-Wl,--as-needed` was removed - this can be left in, but is unnecessary
   as it only applies to dynamic librares
 - `-pie` was removed - this is not compatible with static binaries
 - both `-Wl,-B*` options were removed - everything will be linked statically,
   so informing the linker of how certain libraries should be linked is not
   appropriate
 - `-lgcc_s` was changed to `-lgcc_eh` - `gcc_s` is the GCC support library,
   which Rust uses for unwinding support. This is only available as a dynamic
   library, so we must specify the static version of the library providing
   unwinding support.

By running this command, you will likely see some warnings like

``` text
warning: Using 'getpwuid_r' in statically linked applications requires at runtime the shared libraries from the glibc version used for linking
```

These should be considered carefully! They indicate calls in glibc which
*cannot* be statically linked without significant extra effort. An application
using these calls will find it is not as portable as 'static binary' would imply.
Rust supports targeting musl as an alternative libc to be able to fully
statically link these calls.

As we are confident that our code does not use these calls, we can now see the
fruits of our labour:

```
$ ldd example
        not a dynamic executable
```

This binary can be copied to virtually any 64-bit Linux machine and work
without requiring external libraries.