시작하기

이 가이드에서는 버전 관리 설정, 특정 포트의 소스 코드 사본을 받아 빌드하기, 문서 빌드, 테스트 실행 과정을 단계별로 다루며, MicroPython 코드베이스의 디렉터리 구조에 대한 설명도 함께 제공합니다.

git을 이용한 소스 관리

MicroPython은 GitHub 에서 호스팅되며 소스 관리에 Git 을 사용합니다. 작업 흐름은 메인 저장소로부터 코드를 가져오고(pull) 메인 저장소로 코드를 올리는(push) 방식입니다. 나머지 단계를 따라가려면 사용하는 운영체제에 맞는 Git 버전을 설치하세요.

참고

설치 방법에 대한 참고 자료는 Git 설치 안내 를 참고하세요. 기본적인 git 명령어는 이 Git 핸드북 이나 인터넷의 다른 자료에서 익힐 수 있습니다.

참고

기능 변경 없이 코드 포맷팅만을 위한 커밋 때문에 git blame 출력이 지저분해지는 것을 막아 주는 .git-blame-ignore-revs 파일이 포함되어 있습니다. 사용 방법은 git blame 문서 를 참고하세요.

코드 받기

개발 목적으로는 MicroPython 저장소의 포크(fork)를 유지하는 것을 권장합니다. 소스 코드를 받는 과정은 다음과 같습니다:

  1. https://github.com/micropython/micropython 저장소를 포크합니다

  2. 이제 <https://github.com/<your-user-name>/micropython> 에 포크가 생깁니다.

  3. 다음 명령으로 포크한 저장소를 클론합니다:

$ 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 포트의 경우 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 크로스 컴파일러 빌드하기

거의 모든 포트는 포트 펌웨어에 포함될 Python 코드를 사전 컴파일하기 위해 먼저 mpy-cross 를 빌드해야 합니다:

$ 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 를 사용하세요. 그렇지 않으면 다음 단계를 위해 cd .. 를 실행해야 합니다.

MicroPython의 Unix 포트 빌드하기

Unix 포트는 Linux, macOS 및 기타 Unix 계열 운영체제에서 실행되는 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.

그런 다음 빌드합니다:

$ 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 포트에는 micropython.exe를 빌드하는 데 사용할 수 있는 Visual Studio 프로젝트 파일 micropython.vcxproj가 포함되어 있습니다. 이 파일은 Visual Studio에서 열거나 msbuild를 사용해 명령줄에서 빌드할 수 있습니다. 또는 Cygwin이 설치된 Windows에서, 또는 Linux에서 mingw를 사용해 빌드할 수도 있습니다. 자세한 내용은 Windows 포트 문서 를 참고하세요.

STM32 포트 빌드하기

Unix 포트와 마찬가지로, 필수 의존성 절에서 설명한 대로 필요한 의존성을 설치한 다음 빌드해야 합니다:

$ cd ports/stm32
$ make submodules
$ make

펌웨어 플래시에 대한 자세한 내용은 stm32 문서 를 참고하세요.

참고

이 포트에 필요한 모든 의존성이 설치되어 있는지 확인하려면 필수 의존성 를 참고하세요. 크로스 컴파일러가 필요합니다. arm-none-eabi-gcc 도 $PATH에 있어야 하며, 그렇지 않으면 환경 변수를 설정하거나 make 명령줄 인수로 CROSS_COMPILE을 통해 수동으로 지정해야 합니다.

사용할 보드를 지정할 수도 있습니다:

$ 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 포트에서 테스트 스위트의 모든 테스트를 실행하려면 다음을 사용하세요:

$ 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       # 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은 지속적 통합(CI)에 GitHub Actions를 사용합니다. 특정 CI 시스템에 대한 의존성을 줄이기 위해 Unix 기반 빌드의 실제 빌드 단계는 tools/ci.sh 파일에 들어 있습니다. 이 파일은 다음과 같은 주의 사항과 함께 개발자 데스크톱에서 스크립트로도 사용할 수 있습니다:

  • 대부분의 단계는 CI에서 사용하는 것과 비슷한 Ubuntu/Debian 시스템을 가정합니다.

  • 일부 특정 단계는 특정 Ubuntu 버전을 가정합니다.

  • 설정 단계에서는 시스템 패키지 관리자를 호출해 패키지를 설치하거나, 인터넷에서 소프트웨어를 다운로드하고 설치하는 등의 작업을 수행할 수 있습니다.

명령 목록을 포함한 사용법 메시지를 보려면 다음을 실행하세요:

$ tools/ci.sh --help

예를 들어, 다음과 같이 unix minimal 포트를 빌드하고 테스트할 수 있습니다:

$ tools/ci.sh unix_minimal_build unix_minimal_run_tests

bash 셸을 사용한다면 탭 자동 완성이 지원되는 ci 명령을 추가할 수 있습니다:

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

zsh 셸의 경우 --bash-completion 을 --zsh-completion 으로 바꾸세요. fish 셸의 경우 --bash-completion 을 --fish-completion 으로 바꾸세요.

그런 다음 다음을 입력하면:

$ ci unix_cov<tab>

이렇게 하면 ci 단계 이름이 unix_coverage_ 까지 완성됩니다. 탭을 한 번 더 누르면 일치하는 단계 목록이 표시됩니다:

$ 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 과정에서 사용되는 스크립트와 mpremote 같은 사용자 도구가 들어 있습니다.

examples

MicroPython을 라이브러리로 빌드하기 위한 예제 코드와 네이티브 모듈 예제 코드입니다.