スタートアップガイド
このガイドでは、バージョン管理の設定、ポートのためのソースコードのコピー取得とビルド、ドキュメントのビルド、テストの実行、MicroPython コードベースのディレクトリ構造について順を追って説明します。
git によるソース管理
MicroPython は GitHub でホストされており、ソース管理に Git を使っています。ワークフローは、コードをメインリポジトリから pull したり、メインリポジトリに push するようなことです。お使いのオペレーティングシステムに対応したバージョンの Git をインストールして、残りの手順を実行してください。
注釈
Git のインストール手順については 使い始める - Gitのインストール を参考にしてください。基本的なGitコマンドについては、この Git ハンドブックや他のインターネット上の情報から学べます。
注釈
.git-blame-ignore-revs ファイルをインクルードすることで、コードのフォーマットのみで機能的な変更を伴わないコミットで git blame の出力が乱雑になるのを防ぐことができます。このファイルの使い方については git blame documentation を参照してください。
コードの取得
開発するには MicroPython のリポジトリのフォークを自身で管理することをお勧めします。ソースコードを入手する手順は以下の通りです。
リポジトリ https://github.com/micropython/micropython をフォークします
自身のフォーク <https://github.com/<your-user-name>/micropython> ができあがります。
次のコマンドでフォークしたリポジトリをクローンします:
$ git clone https://github.com/<your-user-name>/micropython
次に MicroPython プロジェクトで共同作業ができるように リモートリポジトリを設定 します。
リモートアップストリームを設定します:
$ 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)
これでソースコードのコピーができたはずです。デフォルトでは、マスターブランチを指しています。さらなる開発に備えるために、開発ブランチで作業することをお勧めします。
$ git checkout -b dev-branch
開発ブランチにはどんな名前をつけても構いません。別のブランチに変更するときには MicroPython をコンパイルすることになるでしょう。
コードのコンパイルとビルド
MicroPython をコンパイルするときは、特定の ポート 、通常は特定の ボード をターゲットにしてコンパイルします。まずは必要な依存関係をインストールすることから始めます。その後 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 クロスコンパイラのビルド
ほとんどすべてのポートは最初に mpy-cross をビルドする必要があります。こえは、ポートのファームウェアに含まれる Python コードをプリコンパイルするためのものです:
$ cd mpy-cross
$ make
注釈
mpy-cross はターゲットアーキテクチャではなくホストアーキテクチャ用にビルドしなければならないことに注意してください。
ビルドに成功した場合、次のようなメッセージが表示されるはずです:
LINK mpy-cross
text data bss dec hex filename
279328 776 880 280984 44998 mpy-cross
注釈
mpy-cross ディレクトリに移動しなくても make -C mpy-cross を使えば1つのステートメントでクロスコンパイラをビルドできます。mpy-cross ディレクトリに移動してからビルドした場合は cd .. することになります。
MicroPython の Unix ポートのビルド
Unix ポートは、Linux や macOS などの Unix ライクなOSで動作するバージョンの 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.then build:
$ 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 ポートには Visual Studio のプロジェクトファイル micropython.vcxproj が含まれており、これを使って micropython.exe をビルドすることができます。このファイルは Visual Studio で開くことも、msbuild を使ってコマンドラインからビルドすることもできます。Cygwin を使った Windows でもLinuxでも、mingw を使ってビルドできます。詳細については windows ポートのドキュメント を参照してください。
STM32 ポートのビルド
Unix ポートと同様、 必要な依存パッケージ のセクションで説明されているように、必要な依存関係をインストールしてからビルドする必要があります:
$ cd ports/stm32
$ make submodules
$ make
ファームウェアのフラッシュの詳細については stm32 のドキュメント を参照してください。
注釈
このポートのためにすべての依存パッケージがインストールされていることを確認するには 必要な依存パッケージ を参照してください。 arm-one-eabi-gcc は $PATH にあるか、環境変数の設定または make コマンドラインの引数で CROSS_COMPILE に手動で指定する必要があります。
使用するボードを指定することもできます:
$ cd ports/stm32
$ make BOARD=<board> submodules
$ make BOARD=<board>
利用可能なボードについては ports/stm32/boards を参照してください。 "PYBV11" や "NUCLEO_WB55" などがあります。
ドキュメントのビルド
MicroPython のドキュメントは Sphinx を使って作成しています。すでに Python をインストールしている場合は pip を使ってSphinxをインストールしてください。仮想環境を利用することをお勧めします:
$ python3 -m venv env
$ source env/bin/activate
$ pip install -r docs/requirements.txt
docs ディレクトリに移動します:
$ cd docs
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 # パターン "int" にマッチすべてのテストを実行
$ make test/ports/unix # ports/unix にあるすべてのテストを実行
$ make test-failures # 失敗したテストだけを再実行
$ make print-failures # 失敗したテストの差分を出力
$ make clean-failures # 失敗したテストから .exp と .out ファイルを削除
ci.sh のローカルでの使用
MicroPython は継続的インテグレーションに GitHub Actions を使います。特定の CI システムへの依存を減らすため、Unix ベースのビルドの実際のビルド手順はファイル tools/ci.sh に記述されています。これは開発者のデスクトップ上でスクリプトとして使用することもできますが、次の点に注意してください:
ほとんどの手順では、CI で使う環境に Ubuntu/Debian システムと同様のものが想定されています。
いくつかの具体的な手順では、特定の Ubuntu バージョンが前提となります。
セットアップ手順では、システムパッケージマネージャーを呼び出してパッケージをインストールしたり、インターネットからソフトウェアをダウンロードしてインストールしたりする場合があります。
コマンドのリストを含む使用方法メッセージを出すには、次のコマンドを実行します:
$ tools/ci.sh --help
たとえば、次のようにして UNIX の最小限のポートをビルドしてテストできます。
$ tools/ci.sh unix_minimal_build unix_minimal_run_tests
bash シェルを使っているなら、Tab 補完で ci コマンドを追加できます。
$ eval $(tools/ci.sh --bash-completion)
zsh を使っている場合は --bash-completion を --zsh-completion に置き換えてください。fish を使っている場合は --bash-completion を --fish-completion に置き換えてください。
そして次のように入力してみてください:
$ ci unix_cov<tab>
これにより、ci 手順名が unix_coverage_ に補完されます。Tab キーをもう一度押すと、一致する手順のリストが表示されます。
$ 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 プロセスで使うスクリプト、および
pyboard.pyやmpremoteなどのユーザーツールが含まれています。
examples
MicroPython のライブラリやネイティブモジュールとしてビルドするためのコード例です。