入門指南

本指南逐步說明如何設定版本控制、取得並建置某個 port 的原始碼副本、建置文件、執行測試，並描述 MicroPython 程式碼庫的目錄結構。

使用 git 進行原始碼控制

MicroPython 託管於 GitHub 上，並使用 Git 進行原始碼控制。其工作流程是從主儲存庫拉取程式碼以及推送程式碼至主儲存庫。請為您的作業系統安裝對應版本的 Git，以便完成後續步驟。

備註

關於安裝說明的參考資料，請參閱 Git 安裝說明。您可以透過這份 Git 手冊 或網路上的其他資源來學習基本的 git 指令。

備註

本專案包含一個 .git-blame-ignore-revs 檔案，可避免 git blame 的輸出被那些僅用於格式化程式碼、但沒有功能變更的提交所干擾。關於如何使用此檔案，請參閱 git blame 文件。

取得程式碼

建議您為了開發目的而維護一份 MicroPython 儲存庫的分叉（fork）。取得原始碼的流程包括下列步驟：

1. 分叉儲存庫 https://github.com/micropython/micropython

2. 您現在會擁有一個位於 <https://github.com/<your-user-name>/micropython> 的分叉。

3. 使用下列指令複製（clone）已分叉的儲存庫：

$ 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，通常針對某個特定的 board。請先安裝所需的相依套件，接著建置 MicroPython 交叉編譯器，然後才能順利編譯與建置。這特別適用於使用 Linux 進行編譯的情況。Windows 的說明會在後續章節中提供。

所需的相依套件

為 Linux 安裝所需的相依套件：

$ sudo apt-get install build-essential libffi-dev git pkg-config

對於 stm32 port，需要 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.
>>>

所有受支援的 port 都有不同的相依套件需求，請參閱各自的 readme 檔案。

建置 MicroPython 交叉編譯器

幾乎所有的 port 都需要先建置 mpy-cross，以便對將包含在 port 韌體中的 Python 程式碼進行預先編譯：

$ cd mpy-cross
$ make

備註

請注意，mpy-cross 必須針對主機架構建置，而非目標架構。

如果建置成功，您應該會看到類似這樣的訊息：

LINK mpy-cross
   text          data    bss     dec     hex filename
 279328          776     880  280984   44998 mpy-cross

備註

使用 make -C mpy-cross 可以用一道指令建置交叉編譯器，而不需切換到 mpy-cross 目錄；否則，您在後續步驟中將需要執行 cd ..。

建置 MicroPython 的 Unix port

Unix port 是可在 Linux、macOS 及其他類 Unix 作業系統上執行的 MicroPython 版本。由於它讓您不必將程式碼部署到裝置上即可測試，因此對開發 MicroPython 非常有用。在許多方面，它的運作方式很像 CPython 的 python 執行檔。

若要為 Unix port 進行建置，請確認已依照所需相依套件章節中的說明安裝所有與 Linux 相關的相依套件。請參閱 所需的相依套件 以確認此 port 所需的所有相依套件都已安裝。同時，請確認您擁有可正常運作的 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 port

Windows port 包含一個 Visual Studio 專案檔 micropython.vcxproj，您可以用它來建置 micropython.exe。它可以在 Visual Studio 中開啟，或使用 msbuild 從命令列建置。此外，也可以使用 mingw 進行建置，無論是在 Windows 中搭配 Cygwin，或是在 Linux 上皆可。更多資訊請參閱 windows port 文件。

建置 STM32 port

與 Unix port 一樣，您需要依照 所需的相依套件 章節中的說明安裝一些所需的相依套件，接著建置：

$ cd ports/stm32
$ make submodules
$ make

關於燒錄韌體的更多詳情，請參閱 stm32 文件。

備註

請參閱 所需的相依套件 以確認此 port 所需的所有相依套件都已安裝。需要使用交叉編譯器。arm-none-eabi-gcc 也應位於 $PATH 中，或透過 CROSS_COMPILE 手動指定，無論是設定環境變數，或是在 make 命令列引數中指定皆可。

您也可以指定要使用哪一塊開發板：

$ 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 port 上執行測試套件中的所有測試，請使用：

$ cd ports/unix
$ make test

若要在透過 USB 連接的開發板／裝置上執行部分選定的測試，請使用：

$ cd tests
$ ./run-tests.py -t /dev/ttyACM0

另請參閱 撰寫測試。

供開發者使用的其他 make 目標

在所有以 make 為基礎的 port 中，都有一個用於印出特定目的檔大小的目標。當變更僅限於單一檔案時，這在測試各種變化以尋找較小的替代方案時非常有用。

舉例來說，在進行 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 port：

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

如果您使用 bash shell，可以新增一個帶有 tab 自動補全功能的 ci 指令：

$ eval $(tools/ci.sh --bash-completion)

對於 zsh shell，請將 --bash-completion 替換為 --zsh-completion。對於 fish shell，請將 --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

包含編譯器、執行階段（runtime）以及核心程式庫的實作。

mpy-cross

包含 MicroPython 交叉編譯器，它會將 Python 指令碼預先編譯為位元組碼。

ports

所有受支援 port 的各個 MicroPython 版本的程式碼。

lib

供任何 port 使用的低階 C 程式庫，其中大多為第三方程式庫。

drivers

包含特定硬體的驅動程式，且設計為可跨多個 port 運作。

extmod

包含更多非核心模組的 C 實作。

docs

包含可在 https://docs.micropython.org/ 上找到的標準文件。

tests

測試套件的實作。

tools

包含建置與 CI 流程所使用的指令碼，以及如 mpremote 等使用者工具。

examples

用於將 MicroPython 建置為程式庫以及原生模組的範例程式碼。