Memulai

Panduan ini mencakup proses langkah demi langkah untuk menyiapkan kontrol versi, mendapatkan dan membangun salinan kode sumber untuk suatu port, membangun dokumentasi, menjalankan pengujian, dan deskripsi struktur direktori basis kode MicroPython.

Kontrol sumber dengan git

MicroPython dihosting di GitHub dan menggunakan Git untuk kontrol sumber. Alur kerja sedemikian rupa sehingga kode ditarik dan didorong ke dan dari repositori utama. Instal versi Git yang sesuai untuk sistem operasi Anda untuk mengikuti langkah-langkah berikutnya.

Catatan

Untuk referensi instruksi instalasi, silakan lihat instruksi instalasi Git. Pelajari perintah-perintah git dasar di Git Handbook ini atau sumber lain di internet.

Catatan

File .git-blame-ignore-revs disertakan untuk menghindari keluaran git blame menjadi berantakan oleh commit yang hanya untuk memformat kode tetapi tidak memiliki perubahan fungsional. Lihat dokumentasi git blame tentang cara menggunakannya.

Dapatkan kode

Disarankan agar Anda memelihara fork repositori MicroPython untuk keperluan pengembangan Anda. Proses mendapatkan kode sumber meliputi hal-hal berikut:

  1. Fork repositori https://github.com/micropython/micropython

  2. Anda sekarang akan memiliki fork di <https://github.com/<your-user-name>/micropython>.

  3. Clone repositori yang telah di-fork menggunakan perintah berikut:

$ git clone https://github.com/<your-user-name>/micropython

Kemudian, konfigurasi repositori remote untuk dapat berkolaborasi dalam proyek MicroPython.

Konfigurasi remote upstream:

$ cd micropython
$ git remote add upstream https://github.com/micropython/micropython

Adalah umum untuk mengkonfigurasi upstream dan origin pada repositori yang di-fork untuk membantu berbagi perubahan kode. Anda dapat memelihara pemetaan Anda sendiri tetapi disarankan bahwa origin memetakan ke fork Anda dan upstream ke repositori MicroPython utama.

Setelah konfigurasi di atas, pengaturan Anda harus serupa dengan ini:

$ 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)

Anda sekarang harus memiliki salinan kode sumber. Secara default, Anda menunjuk ke cabang master. Untuk mempersiapkan pengembangan lebih lanjut, disarankan untuk bekerja pada cabang pengembangan.

$ git checkout -b dev-branch

Anda dapat memberinya nama apa saja. Anda harus mengkompilasi MicroPython setiap kali Anda beralih ke cabang yang berbeda.

Kompilasi dan bangun kode

Saat mengkompilasi MicroPython, Anda mengkompilasi port tertentu, biasanya menargetkan papan tertentu. Mulailah dengan menginstal dependensi yang diperlukan. Kemudian bangun kompiler silang MicroPython sebelum Anda dapat berhasil mengkompilasi dan membangun. Ini berlaku khususnya saat menggunakan Linux untuk mengkompilasi. Instruksi Windows disediakan di bagian selanjutnya.

Dependensi yang diperlukan

Instal dependensi yang diperlukan untuk Linux:

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

Untuk port stm32, kompiler silang ARM diperlukan:

$ sudo apt-get install gcc-arm-none-eabi libnewlib-arm-none-eabi

Lihat ARM GCC toolchain untuk detail terbaru.

Python 3 juga diperlukan. Periksa apakah Python tersedia di sistem Anda:

$ 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.
>>>

Semua port yang didukung memiliki persyaratan dependensi yang berbeda, lihat masing-masing file readme-nya.

Membangun kompiler silang MicroPython

Hampir semua port memerlukan pembangunan mpy-cross terlebih dahulu untuk melakukan pra-kompilasi kode Python yang akan disertakan dalam firmware port:

$ cd mpy-cross
$ make

Catatan

Perhatikan bahwa, mpy-cross harus dibangun untuk arsitektur host dan bukan arsitektur target.

Jika berhasil dibangun, Anda akan melihat pesan yang serupa dengan ini:

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

Catatan

Gunakan make -C mpy-cross untuk membangun kompiler silang dalam satu pernyataan tanpa berpindah ke direktori mpy-cross, jika tidak, Anda perlu melakukan cd .. untuk langkah-langkah berikutnya.

Membangun port Unix dari MicroPython

Port Unix adalah versi MicroPython yang berjalan di Linux, macOS, dan sistem operasi mirip Unix lainnya. Ini sangat berguna untuk mengembangkan MicroPython karena menghindari keharusan menerapkan kode Anda ke perangkat untuk mengujinya. Dalam banyak hal, ini bekerja seperti binary python CPython.

Untuk membangun port Unix, pastikan semua dependensi terkait Linux telah diinstal sebagaimana dijelaskan di bagian dependensi yang diperlukan. Lihat Dependensi yang diperlukan untuk memastikan bahwa semua dependensi diinstal untuk port ini. Juga, pastikan Anda memiliki lingkungan kerja untuk gcc dan GNU make. Ubuntu 20.04 telah digunakan untuk contoh di bawah ini tetapi unix lainnya seharusnya berfungsi dengan sedikit modifikasi:

$ 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.

kemudian bangun:

$ cd ports/unix
$ make submodules
$ make

Jika MicroPython berhasil dibangun, Anda akan melihat yang berikut:

LINK micropython
   text         data     bss     dec     hex filename
 412033         5680    2496  420209   66971 micropython

Sekarang jalankan:

$ ./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
>>>

Membangun port Windows

Port Windows menyertakan file proyek Visual Studio micropython.vcxproj yang dapat Anda gunakan untuk membangun micropython.exe. File ini dapat dibuka di Visual Studio atau dibangun dari baris perintah menggunakan msbuild. Sebagai alternatif, ini dapat dibangun menggunakan mingw, baik di Windows dengan Cygwin, atau di Linux. Lihat dokumentasi port windows untuk informasi lebih lanjut.

Membangun port STM32

Seperti port Unix, Anda perlu menginstal beberapa dependensi yang diperlukan sebagaimana dijelaskan di bagian Dependensi yang diperlukan, kemudian bangun:

$ cd ports/stm32
$ make submodules
$ make

Silakan lihat dokumentasi stm32 untuk detail lebih lanjut tentang mem-flash firmware.

Catatan

Lihat Dependensi yang diperlukan untuk memastikan bahwa semua dependensi diinstal untuk port ini. Kompiler silang diperlukan. arm-none-eabi-gcc juga harus ada di $PATH atau ditentukan secara manual melalui CROSS_COMPILE, baik dengan mengatur variabel lingkungan atau dalam argumen baris perintah make.

Anda juga dapat menentukan papan mana yang akan digunakan:

$ cd ports/stm32
$ make BOARD=<board> submodules
$ make BOARD=<board>

Lihat ports/stm32/boards untuk papan yang tersedia. misalnya "OPENMV4" atau "OPENMV4P".

Membangun dokumentasi

Dokumentasi MicroPython dibuat menggunakan Sphinx. Jika Anda sudah menginstal Python, instal Sphinx menggunakan pip. Disarankan agar Anda menggunakan lingkungan virtual:

$ python3 -m venv env
$ source env/bin/activate
$ pip install -r docs/requirements.txt

Navigasi ke direktori docs:

$ cd docs

Bangun dokumentasi:

$ make html

Buka docs/build/html/index.html di browser Anda untuk melihat dokumentasi secara lokal. Lihat dokumentasi tentang mengimpor dokumentasi Anda untuk menggunakan Read the Docs.

Menjalankan pengujian

Untuk menjalankan semua pengujian dalam suite pengujian pada port Unix gunakan:

$ cd ports/unix
$ make test

Untuk menjalankan sekumpulan pengujian pada papan/perangkat yang terhubung melalui USB gunakan:

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

Lihat juga Menulis pengujian.

Target make tambahan untuk pengembang

Di semua port berbasis make, terdapat target untuk mencetak ukuran file objek tertentu. Ketika perubahan terbatas pada satu file, ini berguna saat menguji variasi untuk menemukan alternatif yang lebih kecil.

Sebagai contoh, untuk mencetak ukuran objstr.o di direktori py/ saat membuat build standar unix:

$ make build-standard/py/objstr.sz

Demikian pula, ada target untuk menyimpan versi yang telah diproses sebelumnya dari sebuah file:

$ make build-standard/py/objstr.pp

Di ports/unix terdapat target tambahan yang terkait dengan menjalankan pengujian:

$ 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

Menggunakan ci.sh secara lokal

MicroPython menggunakan GitHub Actions untuk continuous integration. Untuk mengurangi ketergantungan pada sistem CI tertentu, langkah-langkah build aktual untuk build berbasis Unix ada di file tools/ci.sh. Ini juga dapat digunakan sebagai skrip di desktop pengembang, dengan beberapa catatan:

  • Untuk sebagian besar langkah, diasumsikan sistem Ubuntu/Debian yang serupa dengan yang digunakan selama CI.

  • Beberapa langkah tertentu mengasumsikan versi Ubuntu tertentu.

  • Langkah-langkah pengaturan mungkin memanggil manajer paket sistem untuk menginstal paket, mengunduh dan menginstal perangkat lunak dari internet, dll.

Untuk mendapatkan pesan penggunaan termasuk daftar perintah, jalankan:

$ tools/ci.sh --help

Sebagai contoh, Anda dapat membangun dan menguji port minimal unix dengan:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

Jika Anda menggunakan shell bash, Anda dapat menambahkan perintah ci dengan tab completion:

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

Untuk shell zsh, ganti --bash-completion dengan --zsh-completion. Untuk shell fish, ganti --bash-completion dengan --fish-completion.

Kemudian, ketik:

$ ci unix_cov<tab>

Ini akan melengkapi nama langkah ci menjadi unix_coverage_. Menekan tab untuk kedua kalinya akan menampilkan daftar langkah yang cocok:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Struktur folder

Ada beberapa direktori yang perlu diperhatikan dalam hal di mana detail implementasi tertentu berada. Berikut adalah rincian folder tingkat atas dalam kode sumber.

py

Berisi implementasi compiler, runtime, dan pustaka inti.

mpy-cross

Memiliki kompiler silang MicroPython yang melakukan pra-kompilasi skrip Python menjadi bytecode.

ports

Kode untuk semua versi MicroPython untuk port yang didukung.

lib

Pustaka C tingkat rendah yang digunakan oleh port mana pun yang sebagian besar merupakan pustaka pihak ketiga.

drivers

Memiliki driver untuk perangkat keras tertentu dan dimaksudkan untuk bekerja di berbagai port.

extmod

Berisi implementasi C dari modul-modul non-inti tambahan.

docs

Memiliki dokumentasi standar yang ditemukan di https://docs.micropython.org/.

tests

Implementasi suite pengujian.

tools

Berisi skrip yang digunakan oleh proses build dan CI, serta alat pengguna seperti mpremote.

examples

Kode contoh untuk membangun MicroPython sebagai pustaka serta modul native.