Why do I get compile errors if I comment out an include?

I added a dependency to lib_deps in platformio.ini:

adafruit/Adafruit MCP23017 Arduino Library@^2.1.0

Then I ran “pio run” from the command line to compile it.

I got a bunch of errors about not being able to find headers for Adafruiit_BusIO (which is a dependency). The error messages suggest adding it as a dependency, so I did, but it didn’t help; then it complains about not being able to find Wire.h.

If I then add the include to main:

#include <Adafruit_MCP23X08.h>

Then everything compiles fine, even though I removed the dependency on BusIO. Comment it out, and everything is broken again.

This behavior is puzzling. Why should commenting out an unused #include break things? I’m getting compile errors in code that I’m not actually using. Why is it compiled at all?

Also, why can PlatformIO find the dependency of a dependency when the #include is there, but it can’t find it if it’s not there?

Also, where in the documentation does it explain how the build system works?

The LDF will resolve dependencies to the things it finds an #include for – that’s documented here and here.

All build options are documented. Under the hood, PlatformIO uses SCons (currently 4.3), which is documented. Some more technical details are here.