![]() |
RogiStandard-hal
STM32 向けサークル共通ライブラリ
|
STM32(CubeMX + CMake)向けのサークル共通ライブラリです。 ライブラリごとに独立した CMake ターゲットになっており、**リンクしたライブラリだけがビルドされます**。 使わないペリフェラルに依存するライブラリが原因でコンパイルエラーになることはありません。
CubeMX が生成したプロジェクトのトップ CMakeLists.txt に追記します。 add_subdirectory(cmake/stm32cubemx) より後に書いてください。
VSCode(CMake Tools)で再構成すると、ライブラリが自動で取得されます。 コードからは各ライブラリのヘッダをそのまま #include します(例: #include "DCMotor.hpp")。
cmake/CPM.cmake が無い場合は CPM.cmake の get_cpm.cmake を cmake/CPM.cmake として保存してください。
利用側プロジェクトで、取得したものの代わりに手元の clone を使えます。
Lib/<カテゴリ>/<ライブラリ>/ に Inc/・Src/・README.md・CMakeLists.txt を作るCMakeLists.txt に1行書く。これで rogi::Foo としてリンクできるようになる
Src/ 以下の .c / .cpp は自動でビルド対象になります。 ソースが無い場合(Src/ を作らない場合)はヘッダーオンリーのライブラリになります。 HAL のコールバック(HAL_xxx_Callback)を定義するライブラリは、定義を必ず Src/ の .cpp に書いてください。ヘッダに書くと呼ばれなくなることがあります。 他のライブラリに依存する場合は rogi_add_library(Foo DEPENDS rogi::DCMotor) のように書きます。 ソースを個別に指定したい場合は SOURCES Src/Foo.cpp を付けます。
CMakeLists.txt に add_subdirectory(<ライブラリ>) を1行足すヘッダの先頭で必要なペリフェラルを確認する
テストは PC 上で実行します。ファームウェアと同じ rogi::<名前> のターゲットを使うので、Eigen や units もファームウェアと同じバージョンでテストされます。
テストを追加するときは、ライブラリ(またはカテゴリ)の下に tests/ を作り、CMakeLists.txt に1行書きます。Lib/tests/CMakeLists.txt の追記は不要です。
tests/ 以下の .cpp は自動でビルド対象になりますmain 関数は不要です。テストのソースには #include <doctest/doctest.h> と TEST_CASE だけを書きますTEST_CASE ごとに foo_tests/<TEST_CASE 名> として登録されます-DROGI_TEST_SANITIZERS=OFF を付けますbuild/tests/compile_commands.json を使ってテストのファイルを解析します。テストのファイルを開く前に、上の configure を一度実行してくださいヘッダのコメントと各ライブラリの README から、Doxygen で HTML のドキュメントを生成します。
生成には doxygen・graphviz・python3 が必要です。見るときは、簡易サーバーを立ててブラウザで http://localhost:8000 を開きます(終わったら Ctrl+C)。
build/docs/index.html を直接開いても読めますが、Flatpak 版のブラウザではファイルへのアクセスが制限され、スタイルが当たらないことがあります。
クラスや関数は、左のツリーの「ライブラリ一覧」からカテゴリ → ライブラリの順に辿れます。各ライブラリのページには、リンクするターゲット(target_link_libraries)と #include するヘッダ、そのライブラリの README.md が載ります。この分類はディレクトリ構造から自動で付くので、ヘッダや README に書く必要はありません(docs/doxygen_group_filter.py)。
main に push すると、Actions がドキュメントを生成して https://rogi-docs.5c6f2f.com に公開します。開くとログイン画面が出るので、@keio.jp のメールアドレスを入力し、届いたコードを入れてください。公開の設定と管理は docs/README.md にまとめています。
公開先を開けないときは、Actions の実行結果のページ下部にある Artifacts の docs-html から zip でダウンロードし、展開した index.html を開いても読めます。
見た目はテーマ doxygen-awesome-css の上に、サークルのサイトに合わせた配色(docs/rogi-theme.css)を重ねています。
最低限、次のものに Doxygen 形式のコメントを書きます。見本は Lib/Actuator/DCMotor/Inc/DCMotor.hpp と Lib/Control/OmniWheelController/Inc/OmniWheelController.hpp です。
@file と @brief(何をするライブラリか、必要なペリフェラル)@brief、引数があれば @param、戻り値があれば @returnデータの流れなど、文章では伝わりにくいものは @dot 〜 @enddot に Graphviz の図を書けます(OmniWheelController.hpp を参照)。