v0.1.5

warn against using CARGO_INCREMENTAL

CHANGELOG.md

@@ -5,7 +5,24 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-## v0.1.3 - 2017-05-12
+## [v0.1.5] - 2017-05-16
+
+### Added
+
+- A warning about using CARGO_INCREMENTAL to the how to use and the
+  troubleshooting sections.
+
+## [v0.1.4] - 2017-05-13
+
+### Added
+
+- A dependencies section to the documentation
+
+### Changed
+
+- Extend troubleshooting section
+
+## [v0.1.3] - 2017-05-13
 
 ### Added
 
@@ -15,13 +32,13 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 - Bumped the cortex-m crate version to v0.2.6
 
-## v0.1.2 - 2017-05-07
+## [v0.1.2] - 2017-05-07
 
 ### Fixed
 
 - .gdbinit: jump to reset handler after loading the program.
 
-## v0.1.1 - 2017-04-27
+## [v0.1.1] - 2017-04-27
 
 ### Changed
 
@@ -33,7 +50,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.5...HEAD
+[v0.1.5]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.4...v0.1.5
+[v0.1.4]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.3...v0.1.4
 [v0.1.3]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.2...v0.1.3
 [v0.1.2]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.1...v0.1.2
 [v0.1.1]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.0...v0.1.1

Cargo.toml

@@ -6,7 +6,7 @@ keywords = ["arm", "cortex-m", "template"]
 license = "MIT OR Apache-2.0"
 name = "cortex-m-quickstart"
 repository = "https://github.com/japaric/cortex-m-quickstart"
-version = "0.1.3"
+version = "0.1.5"
 
 [dependencies]
 cortex-m = "0.2.6"

src/lib.rs

@@ -1,5 +1,15 @@
 //! A template for building applications for ARM Cortex-M microcontrollers
 //!
+//! # Dependencies
+//!
+//! - Nightly Rust toolchain: `rustup default nightly`
+//! - ARM linker: `sudo apt-get install binutils-arm-none-eabi`
+//! - Cargo `clone` subcommand: `cargo install cargo-clone`
+//! - GDB: `sudo apt-get install gdb-arm-none-eabi`
+//! - OpenOCD: `sudo apt-get install OpenOCD`
+//! - Xargo: `cargo install xargo`
+//! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
+//!
 //! # Usage
 //!
 //! - Clone this crate
@@ -64,12 +74,16 @@
 //! $ rm -r src/* && cp examples/hello.rs src/main.rs
 //! ```
 //!
+//! - Disable incremental compilation. It doesn't work for embedded development.
+//!   You'll hit nonsensical linker errors if you use it.
+//!
+//! ``` text
+//! $ unset CARGO_INCREMENTAL
+//! ```
+//!
 //! - Build the application
 //!
 //! ``` text
-//! # if not installed
-//! $ cargo install xargo
-//!
 //! # NOTE this command requires `arm-none-eabi-ld` to be in $PATH
 //! $ xargo build --release
 //!
@@ -201,6 +215,43 @@
 //!
 //! Solution: Use `xargo build`.
 //!
+//! ## Used the stable toolchain
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ xargo build
+//! error: failed to run `rustc` to learn about target-specific information
+//!
+//! To learn more, run the command again with --verbose.
+//! ```
+//!
+//! Solution: Switch to the nightly toolchain with `rustup default nightly`.
+//!
+//! ## Used `CARGO_INCREMENTAL=1`
+//!
+//! Error message:
+//!
+//! ```
+//! $ xargo build
+//! error: linking with `arm-none-eabi-ld` failed: exit code: 1
+//!     |
+//! = note: "arm-none-eabi-ld" (..)
+//!     = note: arm-none-eabi-ld:
+//! You must specify the exception handlers.
+//!     Create a non `pub` static variable with type
+//!     `cortex_m::exception::Handlers` and place it in the
+//!     '.rodata.exceptions' section. (cf. #[link_section]). Apply the
+//!     `#[used]` attribute to the variable to make it reach the linker.
+//!     arm-none-eabi-ld:
+//! Invalid '.rodata.exceptions' section.
+//!     Make sure to place a static with type `cortex_m::exception::Handlers`
+//!     in that section (cf. #[link_section]) ONLY ONCE.
+//! ```
+//!
+//! Solution: `$ unset CARGO_INCREMENAL`. And to be on the safe side, call
+//! `cargo clean` and thrash the Xargo sysroot: `$ rm -rf ~/.xargo`
+//!
 //! ## Used `gdb` instead of `arm-none-eabi-gdb`
 //!
 //! Error message: