OpenMV MicroPython
はじめに¶
このガイドでは、バージョン管理のセットアップ、ポート用ソースコードの取得とビルド、ドキュメントのビルド、テストの実行、そして MicroPython コードベースのディレクトリ構造の説明までを、ステップバイステップで解説します。
git によるソース管理¶
MicroPython は GitHub 上でホストされており、ソース管理に Git を使用しています。ワークフローとしては、メインリポジトリとの間でコードをプル・プッシュします。以降の手順を進めるために、ご利用のオペレーティングシステムに対応したバージョンの Git をインストールしてください。
注釈
インストール手順のリファレンスについては、Git のインストール手順 を参照してください。基本的な git コマンドについては、この Git ハンドブック やインターネット上の他の資料で学べます。
注釈
.git-blame-ignore-revs ファイルが同梱されており、これによりコードのフォーマットのみを目的とし機能的な変更を伴わないコミットによって git blame の出力が乱雑になるのを防ぎます。使い方については git blame のドキュメント を参照してください。
コードを取得する¶
開発目的のために、MicroPython リポジトリのフォークを保持しておくことをお勧めします。ソースコードを取得する手順は次のとおりです。
リポジトリ https://github.com/micropython/micropython をフォークします
これで <https://github.com/<your-user-name>/micropython> にフォークができます。
次のコマンドを使ってフォークしたリポジトリをクローンします。
$ git clone https://github.com/<your-user-name>/micropython
次に、MicroPython プロジェクトで共同作業ができるように リモートリポジトリを設定 します。
リモートの upstream を設定します。
$ cd micropython
$ git remote add upstream https://github.com/micropython/micropython
コードの変更を共有しやすくするために、フォークしたリポジトリでは upstream と origin を設定するのが一般的です。独自のマッピングを維持することもできますが、origin を自分のフォークに、upstream をメインの MicroPython リポジトリにマッピングすることをお勧めします。
上記の設定が完了すると、構成は次のようになっているはずです。
$ git remote -v
origin https://github.com/<your-user-name>/micropython (fetch)
origin https://github.com/<your-user-name>/micropython (push)
upstream https://github.com/micropython/micropython (fetch)
upstream https://github.com/micropython/micropython (push)
これでソースコードのコピーが手元に揃いました。デフォルトでは master ブランチを指しています。今後の開発に備えて、開発用ブランチで作業することをお勧めします。
$ git checkout -b dev-branch
ブランチ名は任意に付けられます。別のブランチに切り替えるたびに、MicroPython をコンパイルし直す必要があります。
コードをコンパイル・ビルドする¶
MicroPython をコンパイルする際は、特定の port をコンパイルし、通常は特定の ボード を対象とします。まず、必要な依存関係をインストールします。次に、コンパイルとビルドを正常に行えるようにするため、先に MicroPython クロスコンパイラをビルドします。これは特に Linux 上でコンパイルする場合に当てはまります。Windows 向けの手順は後のセクションで説明します。
必要な依存関係¶
Linux 用に必要な依存関係をインストールします。
$ sudo apt-get install build-essential libffi-dev git pkg-config
stm32 ポートには、ARM クロスコンパイラが必要です。
$ sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi
最新の詳細については ARM GCC ツールチェーン を参照してください。
Python 3 も必要です。システムで Python が利用可能かどうかを確認してください。
$ python3
Python 3.5.0 (default, Jul 17 2020, 14:04:10)
[GCC 5.4.0 20160609] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
サポートされているすべてのポートには、それぞれ異なる依存関係の要件があります。各ポートの readme ファイル を参照してください。
MicroPython クロスコンパイラのビルド¶
ほぼすべてのポートでは、ポートのファームウェアに含める Python コードを事前にコンパイルするために、まず mpy-cross をビルドする必要があります。
$ cd mpy-cross
$ make
注釈
mpy-cross は、ターゲットのアーキテクチャではなくホストのアーキテクチャ向けにビルドする必要がある点に注意してください。
ビルドに成功すると、次のようなメッセージが表示されるはずです。
LINK mpy-cross
text data bss dec hex filename
279328 776 880 280984 44998 mpy-cross
注釈
mpy-cross ディレクトリに移動せずに 1 つのコマンドでクロスコンパイラをビルドするには、make -C mpy-cross を使用します。そうしない場合、次の手順のために cd .. を実行する必要があります。
MicroPython の Unix ポートのビルド¶
Unix ポートは、Linux、macOS、その他の Unix 系オペレーティングシステム上で動作する MicroPython のバージョンです。コードをテストするためにデバイスへデプロイする必要がなくなるため、MicroPython の開発に非常に役立ちます。多くの点で、CPython の python バイナリと同じように動作します。
Unix ポート向けにビルドするには、必要な依存関係のセクションで詳述されているとおり、Linux 関連のすべての依存関係がインストールされていることを確認してください。このポートに必要なすべての依存関係がインストールされていることを確認するには、必要な依存関係 を参照してください。また、gcc と GNU make が動作する環境が整っていることも確認してください。以下の例では Ubuntu 20.04 を使用していますが、他の Unix 系でもわずかな変更で動作するはずです。
$ gcc --version
gcc (Ubuntu 9.3.0-10ubuntu2) 9.3.0
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
次にビルドします。
$ cd ports/unix
$ make submodules
$ make
MicroPython が正しくビルドされた場合、次のように表示されます。
LINK micropython
text data bss dec hex filename
412033 5680 2496 420209 66971 micropython
では実行してみましょう。
$ ./micropython
MicroPython v1.13-38-gc67012d-dirty on 2020-09-13; linux version
Use Ctrl-D to exit, Ctrl-E for paste mode
>>> print("hello world")
hello world
>>>
Windows ポートのビルド¶
Windows ポートには、micropython.exe をビルドするために使用できる Visual Studio プロジェクトファイル micropython.vcxproj が含まれています。これは Visual Studio で開くか、コマンドラインから msbuild を使ってビルドできます。あるいは、Cygwin を使った Windows 上、または Linux 上で mingw を使ってビルドすることもできます。詳細については Windows ポートのドキュメント を参照してください。
STM32 ポートのビルド¶
Unix ポートと同様に、必要な依存関係 セクションで詳述されているとおり、必要な依存関係をいくつかインストールしてからビルドします。
$ cd ports/stm32
$ make submodules
$ make
ファームウェアのフラッシュに関する詳細は、stm32 のドキュメント を参照してください。
注釈
このポートに必要なすべての依存関係がインストールされていることを確認するには、必要な依存関係 を参照してください。クロスコンパイラが必要です。arm-none-eabi-gcc も $PATH に含まれているか、環境変数の設定または make のコマンドライン引数によって CROSS_COMPILE で手動で指定する必要があります。
使用するボードを指定することもできます。
$ cd ports/stm32
$ make BOARD=<board> submodules
$ make BOARD=<board>
利用可能なボードについては ports/stm32/boards を参照してください。例えば "OPENMV4" や "OPENMV4P" などです。
ドキュメントのビルド¶
MicroPython のドキュメントは Sphinx を使って作成されています。すでに Python をインストールしている場合は、pip を使って Sphinx をインストールします。仮想環境を使用することをお勧めします。
$ python3 -m venv env
$ source env/bin/activate
$ pip install -r docs/requirements.txt
docs ディレクトリに移動します。
$ cd docs
ドキュメントをビルドします。
$ make html
ローカルでドキュメントを表示するには、ブラウザで docs/build/html/index.html を開きます。Read the Docs を使用するには、ドキュメントのインポート に関するドキュメントを参照してください。
テストの実行¶
Unix ポートでテストスイート内のすべてのテストを実行するには、次のようにします。
$ cd ports/unix
$ make test
USB 経由で接続されたボード/デバイス上で一部のテストを実行するには、次のようにします。
$ cd tests
$ ./run-tests.py -t /dev/ttyACM0
あわせて テストの作成 も参照してください。
開発者向けの追加の make ターゲット¶
make ベースのすべてのポートには、特定のオブジェクトファイルのサイズを表示するターゲットがあります。変更が単一のファイルに限定されている場合、より小さい代替案を見つけるためにバリエーションをテストする際に便利です。
例えば、unix の標準ビルドを行う際に py/ ディレクトリ内の objstr.o のサイズを表示するには、次のようにします。
$ make build-standard/py/objstr.sz
同様に、ファイルのプリプロセス済みバージョンを保存するターゲットもあります。
$ make build-standard/py/objstr.pp
ports/unix には、テストの実行に関連する追加のターゲットがあります。
$ make test//int # Run all tests matching the pattern "int"
$ make test/ports/unix # Run all tests in ports/unix
$ make test-failures # Re-run only the failed tests
$ make print-failures # print the differences for failed tests
$ make clean-failures # delete the .exp and .out files from failed tests
ci.sh をローカルで使用する¶
MicroPython は継続的インテグレーションに GitHub Actions を使用しています。特定の CI システムへの依存を減らすため、Unix ベースのビルドの実際のビルド手順はファイル tools/ci.sh に記述されています。これは、いくつかの注意点はあるものの、開発者のデスクトップ上でスクリプトとして使用することもできます。
ほとんどの手順では、CI 中に使用されるものと同様の Ubuntu/Debian システムが想定されています。
一部の特定の手順では、特定の Ubuntu バージョンが想定されています。
セットアップ手順では、パッケージをインストールしたり、インターネットからソフトウェアをダウンロード・インストールしたりするために、システムのパッケージマネージャーが呼び出される場合があります。
コマンドの一覧を含む使用方法のメッセージを取得するには、次のようにします。
$ tools/ci.sh --help
例として、unix の minimal ポートを次のようにビルドおよびテストできます。
$ tools/ci.sh unix_minimal_build unix_minimal_run_tests
bash シェルを使用している場合は、タブ補完付きの ci コマンドを追加できます。
$ eval $(tools/ci.sh --bash-completion)
zsh シェルの場合は、--bash-completion を --zsh-completion に置き換えます。fish シェルの場合は、--bash-completion を --fish-completion に置き換えます。
次に、以下を入力します。
$ ci unix_cov<tab>
これにより、ci のステップ名が unix_coverage_ まで補完されます。タブをもう一度押すと、一致するステップの一覧が表示されます。
$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…
フォルダー構造¶
特定の実装の詳細がどこにあるかという観点で、注意すべきディレクトリがいくつかあります。以下は、ソースコードのトップレベルフォルダーの内訳です。
py
コンパイラ、ランタイム、コアライブラリの実装が含まれています。
mpy-cross
Python スクリプトをバイトコードに事前コンパイルする MicroPython クロスコンパイラが含まれています。
ports
サポートされているすべてのポート向けの MicroPython の各バージョンのコードです。
lib
任意のポートで使用される低レベルの C ライブラリで、その大半はサードパーティのライブラリです。
drivers
特定のハードウェア向けのドライバーが含まれており、複数のポートをまたいで動作することを想定しています。
extmod
より多くの非コアモジュールの C 実装が含まれています。
docs
https://docs.micropython.org/ で公開されている標準ドキュメントが含まれています。
tests
テストスイートの実装です。
tools
ビルドおよび CI プロセスで使用されるスクリプトのほか、
mpremoteなどのユーザーツールが含まれています。
examples
MicroPython をライブラリとしてビルドするためのサンプルコードと、ネイティブモジュールのサンプルコードです。