Skip to content

Latest commit

 

History

History
314 lines (196 loc) · 8.87 KB

CONTRIBUTING.md

File metadata and controls

314 lines (196 loc) · 8.87 KB
Raw

Setting up a development environment

This is the recommended development environment used by the Pybricks maintainers.

Requirements

Optional:

  • Docker (only needed if building for ev3dev)
  • Emscripten v1.39.x (only needed if building mpy-cross JavaScript package)
  • Yarn v1.x (only needed if building JavaScript packages)

Installation tips

Pipx

We recommend using pipx to install and manage python command line tools like Poetry.

Linux (Ubuntu):

sudo apt update && sudo apt install pipx

macOS:

brew install pipx

Windows:

py -3 -m pip install pipx

Then install tools like this:

pipx install poetry

Ubuntu

Some of the prerequisites are available as Debian packages.

sudo apt update
sudo apt install git python3 build-essential gcc-arm-none-eabi

Other tools (VS Code, Poetry, Docker) can be installed via the recommended install methods found in the links above.

Windows

We use Cygwin for building code on Windows. Download and install Cygwin from the link. Select the following packages during installation:

doxygen
graphviz
make
mingw64-x86_64-gcc-core
python3
zip

Cygwin and the GNU ARM Embedded Toolchain need to be added to the PATH environment variable. We recommend doing this in the local terminal rather than globally via System Properties. For example using PowerShell:

$env:PATH="C:\cygwin64\bin;C:\Program Files (x86)\GNU Arm Embedded Toolchain\10 2020-q4-major\bin;$env:PATH"

macOS

brew instal libusb
brew install --cask gcc-arm-embedded

Get the code

Via VS Code

There is a Git: clone command available via the command pallette.

TODO:

  • Does GitHub extension need to be installed first?
  • Screenshots

Via GitHub Desktop

If you have never used Git before, GitHub Desktop is a nice tool that does just the basics.

TODO:

  • Screenshots

Via command line

Note: although pybricks-micropython contains submodules, we don't recommend using the --recursive option. There are many submodules from MicroPython that are not used by Pybricks and take a long time to clone. Submodules will be checkout out on-demand when running make.

git clone https://github.com/pybricks/pybricks-micropython
cd pybricks-micropython
code . # Opens the project in VS Code

Set up the Python environment

There are a few special Python packages needed by the build system and other tools, so we are using Poetry to manage these requirements and set up a virtual environment to isolate the installation so you don't break your main Python runtime.

Open a terminal in the pybricks-micropython directory where you cloned the source code, then run:

poetry env info

Verify that the Python version listed is 3.10.x. If it is not, run:

poetry env use <path-to-python3.10>

where <path-to-python3.10> is the full path to the Python 3.10 installation.

Then run the following to set up the Python environment:

poetry install

To activate the environment, run:

poetry shell

The command prompt will now start with (.venv) to remind you that you are working in the virtual environment. You should run poetry shell any time you open a new terminal window while working on pybricks-micropython.

Building the code

After setting up a development environment as described above, open a terminal in the pybricks-micropython directory.

If you are building firmware for a Powered Up hub, first you will need to make sure that the cross-compiler can be found. This can be done by adding it to the PATH environment variable as described in the ARM Embedded Toolchain readme.txt file:

export PATH=$PATH:$install_dir/gcc-arm-none-eabi-*/bin

Or by setting the CROSS_COMPILE environment variable:

export CROSS_COMPILE=$install_dir/gcc-arm-none-eabi-*/bin/arm-none-eabi-

$install_dir needs to be replaced with the actual directory where you actually installed the toolchain.

Then run:

make <target>

Where <target> is one of the bricks listed in the bricks/ directory, e.g. cityhub.

Hopefully all goes well and the firmware builds. The results of the build can be found in bricks/<target>/build/.

Submitting changes

We welcome pull requests to fix bugs in pybricks-micropython. However, due to the extremely limited flash memory in the Powered Up hubs, we will probably not accept new features unless they are considered "essential". Please open an issue to discuss first if you are not sure if something will be acceptable.

Changes should also follow the guidelines below:

Coding style

For the most part, we follow the MicroPython coding style. There are some 3rd party libraries that don't follow this style, so in those cases, the style should match the rest of the code in the file that is being changed.

Before committing your changes, be sure to run:

poetry run ./tools/codeformat.py

This will automatically fix common problems in files that follow the MicroPython style.

Logical commits

Complex changes should be split into smaller changes, each performing a logical step towards the end goal. Each commit on its own should be able to be compiled without error. This helps code reviewers and makes finding regressions easier.

Commit messages

Please follow the recommendations below to write a useful commit message.

  1. Add a prefix to the subject line that gives the area of code that is changed. Usually this will be the relative file path of the file being changed.

    • If the change is to the pbio library, omit the lib/ part of the path.
    • For changes to the implementation of the pybricks package, use import path instead of the file path, as in this example.

  2. The rest of the subject line describes what changed.

  3. The body describes why the change was made.

  4. Include other relevant information in the commit message if applicable. For example, if the commit fixes a compiler error, include a copy of the error message.

  5. Include a link to the relevant GitHub issue, if applicable.

  6. Include the change in firmware size, if applicable.

  7. Look at the git history for more examples.

Building JavaScript packages

This is not needed in the course of normal development, but we have several JavaScript packages that are build from this repository.

firmware

This package is for distributing the Pybricks firmware.

In the pybricks-micropython directory:

cd npm/firmware
yarn install
yarn build

mpy-cross

This package is for distributing mpy-cross as a Web Assembly binary. To build it, we need Emscripten v1.39.12 installed. Then make sure to activate the environment:

source $emsdk_path/emsdk_env.sh

...where $emsdk_path is the folder where the Emscripten SDK is installed.

Then in the pybricks-micropython directory:

# ensure that mpy-cross has been built - we need the generated files
make -C micropython/mpy-cross

cd npm/mpy-cross
yarn install
yarn build:debug

Build and deploy firmware

Build the firmware

Pick your Hub from the bricks sub-directory you want to compile.

poetry shell
make mpy-cross -j8
make -C bricks/primehub -j8

Deploy the firmware to a hub

  1. Follow the guide to prepare your Hub for Pybricks firmware installation:
    1. https://pybricks.com/install, or
    2. https://dfu.pybricks.com for Spike Prime or Mindstorms Inventor
  2. Execute the deployment: 
    make -C bricks/primehub -j8 deploy