Allow adding a linker script in build.rs

[xobs]

Some kinds of targets such as embedded devices have special requirements when it comes to linking. On these devices, a linker script is required in order to load various classes of memory at specific offsets. Without this value, a default linker script is used, which very rarely works on embedded targets.

The current approach (decided in rust-embedded/wg#24 (comment)) is to create a per-project .cargo/config file to pass flags to rustc, however this suffers from a number of drawbacks:

1. These are overridden if the RUSTFLAGS variable is set
2. This file depends on the cwd, which means e.g. cargo build --target riscv32imac-unknown-none-elf -p kernel can pick up different linker scripts depending on the current directory (Support linker scripts in Cargo.toml / build.rs rust-embedded/wg#432 (comment))
3. This file must be copied into every single project, precluding it from being provided by an -rt crate.

It would be nice to be able to include a linker script as an artifact from build.rs by echoing a path to stdout. All of the current examples require users to manually copy this file (e.g. cortex-m-rt or riscv-rt), and the end result of not including this file is either a broken binary or a failed build.

By allowing build.rs to specify additional linker files, we solve several problems:

1. Runtime crates such as cortex-m-rt or riscv-rt can bundle their own linker scripts using their own naming convention for e.g. .bss or .data
2. We can omit the (unversioned?) .cargo/config file
3. The flag can be translated as appropriate depending on the linker
4. Different crates in a workspace can be built with different linker flags, for example an operating system loader, kernel, and runtime

Appending linker flags to the output seems like it should be similar to how library crates can append libraries to the output, and it shouldn't be considered an error if multiple linker files are included. In fact, the approach that is taken by the current -rt libraries is to include an mcu-specific linker script alongside an arch-specific crate.

Disadvantages I can see from this approach are:

1. How do we deal with translating linker scripts across linkers? For example, msvc only supports /REBASE, not full scripts.
2. What about linkers that only accept one linker script?

[jonas-schievink]

The easiest way to support this would be to allow passing arbitrary rustc flags via cargo:rustc-flags=FLAGS. Right now that's limited to -L and -l, while .cargo/config can pass anything.

The flag can be translated as appropriate depending on the linker

This is not really something we need since linker scripts are a GNU LD invention anyways, so linkers supporting them mimic GNU LD's command line options as well.

In fact, the approach that is taken by the current -rt libraries is to include an mcu-specific linker script alongside an arch-specific crate.

Note that we do this by having link.x include device.x and memory.x (where the device.x include is injected by the existing build.rs there), so we don't strictly need the ability to pass multiple linker scripts.

[stdrc]

@xobs This is solved by #8441.

Just pass -Zextra-link-arg flag to cargo and print cargo:rustc-link-arg=-Tpath/to/linker.ld in build.rs.

[xobs]

I've created a repository to demonstrate that this does make things work: https://github.com/xobs/rust-extra-link-arg-test

What is the process now? Should this issue be closed, or should it stay until it's stabilized?

[AaronKutch]

These are overridden if the RUSTFLAGS variable is set

I could not figure out for the life of me why I couldn't get the GitHub Actions CI to build a project that I could replicate everywhere else, until today I happened upon this thread with this detail. I had env: RUSTFLAGS: -D warnings at the top of the workflow file, and refactoring so that the flag did not appear in the particular build fixed it.

[anderslanglands]

We need this functionality in order to add a link statement to the end of the linker invocation for building a crate that links against libstdc++ on CentOS 7 using devtoolset.

Does anyone know when this might be stabilised?

[xobs]

This now has an issue tracking stabilization: #9426

[hydra]

I've created a repository to demonstrate that this does make things work: https://github.com/xobs/rust-extra-link-arg-test

I tried this today, and it didn't work using a very recent cargo build.

xobs/rust-extra-link-arg-test#1

[xobs]

It looks like it will be part of Rust 1.56: https://github.com/rust-lang/cargo/blob/rust-1.56.0/src/cargo/core/features.rs#L879

[MrMino]

I guess this can be closed now?