スタートアップガイド¶
このガイドでは、バージョン管理の設定、ポートのためのソースコードのコピー取得とビルド、ドキュメントのビルド、テストの実行、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 も必要です。今のところ Python 2 でも大丈夫ですが、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 --target minimal --device /dev/ttyACM0
テストの作成 も参照してください。
フォルダ構造¶
特定の実装の詳細がどこにあるかという点で注意すべきディレクトリがいくつかあります。以下はソースコードのトップレベルのフォルダの内訳です。
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 のライブラリやネイティブモジュールとしてビルドするためのコード例です。