Install a Real or Virtual Linux Machine
If you don't already have a Linux machine, you can set one up in several different ways. You can install a Linux distribution natively, either on its own machine or as a dual-boot system. You can install Linux on a virtual machine on, say, a Windows host machine. You can also use Windows Subsystem for Linux (WSL), available on Microsoft Windows 10, which allows you to run a Linux distribution with an emulation layer substituting for the Linux kernel.
We recommend using the Ubuntu distribution of Linux or one of its variants (Kubuntu, Mint, etc.). The instructions here assume you are using Ubuntu. The 20.04 LTS (Long Term Support) version is stable and reliable.
Native Linux
You can install Ubuntu on a bare machine easily. Follow the directions (this link is for 20.04) on the Ubuntu website. You can also install Ubuntu on a disk shared with your Windows installation, or on a separate disk, and make a dual-boot installation.
Linux on a Virtual Machine
Linux can also be installed easily on a virtual machine. First you install the virtual machine software, and then create a new virtual machine, usually giving the VM software a .iso file of Ubuntu or another distribution. On Windows, VM Workstation Player and VirtualBox are both free and easily installed.
Raspberry Pi
It may be possible to build on Raspberry Pi OS, but it will be easier if you install Ubuntu on your Raspberry Pi. You will also need to download the aarch64 gcc toolchain. The RPi is not a fast machine: be prepared to wait for a build to complete.
Install Build Tools on Ubuntu
The Ubuntu 20.04 LTS Desktop distribution includes most of what you need to build CircuitPython. You'll need to install some additional packages, including build-essential, if it's not already installed, and also gettext and uncrustify. In a terminal window, do:
sudo apt update # Try running `make`. If it's not installed, do: # sudo apt install build-essential # The version of uncrustify you need is in a PPA: sudo add-apt-repository ppa:pybricks/ppa sudo apt install git gettext uncrustify
Next you need to download and unpack the ARM gcc toolchain from its download page. ARM is no longer updating its Ubuntu "ppa" (private package archive), so you need to install the toolchain manually. (The links below point to the x64 versions of the toolchain. If you are building on some other architecture, download the appropriate toolchain.)
- For CircuitPython 6.1 and later, use the 10-2020-q4-major version.
If you want to build an older version of CircuitPython:
- For CircuitPython 5 and 6.0, use the 9-2019-q4-major version.
- CircuitPython 4 was built with the 7-2018q2-update version.
# Put the unpacked toolchain into an appropriate directory. # This is an example. cd ~/bin tar xvf <name of the .bz2 file you downloaded>
Next, add a line to your .bash_profile or other startup file to add the unpacked toolchain executables to your PATH. For example:
export PATH=/home/$USER/bin/gcc-arm-none-eabi-10-2020-q4-major/bin:$PATH
Open a new terminal window, and see if you now have the correct executables on your path:
which arm-none-eabi-gcc /home/halbert/bin/gcc-arm-none-eabi-10-2020-q4-major/bin/arm-none-eabi-gcc
Now move to the Build CircuitPython section of this guide. There we will get the CircuitPython source code, install a few more dependencies, and then build!
