Başlangıç

Bu kılavuz; sürüm kontrolünün kurulması, bir port için kaynak kodun bir kopyasının edinilmesi ve derlenmesi, dokümantasyonun oluşturulması, testlerin çalıştırılması ve MicroPython kod tabanının dizin yapısının açıklanması gibi adımları adım adım kapsamaktadır.

git ile sürüm kontrolü

MicroPython, GitHub üzerinde barındırılır ve sürüm kontrolü için Git kullanır. İş akışı, kodun ana depodan çekilip oraya gönderilmesi şeklindedir. Geri kalan adımları takip edebilmek için işletim sisteminize uygun Git sürümünü kurun.

Not

Kurulum talimatlarına ilişkin bir referans için lütfen Git kurulum talimatlarına bakın. Temel git komutlarını bu Git El Kitabı’ndan veya internetteki diğer kaynaklardan öğrenebilirsiniz.

Not

Yalnızca kodu biçimlendirmeye yönelik olup işlevsel bir değişiklik içermeyen commit’lerin git blame çıktısını dağınık hale getirmesini önleyen bir .git-blame-ignore-revs dosyası dahil edilmiştir. Bunun nasıl kullanılacağı için git blame dokümantasyonuna bakın.

Kodu edinin

Geliştirme amaçlarınız için MicroPython deposunun bir fork’unu (çatalını) tutmanız önerilir. Kaynak kodu edinme süreci şunları içerir:

  1. https://github.com/micropython/micropython deposunu fork’layın

  2. Artık <https://github.com/<your-user-name>/micropython> adresinde bir fork’unuz olacak.

  3. Fork’lanan depoyu aşağıdaki komutu kullanarak klonlayın:

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

Ardından, MicroPython projesinde iş birliği yapabilmek için uzak depoları yapılandırın.

Uzak upstream’i yapılandırın:

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

Kod değişikliklerinin paylaşımına yardımcı olmak için fork’lanan bir depoda upstream ve origin yapılandırmak yaygındır. Kendi eşlemenizi tutabilirsiniz, ancak origin‘in fork’unuza ve upstream‘in ana MicroPython deposuna eşlenmesi önerilir.

Yukarıdaki yapılandırmadan sonra kurulumunuz buna benzer olmalıdır:

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

Artık kaynak kodun bir kopyasına sahip olmalısınız. Varsayılan olarak master dalını işaret edersiniz. Daha fazla geliştirmeye hazırlanmak için bir geliştirme dalında çalışmanız önerilir.

$ git checkout -b dev-branch

Ona istediğiniz adı verebilirsiniz. Farklı bir dala her geçtiğinizde MicroPython’u yeniden derlemeniz gerekecektir.

Kodu derleyin ve oluşturun

MicroPython’u derlerken, genellikle belirli bir board hedefleyerek belirli bir port derlersiniz. Gerekli bağımlılıkları kurarak başlayın. Ardından, başarıyla derleyip oluşturabilmeniz için önce MicroPython çapraz derleyicisini oluşturun. Bu, özellikle derleme için Linux kullanırken geçerlidir. Windows talimatları daha sonraki bir bölümde verilmiştir.

Gerekli bağımlılıklar

Linux için gerekli bağımlılıkları kurun:

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

stm32 portu için ARM çapraz derleyicisi gereklidir:

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

En güncel ayrıntılar için ARM GCC araç zincirine bakın.

Python 3 de gereklidir. Sisteminizde Python’un mevcut olup olmadığını kontrol edin:

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

Desteklenen tüm portların farklı bağımlılık gereksinimleri vardır; bunların ilgili readme dosyalarına bakın.

MicroPython çapraz derleyicisini oluşturma

Neredeyse tüm portlar, port aygıt yazılımına (firmware) dahil edilecek Python kodunun ön derlemesini gerçekleştirmek için önce mpy-cross‘un oluşturulmasını gerektirir:

$ cd mpy-cross
$ make

Not

mpy-cross‘un hedef mimariye değil, ana bilgisayar (host) mimarisine yönelik olarak oluşturulması gerektiğine dikkat edin.

Başarıyla oluşturulduysa buna benzer bir mesaj görmelisiniz:

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

Not

Çapraz derleyiciyi mpy-cross dizinine geçmeden tek bir ifadeyle oluşturmak için make -C mpy-cross kullanın; aksi takdirde sonraki adımlar için cd .. yapmanız gerekecektir.

MicroPython’un Unix portunu oluşturma

Unix portu, MicroPython’un Linux, macOS ve diğer Unix benzeri işletim sistemlerinde çalışan bir sürümüdür. Kodunuzu test etmek için bir cihaza dağıtma zorunluluğunu ortadan kaldırdığından MicroPython geliştirmek için son derece kullanışlıdır. Birçok yönden CPython’un python ikili dosyası gibi çalışır.

Unix portu için derleme yapmak üzere, gerekli bağımlılıklar bölümünde ayrıntılı olarak açıklandığı gibi Linux ile ilgili tüm bağımlılıkların kurulu olduğundan emin olun. Bu port için tüm bağımlılıkların kurulu olduğundan emin olmak amacıyla Gerekli bağımlılıklar bölümüne bakın. Ayrıca gcc ve GNU make için çalışan bir ortamınız olduğundan emin olun. Aşağıdaki örnek için Ubuntu 20.04 kullanılmıştır, ancak diğer unix sistemleri de küçük değişikliklerle çalışmalıdır:

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

ardından derleyin:

$ cd ports/unix
$ make submodules
$ make

MicroPython doğru bir şekilde oluşturulduysa şunu görmelisiniz:

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

Şimdi çalıştırın:

$ ./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 portunu oluşturma

Windows portu, micropython.exe dosyasını oluşturmak için kullanabileceğiniz bir Visual Studio proje dosyası olan micropython.vcxproj içerir. Bu dosya Visual Studio’da açılabilir veya msbuild kullanılarak komut satırından oluşturulabilir. Alternatif olarak, mingw kullanılarak ya Windows’ta Cygwin ile ya da Linux üzerinde oluşturulabilir. Daha fazla bilgi için windows portu dokümantasyonuna bakın.

STM32 portunu oluşturma

Unix portunda olduğu gibi, Gerekli bağımlılıklar bölümünde ayrıntılı olarak açıklanan bazı gerekli bağımlılıkları kurmanız ve ardından derlemeniz gerekir:

$ cd ports/stm32
$ make submodules
$ make

Aygıt yazılımını (firmware) flash’lama hakkında daha fazla ayrıntı için lütfen stm32 dokümantasyonuna bakın.

Not

Bu port için tüm bağımlılıkların kurulu olduğundan emin olmak amacıyla Gerekli bağımlılıklar bölümüne bakın. Çapraz derleyici gereklidir. arm-none-eabi-gcc de $PATH içinde bulunmalı veya ortam değişkenini ayarlayarak ya da make komut satırı argümanlarıyla CROSS_COMPILE aracılığıyla manuel olarak belirtilmelidir.

Ayrıca hangi kartı kullanacağınızı da belirtebilirsiniz:

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

Mevcut kartlar için ports/stm32/boards dizinine bakın. Örneğin “OPENMV4” veya “OPENMV4P”.

Dokümantasyonu oluşturma

MicroPython dokümantasyonu Sphinx kullanılarak oluşturulur. Python’u zaten kurduysanız, pip kullanarak Sphinx‘i kurun. Bir sanal ortam kullanmanız önerilir:

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

docs dizinine gidin:

$ cd docs

Dokümanları oluşturun:

$ make html

Dokümanları yerel olarak görüntülemek için tarayıcınızda docs/build/html/index.html dosyasını açın. Read the Docs kullanmak için dokümantasyonunuzu içe aktarma hakkındaki dokümantasyona bakın.

Testleri çalıştırma

Test paketindeki tüm testleri Unix portunda çalıştırmak için şunu kullanın:

$ cd ports/unix
$ make test

USB üzerinden bağlı bir kartta/cihazda belirli bir test seçkisini çalıştırmak için şunu kullanın:

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

Ayrıca bkz. Test yazma.

Geliştiriciler için ek make hedefleri

make tabanlı tüm portlarda, belirli bir nesne dosyasının boyutunu yazdıran bir hedef vardır. Bir değişiklik tek bir dosyayla sınırlı olduğunda, daha küçük alternatifler bulmak için varyasyonları test ederken bu kullanışlıdır.

Örneğin, unix standart derlemesi yaparken py/ dizinindeki objstr.o dosyasının boyutunu yazdırmak için:

$ make build-standard/py/objstr.sz

Benzer şekilde, bir dosyanın ön işlenmiş sürümünü kaydeden bir hedef de vardır:

$ make build-standard/py/objstr.pp

ports/unix içinde testleri çalıştırmaya ilişkin ek hedefler vardır:

$ 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’i yerel olarak kullanma

MicroPython, sürekli entegrasyon (continuous integration) için GitHub Actions kullanır. Herhangi bir belirli CI sistemine olan bağımlılığı azaltmak için, Unix tabanlı derlemelere ilişkin asıl derleme adımları tools/ci.sh dosyasında yer alır. Bu, bazı uyarılarla birlikte geliştirici masaüstlerinde de bir betik olarak kullanılabilir:

  • Çoğu adım için, CI sırasında kullanılana benzer bir Ubuntu/Debian sistemi varsayılır.

  • Bazı belirli adımlar, belirli Ubuntu sürümlerini varsayar.

  • Kurulum adımları, paketleri kurmak, internetten yazılım indirip kurmak vb. için sistem paket yöneticisini çağırabilir.

Komut listesini de içeren bir kullanım mesajı almak için şunu çalıştırın:

$ tools/ci.sh --help

Örnek olarak, unix minimal portunu şu şekilde derleyip test edebilirsiniz:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

bash kabuğunu kullanıyorsanız, sekme tamamlamalı bir ci komutu ekleyebilirsiniz:

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

zsh kabuğu için --bash-completion‘ı --zsh-completion ile değiştirin. fish kabuğu için --bash-completion‘ı --fish-completion ile değiştirin.

Ardından şunu yazınca:

$ ci unix_cov<tab>

Bu, ci adım adını unix_coverage_ olarak tamamlayacaktır. Sekmeye ikinci kez basıldığında eşleşen adımların listesi gösterilecektir:

$ ci unix_coverage_<tab>
unix_coverage_32bit_build
unix_coverage_32bit_run_native_mpy_tests…

Klasör yapısı

Belirli uygulama ayrıntılarının nerede olduğu açısından dikkat edilmesi gereken birkaç dizin vardır. Aşağıda, kaynak kodundaki üst düzey klasörlerin bir dökümü verilmiştir.

py

Derleyiciyi, çalışma zamanını ve çekirdek kütüphane uygulamasını içerir.

mpy-cross

Python betiklerini bayt koduna (bytecode) önceden derleyen MicroPython çapraz derleyicisini içerir.

ports

Desteklenen portlar için MicroPython’un tüm sürümlerine ait kodlar.

lib

Çoğunlukla 3. taraf kütüphaneler olan ve herhangi bir port tarafından kullanılan düşük seviyeli C kütüphaneleri.

drivers

Belirli donanımlar için sürücüleri içerir ve birden fazla portta çalışacak şekilde tasarlanmıştır.

extmod

Çekirdek olmayan daha fazla modülün bir C uygulamasını içerir.

docs

https://docs.micropython.org/ adresinde bulunan standart dokümantasyonu içerir.

tests

Test paketinin bir uygulaması.

tools

Derleme ve CI sürecinde kullanılan betiklerin yanı sıra mpremote gibi kullanıcı araçlarını da içerir.

examples

MicroPython’u bir kütüphane olarak ve ayrıca yerel (native) modüller olarak oluşturmaya yönelik örnek kod.