Arduinoのライブラリで廃止予定警告を出す

背景

Arduino向けのライブラリで関数を廃止したくなったり別の関数の利用を推奨したい場合、何らかの形で利用者にお知らせしたくなります。
cppにdepricated機能があるので、Arduinoのライブラリで使ってみました。

備忘録を兼ねて書き方と挙動を共有します。

使ったもの

Arduinoのプログラムをビルドできる環境
下記の2つの環境で警告が出ることを確認しました。

Arduino IDE 1.8.13
PlatformIO 5.0.1

記述方法

関数単位で警告を出す

廃止予定警告を出したい関数の宣言の前に[[deprecated]]と書くと、Arduino IDEでもPlatformIOでも、ビルド時に警告が出ます。

[[deprecated("Use padStart in string_asukiaaa instead.")]]
String padStart(String str, unsigned int len, char pad);

クラスの場合はclassとクラス名の間にdeprecatedを記述します。そうでないとdeprecatedではなく定義がおかしいという警告が出ます。

class [[deprecated("Use Button in button_asukiaaa instead.")]] Button: public ButtonState {
  // ..
}

上記の記述をするとこのような警告が出ます。

/home/asuki/Arduino/libraries/utils_asukiaaa/examples/string/string.ino:11:42: warning: 'String utils_asukiaaa::string::padStart(String, unsigned int, char)' is deprecated: Use padStart in string_asukiaaa [-Wdeprecated-declarations]
   Serial.println(utils_asukiaaa::string::padStart(String(nowMs), 10, ' ') + "ms");
                                          ^~~~~~~~
In file included from /home/asuki/Arduino/libraries/utils_asukiaaa/examples/string/string.ino:2:0:
/home/asuki/Arduino/libraries/utils_asukiaaa/src/utils_asukiaaa/string.h:9:12: note: declared here
     String padStart(String str, unsigned int len, char pad);
            ^~~~~~~~

/home/asuki/Arduino/libraries/utils_asukiaaa/examples/button/button.ino:7:35: warning: 'Button' is deprecated: Use Button in button_asukiaaa [-Wdeprecated-declarations]
 utils_asukiaaa::button::Button btn(PIN_BTN);
                                   ^
In file included from /home/asuki/Arduino/libraries/utils_asukiaaa/examples/button/button.ino:2:0:
/home/asuki/Arduino/libraries/utils_asukiaaa/src/utils_asukiaaa/button.h:31:59: note: declared here
     class [[deprecated("Use Button in button_asukiaaa")]] Button: public ButtonState {
                                                           ^~~~~~

ヘッダファイル単位で警告を出す

関数やクラス単位で警告を出すと表示量が多くて見にくいという場合は、#warningをヘッダファイルに記述することで、ヘッダファイル単位で警告を表示できます。

#warning "utils_asukiaaa/wire.h is deprecated. Use other lib wire_asukiaaa instead."

上記のような記述をした場合は、このように警告が表示されます。

In file included from /home/asuki/Arduino/libraries/utils_asukiaaa/examples/wire/wire.ino:2:0:
/home/asuki/Arduino/libraries/utils_asukiaaa/src/utils_asukiaaa/wire.h:7:2: warning: #warning "utils_asukiaaa/wire.h is deprecated. Use other lib wire_asukiaaa instead." [-Wcpp]
 #warning "utils_asukiaaa/wire.h is deprecated. Use other lib wire_asukiaaa instead."
  ^~~~~~~

Arduino IDEで警告が見れない場合の対応

ログの表示領域が小さいと警告が見えません。

縦に伸ばしてみてください。

表示領域を伸ばしても警告が出ない場合は、Arduino IDEで環境設定の「コンパイラの警告」が「なし」になっていると警告が出ないので、警告が出るはずに出ない場合はその設定を確認してください。
「なし」以外なら「初期値」でも警告が表示されます。

まとめ

cppのdeprecatedやwarningを利用して、Arduinoのライブラリで廃止予定を知らせる警告をビルド時に表示できました。

参考

C++ attribute: deprecated (since C++14)
Allow deprecation of Library Manager libraries