|
|
# PyraOS Build System
|
|
|
|
|
|
The PyraOS build system utilizes `docker.io` to manage a clean and isolated build environment for building PyraOS images and packages.
|
|
|
|
|
|
## Setting up your host
|
|
|
|
|
|
### Installing dependencies
|
|
|
|
|
|
All you need is a Linux host, preferably x86_64 with 4+ cores and 8GB+ of RAM, with `docker.io` running. On Debian based systems, install `docker.io` via `apt`. On other systems, Google is your friend :)
|
|
|
All you need is a Linux host, preferably x86_64 with 4+ cores and 8GB+ of RAM, with `docker.io` and `repo` packages. On Debian based systems, install `docker.io` via `apt`. On other systems, Google is your friend :)
|
|
|
|
|
|
```
|
|
|
sudo apt install docker.io
|
|
|
sudo apt install docker.io repo
|
|
|
```
|
|
|
|
|
|
Note, you will probably need to add your user to the `docker` group.
|
... | ... | @@ -18,72 +15,75 @@ Note, you will probably need to add your user to the `docker` group. |
|
|
sudo usermod -a -G docker $USER
|
|
|
```
|
|
|
|
|
|
Also ensure that you have an ssh key created named `id_rsa` in `~/.ssh`.
|
|
|
At this point, you will need to reboot to ensure that your user is properly associated with the `docker` group.
|
|
|
|
|
|
### Setting up your build environment
|
|
|
|
|
|
Start off by cloning the `pyra-docker` repository to a sensible build location.
|
|
|
|
|
|
```
|
|
|
git clone git@dev.pyra-handheld.com:imagebuild/pyra-docker.git /path/to/build/location
|
|
|
cd /path/to/build/location
|
|
|
```
|
|
|
Also ensure that you have an ssh key created named `id_rsa` in `~/.ssh` and it is registered with your `dev.pyra-handheld.com` account. This will be necessary for cloning the PyraOS sources. At this point, you will need to reboot to ensure that your user is properly associated with the `docker` group.
|
|
|
|
|
|
Next, you'll need to create the directory on your host system where we'll be doing all the work. This directory will be linked into the docker environment when we start up the container.
|
|
|
### Cloning Sources
|
|
|
First, you'll need to create the directory on your host system where we'll be downloading the source repositories and running our builds.
|
|
|
|
|
|
```
|
|
|
mkdir -p /path/to/docker/directory/../build
|
|
|
mkdir -p /path/to/build/directory
|
|
|
```
|
|
|
|
|
|
Now we're ready to build the docker image. This will create and configure a base image of our build environment. If you're curious to see what's going on here or want to modify it, check out `Dockerfile`. Note that as long as you don't modify `Dockerfile` or `docker-entrypoint.sh` (pulling new commits from the remote counts as modifying), you only have to do this once.
|
|
|
Next, we'll clone the source repositories using `repo`. Note that the `repo sync` command supports defining job number, much like `make`. Pick a number that is sensible given the number of cores your build machine has.
|
|
|
|
|
|
```
|
|
|
./build_docker.sh
|
|
|
cd /path/to/build/directory
|
|
|
repo init -u dev.pyra-handheld.com:imagebuild/pyra-manifest.git
|
|
|
repo sync -d -j4
|
|
|
```
|
|
|
|
|
|
## Working with the build system
|
|
|
|
|
|
### Building a PyraOS image
|
|
|
Now you have all the source code and some tools, but the build environment needs to be properly set up. Luckily, `docker` handles that for us.
|
|
|
|
|
|
Once you have the docker image built, you're ready to start using it to build a PyraOS image. Building an image consists of three steps: building U-Boot, building the rootfs from the Pyra repository (this uses the most recent stable kernel in the repo), and creating the virtual disk image.
|
|
|
|
|
|
First, sync your source repositories with the remote. This will take a fair amount of time. Note: before doing this, ensure that your git configuration is already set up. The sync will fail if it is not.
|
|
|
### Setting up your build environment
|
|
|
Start off by cloning the `pyra-docker` repository to a sensible build location.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh sync-manifest
|
|
|
git clone git@dev.pyra-handheld.com:imagebuild/pyra-docker.git /path/to/dockerfile/location
|
|
|
cd /path/to/dockerfile/location
|
|
|
```
|
|
|
|
|
|
Next, build the bootloader. You must specify whether you are building for 2gb or 4gb hardware.
|
|
|
Now we're ready to build the docker image. This will create and configure a base image of our build environment. If you're curious to see what's going on here or want to modify it, check out `Dockerfile`. Note that as long as you don't modify `Dockerfile` or `docker-entrypoint.sh` (pulling new commits from the remote counts as modifying), you only have to do this once.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh build uboot [2gb|4gb]
|
|
|
./build_docker.sh
|
|
|
```
|
|
|
|
|
|
Next, build the rootfs.
|
|
|
## Building a PyraOS image
|
|
|
### Starting the Docker Container
|
|
|
Once you have the docker image built, you're ready to start using it to build a PyraOS image. Building a PyraOS image consists of two steps: building the bootloader, and building the rootfs from the Pyra repository (this uses the most recent stable kernel in the repo).
|
|
|
|
|
|
Before we can do any of this, we need to start a container using the `docker` image we just built. There is a simple wrapper script to handle this for you, but you need to tell it where you cloned the sources on the host filesystem.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh build rootfs
|
|
|
BUILD_DIR=/path/to/build/directory ./docker_run.sh
|
|
|
```
|
|
|
|
|
|
Finally, create the virtual disk image. Warning: This step makes use of your host machine's loopback devices.
|
|
|
### Building the Bootloader
|
|
|
Unfortunately, the Pyra bootloader is not able to detect whether it is booting on 2GB or 4GB hardware, so they must be built separately. Simply define the `PYRA_DDR` shell variable as either `2gb` or `4gb`. The Makefile will default to `4gb` if none is supplied.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh build image
|
|
|
PYRA_DDR=2gb make bootloader
|
|
|
```
|
|
|
|
|
|
All binaries will be located within `build/out`. Note that the following command can be used to build everything at once, however it will build the kernel as well. The kernel built during this step is NOT the one used in the final image.
|
|
|
### Building the RootFS
|
|
|
The Debian root filesystem is built using `multistrap` and packaged into a `.tgz`. At this time, full emulation for package configuration is not supported, so the packages are not configured during the post-hook phase unless running on native armhf architecture. Therefore, the rootfs created here will not properly boot if built on non-native architecture.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh build-all
|
|
|
make rootfs
|
|
|
```
|
|
|
|
|
|
You can also simply enter a bash shell within the docker container and run any commands manually by starting it with the following command.
|
|
|
### Building a Custom Kernel
|
|
|
When building PyraOS, the kernel used is pulled from the package repository rather than from the build system. However, the build system supports building the PyraOS kernel as both a zImage and a `.deb` package.
|
|
|
|
|
|
```
|
|
|
./docker_run.sh bash
|
|
|
# build Debian package
|
|
|
make linux
|
|
|
# build zImage
|
|
|
make zImage
|
|
|
```
|
|
|
|
|
|
To install your custom debian package build, simply follow standard procedure on Debian. You may then need to update the extlinux configuration if you want to automatically boot this kernel. If you want to install your custom zImage kernel (and/or device tree), this will need to be done with special modificaitions to the boot process at [flash time](Flashing-and-Booting-the-Pyra).
|
|
|
|
|
|
### Building PyraOS Debian packages
|
|
|
|
|
|
Coming soon!
|
... | ... | |