fix(teensy): auto-link Teensyduino CMSIS-DSP per-MCU (#300)

crates/fbuild-build/src/teensy/configs/teensy4x.json

@@ -38,7 +38,6 @@
   ],
 
   "linker_libs": [
-    "-larm_cortexM7lfsp_math",
     "-lgcc",
     "-lstdc++",
     "-lm",

crates/fbuild-build/src/teensy/mcu_config.rs

@@ -199,24 +199,39 @@ mod tests {
             .contains(&"-mcpu=cortex-m7".to_string()));
     }
 
-    /// Regression test for issue #257: teensy4x must link
-    /// `libarm_cortexM7lfsp_math.a` (CMSIS-DSP) so Teensy Audio FFT
-    /// examples (`Ports/PJRCSpectrumAnalyzer`) resolve symbols like
-    /// `arm_cfft_radix4_q15`. The library ships in the Teensy 4.x core
-    /// dir, which the linker already gets as `-L<core_dir>` via
-    /// `LinkerScripts::single`.
+    /// Regression test for issues #257 and #300: Teensy boards that ship a
+    /// Teensyduino-bundled CMSIS-DSP math library must auto-link it so Teensy
+    /// `Audio.h` FFT examples (`Ports/PJRCSpectrumAnalyzer`) resolve symbols
+    /// like `arm_cfft_radix4_q15`. After #300 the per-MCU library name is
+    /// data-driven via `BoardConfig.cmsis_dsp_lib` (populated from board JSON
+    /// `build.cmsis_dsp_lib`), mirroring PlatformIO+Teensyduino's SCons
+    /// builder. The library ships in the Teensy core dir, which the linker
+    /// already gets as `-L<core_dir>` via `LinkerScripts::single`.
     #[test]
-    fn teensy4x_links_cmsis_dsp_math() {
-        let config = get_teensy_config_for_mcu("imxrt1062").expect("teensy4x config");
-        assert!(
-            config
-                .linker_libs
-                .contains(&"-larm_cortexM7lfsp_math".to_string()),
-            "teensy4x linker_libs must include -larm_cortexM7lfsp_math \
-             so Teensy Audio FFT examples link; see issue #257. \
-             Actual libs: {:?}",
-            config.linker_libs
-        );
+    fn teensy_boards_carry_cmsis_dsp_lib() {
+        let expectations: &[(&str, &str)] = &[
+            ("teensy30", "arm_cortexM4l_math"),
+            ("teensy31", "arm_cortexM4l_math"),
+            ("teensy35", "arm_cortexM4lf_math"),
+            ("teensy36", "arm_cortexM4lf_math"),
+            ("teensy40", "arm_cortexM7lfsp_math"),
+            ("teensy41", "arm_cortexM7lfsp_math"),
+            ("teensymm", "arm_cortexM7lfsp_math"),
+            ("teensylc", "arm_cortexM0l_math"),
+        ];
+        for (board_id, expected) in expectations {
+            let board = fbuild_config::BoardConfig::from_board_id(board_id, &HashMap::new())
+                .unwrap_or_else(|_| panic!("BoardConfig should load for {}", board_id));
+            assert_eq!(
+                board.cmsis_dsp_lib.as_deref(),
+                Some(*expected),
+                "{} must declare build.cmsis_dsp_lib={} so Teensy Audio FFT \
+                 examples link (mirrors PlatformIO+Teensyduino's per-MCU \
+                 auto-link). See FastLED/fbuild#300.",
+                board_id,
+                expected,
+            );
+        }
     }
 
     #[test]

crates/fbuild-build/src/teensy/orchestrator.rs

@@ -261,6 +261,7 @@ impl BuildOrchestrator for TeensyOrchestrator {
             params.profile,
             ctx.board.max_flash,
             ctx.board.max_ram,
+            ctx.board.cmsis_dsp_lib.clone(),
             params.verbose,
         );
 

crates/fbuild-build/src/teensy/teensy_linker.rs

@@ -22,6 +22,11 @@ pub struct TeensyLinker {
     profile: BuildProfile,
     max_flash: Option<u64>,
     max_ram: Option<u64>,
+    /// Bare CMSIS-DSP math library name (e.g. `arm_cortexM4lf_math`) to link
+    /// via `-l<name>`. Mirrors PlatformIO+Teensyduino's per-MCU auto-link of
+    /// the appropriate `libarm_cortex*_math.a` so Teensy `Audio.h` FFT classes
+    /// resolve at link time. See FastLED/fbuild#300.
+    cmsis_dsp_lib: Option<String>,
     verbose: bool,
 }
 
@@ -37,6 +42,7 @@ impl TeensyLinker {
         profile: BuildProfile,
         max_flash: Option<u64>,
         max_ram: Option<u64>,
+        cmsis_dsp_lib: Option<String>,
         verbose: bool,
     ) -> Self {
         Self {
@@ -49,26 +55,26 @@ impl TeensyLinker {
             profile,
             max_flash,
             max_ram,
+            cmsis_dsp_lib,
             verbose,
         }
     }
-}
 
-impl Linker for TeensyLinker {
-    fn archive(&self, objects: &[PathBuf], output: &Path) -> Result<()> {
-        crate::linker::LinkerBase::archive(&self.ar_path, objects, output, "arm-none-eabi-ar")
+    /// Bare CMSIS-DSP library name configured for this linker, if any.
+    pub fn cmsis_dsp_lib(&self) -> Option<&str> {
+        self.cmsis_dsp_lib.as_deref()
     }
 
-    fn link(
+    /// Build the full `arm-none-eabi-gcc` link command-line for the given
+    /// inputs. Exposed for unit-testing the auto-appended CMSIS-DSP lib
+    /// (FastLED/fbuild#300) without spawning the real linker.
+    fn build_link_args(
         &self,
         objects: &[PathBuf],
         archives: &[PathBuf],
-        output_dir: &Path,
+        elf_path: &Path,
         extra: &LinkExtraArgs,
-    ) -> Result<PathBuf> {
-        std::fs::create_dir_all(output_dir)?;
-        let elf_path = output_dir.join("firmware.elf");
-
+    ) -> Vec<String> {
         let mut args: Vec<String> = vec![self.gcc_path.to_string_lossy().to_string()];
 
         // Linker flags from config
@@ -95,8 +101,38 @@ impl Linker for TeensyLinker {
 
         // Linker libraries from config
         args.extend(self.mcu_config.linker_libs.iter().cloned());
+        // Per-board CMSIS-DSP math library auto-link (FastLED/fbuild#300).
+        // Mirrors PlatformIO+Teensyduino's behaviour: when the board defines
+        // `build.cmsis_dsp_lib`, append `-l<name>` so the linker resolves
+        // CMSIS-DSP symbols (`arm_cfft_*`, etc.) referenced by `Audio.h` FFT
+        // classes from `libarm_cortex*_math.a` that ships in the Teensy core
+        // dir (already on the search path via `-L<core_dir>`).
+        if let Some(ref lib) = self.cmsis_dsp_lib {
+            args.push(format!("-l{}", lib));
+        }
         args.extend(extra.libs.iter().cloned());
 
+        args
+    }
+}
+
+impl Linker for TeensyLinker {
+    fn archive(&self, objects: &[PathBuf], output: &Path) -> Result<()> {
+        crate::linker::LinkerBase::archive(&self.ar_path, objects, output, "arm-none-eabi-ar")
+    }
+
+    fn link(
+        &self,
+        objects: &[PathBuf],
+        archives: &[PathBuf],
+        output_dir: &Path,
+        extra: &LinkExtraArgs,
+    ) -> Result<PathBuf> {
+        std::fs::create_dir_all(output_dir)?;
+        let elf_path = output_dir.join("firmware.elf");
+
+        let args = self.build_link_args(objects, archives, &elf_path, extra);
+
         if self.verbose {
             tracing::info!("link: {}", args.join(" "));
         }
@@ -181,10 +217,12 @@ mod tests {
             BuildProfile::Release,
             Some(8126464),
             Some(1048576),
+            None,
             false,
         );
         assert_eq!(linker.max_flash, Some(8126464));
         assert_eq!(linker.max_ram, Some(1048576));
+        assert!(linker.cmsis_dsp_lib().is_none());
     }
 
     #[test]
@@ -199,6 +237,7 @@ mod tests {
             BuildProfile::Release,
             Some(8126464),
             Some(1048576),
+            None,
             false,
         );
         assert!(linker
@@ -207,4 +246,96 @@ mod tests {
             .iter()
             .any(|s| s.contains("imxrt1062")));
     }
+
+    /// Regression test for FastLED/fbuild#300: when a CMSIS-DSP library is
+    /// configured, the linker stores it so the `-l<lib>` flag is appended at
+    /// link time (mirrors PlatformIO+Teensyduino's auto-link behaviour).
+    #[test]
+    fn test_teensy_linker_stores_cmsis_dsp_lib() {
+        let linker = TeensyLinker::new(
+            PathBuf::from("/bin/arm-none-eabi-gcc"),
+            PathBuf::from("/bin/arm-none-eabi-ar"),
+            PathBuf::from("/bin/arm-none-eabi-objcopy"),
+            PathBuf::from("/bin/arm-none-eabi-size"),
+            LinkerScripts::single(PathBuf::from("/teensy3"), "mk66fx1m0.ld"),
+            crate::teensy::mcu_config::get_teensy_config_for_mcu("mk66fx1m0").unwrap(),
+            BuildProfile::Release,
+            Some(1048576),
+            Some(262144),
+            Some("arm_cortexM4lf_math".to_string()),
+            false,
+        );
+        assert_eq!(linker.cmsis_dsp_lib(), Some("arm_cortexM4lf_math"));
+    }
+
+    /// Regression test for FastLED/fbuild#300: the constructed link command
+    /// includes `-larm_cortexM4lf_math` for teensy36 (MK66FX1M0). Mirrors
+    /// PlatformIO+Teensyduino's per-MCU auto-link so Teensy `Audio.h` FFT
+    /// classes (e.g. `arm_cfft_radix4_q15`) resolve at link time.
+    #[test]
+    fn test_teensy36_link_command_includes_cmsis_dsp_lib() {
+        let linker = TeensyLinker::new(
+            PathBuf::from("/bin/arm-none-eabi-gcc"),
+            PathBuf::from("/bin/arm-none-eabi-ar"),
+            PathBuf::from("/bin/arm-none-eabi-objcopy"),
+            PathBuf::from("/bin/arm-none-eabi-size"),
+            LinkerScripts::single(PathBuf::from("/teensy3"), "mk66fx1m0.ld"),
+            crate::teensy::mcu_config::get_teensy_config_for_mcu("mk66fx1m0").unwrap(),
+            BuildProfile::Release,
+            Some(1048576),
+            Some(262144),
+            Some("arm_cortexM4lf_math".to_string()),
+            false,
+        );
+        let args = linker.build_link_args(
+            &[PathBuf::from("/build/sketch.o")],
+            &[PathBuf::from("/build/core.o")],
+            &PathBuf::from("/build/firmware.elf"),
+            &LinkExtraArgs::default(),
+        );
+        assert!(
+            args.iter().any(|a| a == "-larm_cortexM4lf_math"),
+            "teensy36 link command must include -larm_cortexM4lf_math \
+             so Audio.h FFT examples link (see fbuild#300). Args: {:?}",
+            args
+        );
+        // The `-L<core_dir>` flag from LinkerScripts is what lets the linker
+        // resolve the `-l` to `libarm_cortexM4lf_math.a` inside teensy3/.
+        assert!(
+            args.iter().any(|a| a == "-L/teensy3"),
+            "expected -L/teensy3 for library search, got {:?}",
+            args
+        );
+    }
+
+    /// Boards that do not declare a CMSIS-DSP lib (e.g. user override clears
+    /// it) must not have a spurious `-l` argument appended.
+    #[test]
+    fn test_teensy_link_command_omits_cmsis_dsp_lib_when_none() {
+        let linker = TeensyLinker::new(
+            PathBuf::from("/bin/arm-none-eabi-gcc"),
+            PathBuf::from("/bin/arm-none-eabi-ar"),
+            PathBuf::from("/bin/arm-none-eabi-objcopy"),
+            PathBuf::from("/bin/arm-none-eabi-size"),
+            LinkerScripts::single(PathBuf::from("/teensy4"), "imxrt1062_t41.ld"),
+            crate::teensy::mcu_config::get_teensy_config_for_mcu("imxrt1062").unwrap(),
+            BuildProfile::Release,
+            Some(8126464),
+            Some(524288),
+            None,
+            false,
+        );
+        let args = linker.build_link_args(
+            &[],
+            &[],
+            &PathBuf::from("/build/firmware.elf"),
+            &LinkExtraArgs::default(),
+        );
+        assert!(
+            !args.iter().any(|a| a.starts_with("-larm_cortex")),
+            "no CMSIS-DSP -l flag should be appended when cmsis_dsp_lib is None. \
+             Args: {:?}",
+            args
+        );
+    }
 }

crates/fbuild-config/assets/boards/json/teensy30.json

@@ -3,6 +3,7 @@
     "arduino": {
       "ldscript": "mk20dx128.ld"
     },
+    "cmsis_dsp_lib": "arm_cortexM4l_math",
     "core": "teensy3",
     "extra_flags": "-D__MK20DX128__ -DARDUINO_TEENSY30",
     "f_cpu": "48000000L",

crates/fbuild-config/assets/boards/json/teensy31.json

@@ -3,6 +3,7 @@
     "arduino": {
       "ldscript": "mk20dx256.ld"
     },
+    "cmsis_dsp_lib": "arm_cortexM4l_math",
     "core": "teensy3",
     "extra_flags": "-D__MK20DX256__ -DARDUINO_TEENSY31",
     "f_cpu": "72000000L",

crates/fbuild-config/assets/boards/json/teensy35.json

@@ -3,6 +3,7 @@
     "arduino": {
       "ldscript": "mk64fx512.ld"
     },
+    "cmsis_dsp_lib": "arm_cortexM4lf_math",
     "core": "teensy3",
     "extra_flags": "-D__MK64FX512__ -DARDUINO_TEENSY35",
     "f_cpu": "120000000L",

crates/fbuild-config/assets/boards/json/teensy36.json

@@ -3,6 +3,7 @@
     "arduino": {
       "ldscript": "mk66fx1m0.ld"
     },
+    "cmsis_dsp_lib": "arm_cortexM4lf_math",
     "core": "teensy3",
     "extra_flags": "-D__MK66FX1M0__ -DARDUINO_TEENSY36",
     "f_cpu": "180000000L",

crates/fbuild-config/assets/boards/json/teensy40.json

@@ -3,6 +3,7 @@
     "arduino": {
       "ldscript": "imxrt1062.ld"
     },
+    "cmsis_dsp_lib": "arm_cortexM7lfsp_math",
     "core": "teensy4",
     "extra_flags": "-D__IMXRT1062__ -DARDUINO_TEENSY40",
     "f_cpu": "600000000",

crates/fbuild-config/assets/boards/json/teensy41.json

@@ -3,6 +3,7 @@
     "arduino": {
       "ldscript": "imxrt1062_t41.ld"
     },
+    "cmsis_dsp_lib": "arm_cortexM7lfsp_math",
     "core": "teensy4",
     "extra_flags": "-D__IMXRT1062__ -DARDUINO_TEENSY41",
     "f_cpu": "600000000",

crates/fbuild-config/assets/boards/json/teensylc.json

@@ -3,6 +3,7 @@
     "arduino": {
       "ldscript": "mkl26z64.ld"
     },
+    "cmsis_dsp_lib": "arm_cortexM0l_math",
     "core": "teensy3",
     "extra_flags": "-D__MKL26Z64__ -DARDUINO_TEENSYLC",
     "f_cpu": "48000000L",

crates/fbuild-config/assets/boards/json/teensymm.json

@@ -3,6 +3,7 @@
     "arduino": {
       "ldscript": "imxrt1062_mm.ld"
     },
+    "cmsis_dsp_lib": "arm_cortexM7lfsp_math",
     "core": "teensy4",
     "extra_flags": "-D__IMXRT1062__ -DARDUINO_TEENSY_MICROMOD",
     "f_cpu": "600000000",

crates/fbuild-config/src/board/db.rs

@@ -178,6 +178,9 @@ pub(super) fn get_board_defaults(board_id: &str) -> Option<HashMap<String, Strin
         if let Some(f_image) = build.get("f_image").and_then(|v| v.as_str()) {
             d.insert("f_image".into(), f_image.to_string());
         }
+        if let Some(cmsis_dsp_lib) = build.get("cmsis_dsp_lib").and_then(|v| v.as_str()) {
+            d.insert("cmsis_dsp_lib".into(), cmsis_dsp_lib.to_string());
+        }
         // Arduino sub-fields
         if let Some(arduino) = build.get("arduino").and_then(|v| v.as_object()) {
             if let Some(ldscript) = arduino.get("ldscript").and_then(|v| v.as_str()) {

crates/fbuild-config/src/board/loaders.rs

@@ -107,6 +107,7 @@ impl BoardConfig {
             partitions: get("partitions"),
             ldscript: get("ldscript"),
             platform_str: get("platform_str"),
+            cmsis_dsp_lib: get("cmsis_dsp_lib"),
             debug_tools: None, // boards.txt format does not contain debug metadata
         })
     }
@@ -231,6 +232,10 @@ impl BoardConfig {
                 .cloned()
                 .or_else(|| defaults.get("ldscript").cloned()),
             platform_str: defaults.get("platform_str").cloned(),
+            cmsis_dsp_lib: overrides
+                .get("cmsis_dsp_lib")
+                .cloned()
+                .or_else(|| defaults.get("cmsis_dsp_lib").cloned()),
             debug_tools: get_board_debug_tools(board_id),
         })
     }