Improve the device generator script

Author: dylanmckay

Cargo.toml

@@ -23,7 +23,7 @@ categories = ["embedded"]
 [features]
 default = []
 # Enable all microcontrollers.
-all_mcus = []
+all-mcus = []
 
 [dependencies]
 
@@ -34,3 +34,6 @@ avr-mcu = "0.3"
 # Most of the build consists of generating the mcu description files. So
 # enable optimizations to speed this process.
 opt-level = 2
+
+[package.metadata.docs.rs]
+all-features = true

README.md

@@ -28,8 +28,8 @@ volatile_store(PORTB, 0x1f);
 
 Just include the crate as a dependency and it will work.
 
-## Usage on other architectures
+## Enabling all microcontrollers at once
 
-You need to compile with the `all_mcus` feature enabled, otherwise it will attempt
-to target the current AVR microcontroller, which isn't set in these cases.
+You may want to compile with the `all-mcus` feature enabled, which enables
+modules for all microcontrollers to be compiled and included at once.
 

build.rs

@@ -0,0 +1,13 @@
+const DEFAULT_MCU_FOR_NON_AVR_DOCS: &'static str = "atmega328";
+
+fn main() {
+    let current_mcu = if avr_mcu::current::is_compiling_for_avr() {
+        avr_mcu::current::mcu()
+            .expect("no target cpu specified")
+    } else {
+        avr_mcu::microcontroller(DEFAULT_MCU_FOR_NON_AVR_DOCS)
+    };
+    let current_mcu_name = current_mcu.device.name.clone().to_lowercase();
+
+    println!("cargo:rustc-cfg=avr_mcu_{}", &current_mcu_name);
+}

device_generator/src/main.rs

@@ -4,6 +4,8 @@ use clap::{App, Arg};
 
 use std::path::{Path, PathBuf};
 
+const DEFAULT_MCU_FOR_NON_AVR: &'static str = "atmega328";
+
 #[derive(Clone, Debug)]
 struct Config {
     output_directory: PathBuf,
@@ -74,38 +76,35 @@ mod gen {
     fn generate_entry_module(output_path: &Path, module_names: &[String]) -> Result<(), io::Error> {
         let mut mod_rs = File::create(output_path.join("mod.rs"))?;
 
-        writeln!(mod_rs, "// Device definitions")?;
-        for module_name in module_names {
-            writeln!(mod_rs, "pub mod {};", module_name)?;
-        }
-        writeln!(mod_rs)?;
+        const CURRENT_MOD_SUMMARY: &'static str = "Contains definitions for the current AVR device being targeted.";
 
-        const CURRENT_MOD_SUMMARY: &'static str = "Contains definitions for the current AVR device";
-
-        writeln!(mod_rs, "/// {}", CURRENT_MOD_SUMMARY)?;
-        writeln!(mod_rs, "///")?;
-        writeln!(mod_rs, "/// **NOTE**: We are showing the ATmega328 here, even though the library")?;
-        writeln!(mod_rs, "/// is not targeting a real AVR device. If you compile this library for")?;
-        writeln!(mod_rs, "/// a specific AVR MCU, the module for that device will aliased here.")?;
-        writeln!(mod_rs, "// If we are targeting a non-AVR device, just pick the ATmega328p so")?;
-        writeln!(mod_rs, "// that users can see what the API would look like")?;
-        writeln!(mod_rs, "//")?;
-        writeln!(mod_rs, "// Note that we reexport rather than alias so that we can add a note about")?;
-        writeln!(mod_rs, "// this behaviour to the documentation.")?;
-        writeln!(mod_rs, "#[cfg(not(target_arch = \"avr\"))]")?;
-        writeln!(mod_rs, "pub mod current {{ pub use super::atmega328::*; }}")?;
+        writeln!(mod_rs, "// Device definitions")?;
         writeln!(mod_rs)?;
-        writeln!(mod_rs, "/// {}", CURRENT_MOD_SUMMARY)?;
-        writeln!(mod_rs, "// If we are targeting AVR, lookup the current device's module")?;
-        writeln!(mod_rs, "// and alias it to the `current` module.")?;
-        writeln!(mod_rs, "#[cfg(target_arch = \"avr\")]")?;
-        writeln!(mod_rs, "pub mod current {{")?;
-        writeln!(mod_rs, "    // NOTE: 'target_cpu' is a cfg flag specific to the avr-rust fork")?;
         for module_name in module_names {
-            writeln!(mod_rs, "    #[cfg(target_cpu = \"{}\")] pub use super::{} as current;",
-                     module_name, module_name)?;
+            if module_name == crate::DEFAULT_MCU_FOR_NON_AVR {
+                writeln!(mod_rs, "/// The module containing the values for the '{}' microcontroller", module_name)?;
+                writeln!(mod_rs, "///")?;
+                writeln!(mod_rs, "/// This is the default MCU when targeting a non-AVR target.")?;
+
+                writeln!(mod_rs, "#[cfg(any(not(target_arch = \"avr\"), avr_mcu_{}, feature = \"all-mcus\"))] pub mod {};", module_name, module_name)?;
+
+                writeln!(mod_rs, "/// {} **The '{}' is the default when targeting non-AVR devices.**", CURRENT_MOD_SUMMARY, module_name)?;
+
+                writeln!(mod_rs, "#[cfg(not(target_arch = \"avr\"))] pub mod current {{ pub use super::{}::*; }}", module_name)?;
+
+                writeln!(mod_rs, "/// {} **This is currently the '{}'**.", CURRENT_MOD_SUMMARY, module_name)?;
+                writeln!(mod_rs, "#[cfg(all(target_arch = \"avr\", avr_mcu_{}))] pub mod current {{ pub use super::{}::*; }}",
+                         module_name, module_name)?;
+            } else {
+                writeln!(mod_rs, "/// The module containing the values for the '{}' microcontroller", module_name)?;
+                writeln!(mod_rs, "#[cfg(any(avr_mcu_{}, feature = \"all-mcus\"))] pub mod {};", module_name, module_name)?;
+                writeln!(mod_rs, "/// {} **This is currently the '{}'**.", CURRENT_MOD_SUMMARY, module_name)?;
+                writeln!(mod_rs, "#[cfg(all(target_arch = \"avr\", avr_mcu_{}))] pub mod current {{ pub use super::{}::*; }}",
+                         module_name, module_name)?;
+            }
+            writeln!(mod_rs)?;
         }
-        writeln!(mod_rs, "}}")?;
+        writeln!(mod_rs)?;
 
         Ok(())
     }

regenerate-devices.sh

@@ -2,10 +2,8 @@
 
 CRATE_DIR=$(realpath $(dirname $0))
 
-echo "create dir: '${CRATE_DIR}'"
-
 cd "${CRATE_DIR}/device_generator"
 
 echo "Generating cores"
 
-cargo run -- -o "${CRATE_DIR}/src/gen"
+cargo run -- -o "${CRATE_DIR}/src/gen" $@

src/gen/README.md

@@ -0,0 +1 @@
+Contains autogenerated device-specific Rust modules.

src/lib.rs

@@ -6,6 +6,14 @@
 //!
 //! The information for each device is separated into submodules, named after
 //! the microcontroller itself.
+//!
+//! The [`current`][crate::current] module is an alias to whatever microcontroller
+//! is currently being targeted.
+//!
+//! # Enabling all microcontrollers at once
+//!
+//! You may want to compile with the `all-mcus` feature enabled, which enables
+//! modules for all microcontrollers to be compiled and included at once.
 
 #![no_std]