Building#
To create a Phoenix-RTOS image for the selected target the phoenix-rtos-project
repository should be used. This
repository aggregates all operating system modules - kernel, standard library, device
drivers, filesystems, utilities, and loader. Read more about phoenix-rtos-project
submodule repositories
here.
This chapter contains instructions on how to build a reference project and how to create the final system image.
Contents#
Host operating system#
Instructions in the Building
and Running system on targets
chapters have been verified for the Ubuntu
(20.04 and 22.04 versions) Linux distribution and macOS (tested on macOS Monterey 12.6.1), so this is the easiest way
to start working with Phoenix-RTOS. Windows is also supported, by using Cygwin
or WSL
.
For more information follow:
Obtaining the sources#
The first step of the preparation of the final system image is repository cloning.
To do that and make the next instructions possible, it’s recommended to update currently installed packages and, if need be, install git:
Installing git on Ubuntu (click to expand)
sudo apt update && \
sudo apt install -y git
Installing git on macOS (click to expand)
You will need the command line tools for Xcode
and Homebrew
package, if you don’t have it you can install it by
typing:
xcode-select --install
and then:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Assure that brew is properly installed, by checking its version:
brew --version
*The described instructions have been verified for 4.0.11
brew version.
Then you will be ready for installing git and other required tools:
brew update && \
brew install git
Then, the repository should be cloned recursively (to get the submodules):
git clone --recursive https://github.com/phoenix-rtos/phoenix-rtos-project.git
Supported target platforms#
The Phoenix-RTOS reference project supports the following target platforms:
armv7a7-imx6ull-evk
armv7a9-zynq7000-qemu
armv7a9-zynq7000-zedboard
armv7a9-zynq7000-zturn
armv7m4-stm32l4x6-nucleo
armv7m7-imxrt105x-evk
armv7m7-imxrt106x-evk
armv7m7-imxrt117x-evk
host-generic-pc
ia32-generic-pc
ia32-generic-qemu
riscv64-generic-qemu
riscv64-generic-spike
riscv64-noelv-fpga
sparcv8leon3-generic-qemu
sparcv8leon3-gr712rc-board
sparcv8leon3-gr716-mimas
sparcv8leon3-gr716-mini
To get the list of valid targets the build.sh
script should be launched with an empty TARGET
variable, eg:
./phoenix-rtos-build/build.sh
Building using docker#
This is the quickest way to start development - all necessary tools are distributed in a docker image.
Firstly, you need to have the docker installed.
Installing Docker on Ubuntu (click to expand)
Install required packages
sudo apt update && \ sudo apt install -y curl \ ca-certificates \ gnupg \ lsb-release
Make docker packages available
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg && \ echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Install docker packages
sudo apt-get update && \ sudo apt-get install docker-ce docker-ce-cli containerd.io
Check if Docker is properly installed (version can be different):
sudo docker --version
To make calling docker command without
sudo
possible type:sudo groupadd docker
Even if group
docker
already exists type then:sudo usermod -aG docker $USER && \ newgrp docker
Check if running docker images without sudo works properly:
docker run hello-world
For more details and other instructions see
Installing Docker on macOS (click to expand)
You can find the up-to-date instructions on https://docs.docker.com/desktop/install/mac-install/
To make this process simpler below is an example of installation for Mac with the Intel chip:
Download the installer:
curl -o Docker.dmg "https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64"
Run the following commands to install Docker:
sudo hdiutil attach Docker.dmg && \
sudo /Volumes/Docker/Docker.app/Contents/MacOS/install && \
sudo hdiutil detach /Volumes/Docker
Then add the path to docker
binaries to the PATH
environment variable:
export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"
It’s recommended to place it in .zshrc
startup script to export it every time during startup:
echo 'export PATH=/Applications/Docker.app/Contents/Resources/bin:$PATH' >> $HOME/.zshrc
Check if Docker is properly installed by checking its version:
docker --version
Check if running docker images without sudo works properly:
docker run hello-world
If you see the following error:
ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
you can try to installcolima
and check once again:brew install colima && \ colima start
Then, to build - provide a TARGET
via ENV variable and run the build script:
cd phoenix-rtos-project/
TARGET=ia32-generic-qemu ./docker-build.sh all
After the build completes, kernel and disk images will be created and placed in the _boot
directory.
You can read more about the building script options here.
Building using the native toolchain#
This is the method preferred when you plan to develop Phoenix-RTOS.
Firstly, you need to install some tools required for compiling the toolchain and finally create a Phoenix-RTOS system image. There is a list of commands you can use to get them: on both Ubuntu and macOS host operating systems.
Installing required tools for native build on Ubuntu (click to expand)
sudo apt update && \
sudo apt install -y build-essential \
mtd-utils \
autoconf \
pkg-config \
texinfo \
genext2fs \
libtool \
libhidapi-dev \
python3 \
python3-jinja2 \
python3-yaml
Installing required tools for native build on macOS (click to expand)
brew update && \
brew upgrade && \
brew install bash \
coreutils \
autoconf \
automake \
genext2fs \
make \
libelf \
wget \
gnu-sed \
hidapi \
python3 \
python3-jinja2 \
python3-yaml
*bash
in version >= 4.0
and make
in version >= 3.82
are needed (associative arrays and undefine
used).
They may be preinstalled, but in older versions, that’s why we install it there.
It’s also required to add appropriate paths to the PATH
environment variable:
export PATH=$(brew --prefix make)/libexec/gnubin:$(brew --prefix gnu-sed)/libexec/gnubin:$PATH
and keep it updated, for example by placing the export in the startup script:
echo 'export PATH=$(brew --prefix make)/libexec/gnubin:$(brew --prefix gnu-sed)/libexec/gnubin:$PATH' >> $HOME/.zshrc
*Note that you have to place the gnubin
path that provides make
before the /usr/bin
in the PATH
environment
variable to use the gnu
version (as it is done above).
Phoenix-RTOS requires the endian.h
header, which may exist, but not be visible. If during the building you discover
the following error:
fatal error: 'endian.h' file not found
please create the symlink to this header by the given command:
sudo ln -s /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/machine/endian.h /usr/local/include/endian.h
Next, you need to compile the toolchains for all required target architectures:
cd phoenix-rtos-project
(cd phoenix-rtos-build/toolchain/ && ./build-toolchain.sh i386-pc-phoenix ~/toolchains/i386-pc-phoenix)
(cd phoenix-rtos-build/toolchain/ && ./build-toolchain.sh arm-phoenix ~/toolchains/arm-phoenix)
(cd phoenix-rtos-build/toolchain/ && ./build-toolchain.sh riscv64-phoenix ~/toolchains/riscv64-phoenix)
(cd phoenix-rtos-build/toolchain/ && ./build-toolchain.sh sparc-phoenix ~/toolchains/sparc-phoenix)
Errors and warnings that may occur during the toolchain compilation
If you have encountered some issue during the toolchain build - you probably interrupted a build before or the files in
the toolchains
directory are broken for some reason. Removing a directory for a specific architecture
(arm-phoenix/i386-pc-phoenix/riscv64-phoenix/sparc-phoenix) and launching a build once again should help.
NOTE:
Even during the correct compilation process there may be some unresolved warnings.
Toolchain binaries should be added to the PATH variable:
export PATH=$PATH:$HOME/toolchains/i386-pc-phoenix/i386-pc-phoenix/bin/:$HOME/toolchains/arm-phoenix/arm-phoenix/bin/:$HOME/toolchains/riscv64-phoenix/riscv64-phoenix/bin/:$HOME/toolchains/sparc-phoenix/sparc-phoenix/bin/
You should keep the PATH
variable updated. There are various methods to do that, for example you can place the export
in .bashrc
file on Ubuntu
:
echo "export PATH=$PATH:$HOME/toolchains/i386-pc-phoenix/i386-pc-phoenix/bin/:$HOME/toolchains/arm-phoenix/arm-phoenix/bin/:$HOME/toolchains/riscv64-phoenix/riscv64-phoenix/bin/:$HOME/toolchains/sparc-phoenix/sparc-phoenix/bin/" >> $HOME/.bashrc
or in .zshrc
on macOS:
echo 'export PATH=$PATH:$HOME/toolchains/i386-pc-phoenix/i386-pc-phoenix/bin/:$HOME/toolchains/arm-phoenix/arm-phoenix/bin/:$HOME/toolchains/riscv64-phoenix/riscv64-phoenix/bin/:$HOME/toolchains/sparc-phoenix/sparc-phoenix/bin/' >> $HOME/.zshrc
Read more about the Phoenix-RTOS toolchain here.
To build a project - provide a TARGET
via ENV variable:
TARGET=ia32-generic-qemu ./phoenix-rtos-build/build.sh all
After the build completes, kernel and disk images will be created and placed in the _boot
directory.
You can read more about the building script options here.
Launching Phoenix-RTOS#
To start the created image on target architecture please see phoenix-rtos-doc/quickstart guide.