libraries: guard TinyUSB include under PlatformIO so SAMD builds compile

[tyeth-ai-assisted]

Problem

Every PlatformIO SAMD build with USE_TINYUSB fails to compile:

libraries/Servo/src/samd/Servo.cpp:26:10: fatal error: Adafruit_TinyUSB.h: No such file or directory
   26 | #include <Adafruit_TinyUSB.h>

arduino-cli is unaffected, which is why this has gone unnoticed.

Why

Adafruit_TinyUSB.h lives in the library's src/, and only src/arduino is ever put on the include path — by both toolchains:

• platform.txt (line 80) for arduino-cli:
  "-I{runtime.platform.path}/libraries/Adafruit_TinyUSB_Arduino/src/arduino"
• PlatformIO's atmelsam platform appends that same .../Adafruit_TinyUSB_Arduino/src/arduino to the global CPPPATH for the Adafruit vendor core (builder/frameworks/arduino/arduino-samd.py).

So Adafruit_USBD_CDC.h resolves everywhere, while <Adafruit_TinyUSB.h> resolves from neither.

Under arduino-cli it works anyway, because that unresolved include is itself what drives the Arduino builder's library discovery: it finds Adafruit_TinyUSB_Arduino, adds its src/ to the include path, and links the library — the side effect the existing comment refers to. PlatformIO has no equivalent step for framework-bundled libraries (they never receive lib_deps include paths), so there the include is simply a hard error.

Fix

Skip the include under PlatformIO when the header is unreachable, and leave it plain and unconditional everywhere else:

#ifdef USE_TINYUSB
// For Serial when selecting TinyUSB (also causes the Arduino builder to link
// the TinyUSB library). Outside PlatformIO this include must stay plain and
// unconditional: the Arduino builder discovers the library from it, and its
// dependency-detection pass cannot parse a __has_include() expression.
#ifdef PLATFORMIO
// PlatformIO does not give framework-bundled libraries the lib_deps include
// paths, so the header can be unreachable here; skip it instead of failing.
#if !defined(__has_include) || __has_include(<Adafruit_TinyUSB.h>)
#include <Adafruit_TinyUSB.h>
#endif
#else
#include <Adafruit_TinyUSB.h>
#endif
#endif

The nesting is load-bearing, and this repo's CI is what proved it. A flat guard — #if !defined(__has_include) || __has_include(<Adafruit_TinyUSB.h>) around the include, with or without a !defined(PLATFORMIO) clause — turns both usbstack=tinyusb legs red with undefined reference to 'Serial' and Adafruit_USBD_CDC::begin(unsigned long) in the Wire and SAMD_AnalogCorrection examples. The failures are link-time only, never compile errors: the Arduino builder's dependency-detection pass cannot parse a __has_include() expression, so it finds no dependency and TinyUSB is never linked, while the real compile (GCC 9, which does support __has_include) goes through fine. Short-circuiting does not help, because the expression still has to be parsed. Nesting it inside #ifdef PLATFORMIO puts it in a branch arduino-cli skips without evaluating, leaving that toolchain untouched.

Servo.cpp is the only file that actually fails in the configuration I tested; the other four carry the identical unguarded include and the identical hazard, so they get the same treatment rather than surfacing one at a time.

Testing

PlatformIO — Adafruit WipperSnapper (TinyUSB + SPI + Wire + ~60 sensor libraries), env adafruit_pyportal_m4, PlatformIO 6, USE_TINYUSB=1. Each tree was built from the installed platformio/framework-arduino-samd-adafruit@1.10716.0 package (= this repo at 1.7.16) consumed via platform_packages = framework-arduino-samd-adafruit@symlink://<tree>, so these five files are the only variable. They are byte-identical between master and 1.7.16, so the result applies directly to this branch.

framework tree	PlatformIO
unmodified	FAILED — Servo.cpp:26: fatal error: Adafruit_TinyUSB.h: No such file or directory
this PR	SUCCESS — Flash 44.7% (468,924 B), RAM 5.9% (15,400 B)

arduino-cli — this repo's own matrix, run three times on this PR:

branch state	tinyusb legs	other 10 legs
baseline (master tree, guards not applied)	pass	pass
flat __has_include guard	fail (undefined Serial)	pass
nested guard (this PR)	pass	pass

The PlatformIO firmware is byte-for-byte the same size across every guard variant, confirming the guard only ever removes an include PlatformIO could not resolve in the first place.

Note

This supersedes a Copilot-authored attempt (tyeth/adafruit_ArduinoCore-samd#1) that rerouted the Adafruit_USBD_CDC.h include to "arduino/Adafruit_USBD_CDC.h" under PLATFORMIO. That rested on the inverted premise that PlatformIO exposes src but not src/arduino; it breaks every translation unit that includes Arduino.h, and it was never compiled. Closed.

[tyeth]

Hey @hathach could you have a review of this please?
Testing this PR (https://github.com/adafruit/Adafruit_Wippersnapper_Arduino/tree/fix-ws-v2-global-to-pointer adafruit/Adafruit_Wippersnapper_Arduino#974) it was found that Servo.cpp failed to compile due to platformIO LDF being awkward compared to arduino-cli.

This rectifies the include error that occurs otherwise.

[tyeth]

Oops, failing CI on untested path, will fix

[tyeth]

Comments are a bit long, worth a replacement possibly.

[hathach]

look good, sorry for the delay. I think we can simplify this

// PlatformIO does not give framework-bundled libraries the lib_deps include
// paths, so the header can be unreachable there; skip it instead of failing.
#if !defined(PLATFORMIO) || !defined(__has_include) || __has_include(<Adafruit_TinyUSB.h>)
#include <Adafruit_TinyUSB.h>
#endif

[tyeth-ai-assisted]

Update: the __has_include probe is gone; the guard is now just #ifndef PLATFORMIO

#ifdef USE_TINYUSB
// For Serial when selecting TinyUSB; the Arduino builder discovers and links
// the library from this include. PlatformIO never resolves it (framework-
// bundled libraries get no lib_deps include paths), so skip it there.
#ifndef PLATFORMIO
#include <Adafruit_TinyUSB.h>
#endif
#endif

Three lines, no __has_include anywhere, and arduino-cli sees a byte-identical unconditional include. Full matrix green: run 35357540160 — 12/12, both usbstack=tinyusb legs included. (One pyportal_m4 leg in that run first failed at 10s on a runner blip; it passed on re-run, different job id, same tree.)

What actually breaks, per scenario

guard	arduino-cli (usbstack=tinyusb)	PlatformIO (USE_TINYUSB)
none (master)	passes	compile error — Servo.cpp:26:10: fatal error: Adafruit_TinyUSB.h: No such file or directory
flat __has_include, with or without a leading !defined(PLATFORMIO)	link error — undefined reference to 'Serial', undefined reference to 'Adafruit_USBD_CDC::begin(unsigned long)'	passes
__has_include nested inside #ifdef PLATFORMIO	passes	passes
#ifndef PLATFORMIO (current)	passes	passes

Why each cell is what it is:

PlatformIO's compile error. Only Adafruit_TinyUSB_Arduino/src/arduino is ever put on the include path — platform.txt line 80 for arduino-cli, and the atmelsam platform appends the same directory to the global CPPPATH for this core. Adafruit_USBD_CDC.h lives there and resolves everywhere; Adafruit_TinyUSB.h lives one level up in src/ and resolves from neither. PlatformIO gives framework-bundled libraries no lib_deps include paths, so there is no second chance and the include is a hard error.

Why arduino-cli survives that same unresolved include. The unresolved include is the discovery mechanism: the Arduino builder uses it to find Adafruit_TinyUSB_Arduino, add its src/ to the include path, and link the library. Remove or hide the include and nothing links.

The link errors, and why the flat form can't work. The failures are link-time only — never compile errors. GCC 9 handles __has_include fine, so the real compile is clean; it is the builder's dependency-detection pass that cannot parse the expression, finds no dependency, and never links TinyUSB. Ordering the clauses so !defined(PLATFORMIO) short-circuits first does not rescue it, because __has_include is resolved while the #if line is being expanded — before its operands are evaluated — so short-circuiting never gets the chance to hide it. Measured red four times: three runs before this PR was opened, and run 35356063732 on the flat form, where both tinyusb legs failed in the Wire and SAMD_AnalogCorrection examples while the other ten passed. Nesting it inside #ifdef PLATFORMIO worked only because arduino-cli skips that branch without reading it.

Why dropping the include outright is safe. None of the five files — I2S.cpp, SAMD_AnalogCorrection.cpp, SPI.cpp, Servo.cpp, Wire.cpp — references Serial or any TinyUSB symbol. The include exists purely for the arduino-cli discovery side effect, so where that side effect doesn't exist there is nothing to preserve. That is what lets the guard be a plain #ifndef rather than a probe, and it makes the nesting unnecessary rather than merely tidier.

PlatformIO side, unchanged from the original report: WipperSnapper, env adafruit_pyportal_m4, USE_TINYUSB=1, built against the installed framework-arduino-samd-adafruit@1.10716.0 with only these five files varied — fails unpatched, builds patched, identical firmware size across every working guard variant, confirming the guard only ever removes an include PlatformIO could not resolve.

Tyeth will squash the three commits on this branch into one before merge and release.

[tyeth]

@hathach thanks for the review and suggestion. I had a try and unfortunately still fails so this simpler version should be sufficient. I'll squash the PR before merge if you're happy with that.