Arduino IDEでサブディレクトリの資源がコンパイルされない問題

Arduino IDEでサブディレクトリの資源がコンパイルされない問題の解決方法

背景

Arduino IDEで開発を進める際、MyProject.ino という1つのファイルに全てのコードを記述すると、コードの管理がしにくくなりました。そこで、Wi-Fi制御やNTP時刻取得、UI表示といった機能ごとにファイルを分割し、それぞれ WiFiManager.cpp や NTPClient.cpp などに整理することにしました。

しかし、.ino ファイルと同じフォルダにない .cpp ファイルがコンパイルされず、undefined reference エラーが発生する問題に直面しました。

困ったこと

Arduino IDEを使って以下の構成で開発をしていたところ、WiFiManager.cpp など core や ui 内のサブディレクトリにある .cpp ファイルがコンパイルされないという問題に直面しました。

/Arduino
  ├── /Project                // プロジェクトフォルダ（スケッチフォルダ）
  │     ├── MyProject.ino       // メインのスケッチファイル
  │     ├── core              // 基盤部品フォルダ
  │     │     ├── wifi        // Wi-Fi制御
  │     │     │     ├── WiFiManager.h
  │     │     │     ├── WiFiManager.cpp
  │     │     ├── ntp         // NTP時刻取得
  │     │     │     ├── NTPClient.h
  │     │     │     ├── NTPClient.cpp
  │     ├── ui                // 表示系フォルダ
  │     │     ├── clock       // 時計表示
  │     │     │     ├── ClockDisplay.h
  │     │     │     ├── ClockDisplay.cpp

このようなディレクトリ構成では、Arduino IDE は MyProject.ino と同じフォルダにある .cpp ファイルのみを自動的にコンパイル対象にします。そのため、core や ui の中にある .cpp ファイルはコンパイル対象外となり、undefined reference エラーが発生しました。

解決方法

src ディレクトリを作成し、その中に core や ui のようなサブディレクトリを配置することで、この問題を解決できます。

なぜ src 以下に入れると解決するのか？

Arduino IDEは、スケッチフォルダ直下にある .cpp ファイルのみを自動的にコンパイル対象とします。しかし、src というディレクトリを作成してその中に .cpp ファイルを配置すると、Arduino IDEは src 以下の全ての .cpp ファイルをコンパイル対象として認識します。

これは、Arduinoのコンパイルシステムが src ディレクトリを特別扱いし、そこにあるファイルをすべてビルド対象とする仕様によるものです。そのため、ファイルを整理しつつ、正しくコンパイルされる環境を構築できます。

修正後のディレクトリ構成

/Arduino
  ├── /Project                // プロジェクトフォルダ（スケッチフォルダ）
  │     ├── MyProject.ino       // メインのスケッチファイル
  │     ├── src                // ソースコード格納用ディレクトリ
  │     │     ├── core        // 基盤部品フォルダ
  │     │     │     ├── wifi        // Wi-Fi制御
  │     │     │     │     ├── WiFiManager.h
  │     │     │     │     ├── WiFiManager.cpp
  │     │     │     ├── ntp         // NTP時刻取得
  │     │     │     │     ├── NTPClient.h
  │     │     │     │     ├── NTPClient.cpp
  │     │     ├── ui          // 表示系フォルダ
  │     │     │     ├── clock       // 時計表示
  │     │     │     │     ├── ClockDisplay.h
  │     │     │     │     ├── ClockDisplay.cpp

.ino ファイルでの #include の修正

この変更後、MyProject.ino 内でヘッダーファイルを正しく参照するには、src ディレクトリを考慮して #include を修正します。

修正前:

#include "core/wifi/WiFiManager.h"
#include "core/ntp/NTPClient.h"
#include "ui/clock/ClockDisplay.h"

修正後:

#include "src/core/wifi/WiFiManager.h"
#include "src/core/ntp/NTPClient.h"
#include "src/ui/clock/ClockDisplay.h"

このように変更することで、Arduino IDE は src 以下の .cpp ファイルもコンパイル対象として認識し、正しくビルドされるようになります。

まとめ

Arduino IDEでは、.ino ファイルと同じディレクトリにない .cpp ファイルは自動ではコンパイル対象になりません。この問題を解決するために、src ディレクトリを作成し、その中に .cpp や .h ファイルを配置することで、正常にコンパイルされるようになりました。

src ディレクトリを使用することで、ファイルの整理がしやすくなり、Arduino IDEが正しく認識してコンパイルできるようになるため、推奨される方法です。