制御
基本的な開発フロー
GiHubフローを前提とします。
プログラム開発
配布するプログラムはPlatformIOを利用して開発されています。特にmbedフレームワークを利用し、フォーマッターにclang-format, リンターにclang-tidyを使用しています。
リンターは将来変わる可能性があります。(#122)
使用するエディターはVSCodeを想定していますが、CLionなどPlatformIOが適切に動作する環境であれば特に問いません。
ドキュメント開発
このドキュメントはmdBookを利用してGitHub Pagesの内容が生成されています。mdBookの詳細な使用方法に関しては、mdBook Documentationを参照してください。
画像の使用に関して
ドキュメント内では画像を使用することができます。docs/assetsフォルダー内に使用したい画像ファイルを置き、ドキュメントのMarkdownファイルからその画像ファイルへの相対パスを用いて参照することができます。コミットb66c64aなどを記述例として参照してください。
SNS等に画像をアップロードする場合とは異なり、gitリポジトリでは Exif情報がそのままになっています。 exiftoolやImageMagickなどを用いて適切な処理を施したものを使用してください。
参照: exif情報をコマンド一発で削除する #exif - Qiita, ImageMagickでメタデータから不要な情報を削除する｜e
Google Driveの画像を使用する場合
Google Driveに保存されている画像ファイルはGoogle Driveの画像をMarkdownで直接表示したい時に読む記事などで示される方法に従って参照することができます。しかしこの方法ではGitHub Pages上で画像が表示されない(#99)ため、一工夫加える必要があります。具体的には、以下の手順に従ってください。
1: 使用したい画像のリンクと名前を控える
ここでは画像のリンクをhttps://drive.google.com/uc?export=view&id=xxx, Google Driveに保存してある画像の名前をxxx.jpegとします。
2: 控えた情報をスクリプトに追記する
docs/scripts/fetch-gdrive-assets.bashのimage_table='とある行の次などに以下の内容を追記します。
image_magic='
...
https://drive.google.com/uc?export=view&id=xxx xxx.jpeg
...
'
適当な場所に追記してください。
3: Markdownで画像を参照する
先ほどbashファイルに追記したことで、mdBookのビルド時に目的の画像がdocs/gdrive/xxx.jpegに配置されるようになります。Markdownファイルでは相対パスで、以下のように記述することで画像を参照可能です。
こちらもSNS等とは異なり、Google DriveはExif情報を編集しません。
GitHub Actions
GitHub Actionsを用いて自動的にプログラムのチェックなどが入るようになっています。GitHub ActionsについてはGitHub Docsを参照してください。
プライベートリポジトリではGitHub Actionsを使いすぎると課金が発生します。詳しくはGitHub Actions の支払いを管理する - GitHub Docs
GitHub Actionsの設定は.github/workflows以下に保存されています。
main.yml
このワークフローファイル内のジョブは以下のタイミングで実行されます。
mainブランチへのPull Request作成・更新時mainブランチの更新時
どちらの場合も、以下の内容が確認されます。
- PlatformIOのビルドが成功すること
- clang-formatによるプログラムのフォーマット確認 (format)
- clang-tidyによるプログラムの簡易なバグチェック (lint)
- mdBookのビルドが成功すること
特にPull Requestの場合は、変更内容に応じてそれぞれチェックが省略されます。詳しくはmain.ymlのchangesジョブ、およびdorny/paths-filterを確認してください。逆に、変更に対して入ってほしいチェックが行われない場合はここを見てください。
release.yml
TODO (#76)
リリース
TODO (#76)
依存関係管理
プログラムを開発する上で様々なツール、ライブラリが必要になります。一般的にそれらは「依存関係」と呼ばれます。ここではこのリポジトリを管理する上で使用されている依存関係について説明し、それらの更新方法について説明します。
GitHub Actions
GitHub Actionsの依存関係はDependabotで管理されています。依存関係何か更新があればDependabotが自動でPRを作成してくれます。Dependabotの設定は.github/dependabot.ymlに書いてあります。
Dependabotについてより詳しくは、Dependabot を使う - GitHub Docsを参照してください。
mdBook
GitHub Actions内で使用されるmdBookのバージョンは自動で更新されません。main.ymlおよびrelease.ymlにMDBOOK_VERSION: vX.Y.Zのような記述があります。mdBookのバージョン一覧はReleases · rust-lang/mdBookにリストされているので、そこを見つつバージョンを更新してください。バージョンの更新は1年に1度ほどで問題ないです。
PlatformIO
PlatformIOに関連する依存関係は2種類あります: PlatformIOそれ自身と、PlatformIO内で使用するツール群です。
PlatformIO自身
特に明記せず、最新版のPlatformIOを前提とします。GitHub Actions内でも最新版のPlatformIOを使用するように設定されています。PlatformIO関連で何か不具合があればバージョンの問題を考慮してみてください。
PlatformIO内の依存関係
これらはPlatformIOの設定ファイルplatformio.iniに記述されています。具体的な記述については以下を参照してください。
- "platformio.ini" (Project Configuration File) — PlatformIO latest documentation
- platform_packages — PlatformIO latest documentation
- lib_deps — PlatformIO latest documentation
特にGCCコンパイラのバージョンはplatformio/toolchain-gccarmnoneeabiで明記されているため、定期的(こちらも1年おきが目安)に更新する必要があります。
Nix, direnv
略