From 72e914069c6bde59c9999bcc80e08bc3aaca4dde Mon Sep 17 00:00:00 2001
From: Jorge Aparicio <jorge@japaric.io>
Date: Sat, 25 Aug 2018 19:26:05 +0200
Subject: [PATCH] use LLD as the default linker

closes #39
---
 .cargo/config | 45 +++++++++++++++++++++++++++++++++++++--------
 src/lib.rs    |  9 +++++----
 2 files changed, 42 insertions(+), 12 deletions(-)

diff --git a/.cargo/config b/.cargo/config
index 5999ced..b84a4d2 100644
--- a/.cargo/config
+++ b/.cargo/config
@@ -1,27 +1,56 @@
 [target.thumbv6m-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Wl,-Tlink.x",
-  "-C", "link-arg=-nostartfiles",
+  # LLD (shipped with the Rust toolchain) is used as the default linker
+  "-C", "link-arg=-Tlink.x",
+
+  # if you run into problems with LLD switch to the GNU linker by commenting out
+  # this line
+  # "-C", "linker=arm-none-eabi-ld",
+
+  # if you need to link to pre-compiled C libraries provided by a C toolchain
+  # use GCC as the linker by commenting out both lines above and then
+  # uncommenting the three lines below
+  # "-C", "linker=arm-none-eabi-gcc",
+  # "-C", "link-arg=-Wl,-Tlink.x",
+  # "-C", "link-arg=-nostartfiles",
 ]
 
 [target.thumbv7m-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Wl,-Tlink.x",
-  "-C", "link-arg=-nostartfiles",
+  # the comments under `[target.thumbv6m-none-eabi]` also apply here
+  "-C", "link-arg=-Tlink.x",
+
+  # "-C", "linker=arm-none-eabi-ld",
+
+  # "-C", "linker=arm-none-eabi-gcc",
+  # "-C", "link-arg=-Wl,-Tlink.x",
+  # "-C", "link-arg=-nostartfiles",
 ]
 
 [target.thumbv7em-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Wl,-Tlink.x",
-  "-C", "link-arg=-nostartfiles",
+  # the comments under `[target.thumbv6m-none-eabi]` also apply here
+  "-C", "link-arg=-Tlink.x",
+
+  # "-C", "linker=arm-none-eabi-ld",
+
+  # "-C", "linker=arm-none-eabi-gcc",
+  # "-C", "link-arg=-Wl,-Tlink.x",
+  # "-C", "link-arg=-nostartfiles",
 ]
 
 [target.thumbv7em-none-eabihf]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Wl,-Tlink.x",
-  "-C", "link-arg=-nostartfiles",
+  # the comments under `[target.thumbv6m-none-eabi]` also apply here
+  "-C", "link-arg=-Tlink.x",
+
+  # "-C", "linker=arm-none-eabi-ld",
+
+  # "-C", "linker=arm-none-eabi-gcc",
+  # "-C", "link-arg=-Wl,-Tlink.x",
+  # "-C", "link-arg=-nostartfiles",
 ]
diff --git a/src/lib.rs b/src/lib.rs
index 686b362..9246535 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -4,7 +4,6 @@
 //!
 //! - Nightly Rust toolchain newer than `nightly-2018-04-08`: `rustup default nightly`
 //! - Cargo `clone` subcommand: `cargo install cargo-clone`
-//! - ARM toolchain: `sudo apt-get install gcc-arm-none-eabi` (on Ubuntu)
 //! - GDB: `sudo apt-get install gdb-arm-none-eabi` (on Ubuntu)
 //! - OpenOCD: `sudo apt-get install OpenOCD` (on Ubuntu)
 //! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
@@ -179,11 +178,13 @@
 //! ``` text
 //! $ cargo build
 //! Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
-//! error: linking with `arm-none-eabi-ld` failed: exit code: 1
+//! error: linking with `rust-lld` failed: exit code: 1
 //! |
-//! = note: "arm-none-eabi-gcc" "-L" (..)
+//! = note: "rust-lld" "-flavor" "gnu" "-L" (..)
+//! (..)
+//!  = note: rust-lld: error: section '.vector_table' will not fit in region 'FLASH': overflowed by X bytes
+//!          rust-lld: error: section '.vector_table' will not fit in region 'FLASH': overflowed by Y bytes
 //! (..)
-//!           (..)/ld: region `FLASH' overflowed by XXX bytes
 //! ```
 //!
 //! Solution: Specify your device memory layout in the `memory.x` linker script. See [Usage]