Building

At the moment building is done from an Raspbian / Debian / Ubuntu / CustomPiOS distro. If you have another flavor of linux, or a version which is not supported, you can also install using the vagrant method or docker method, which generally solves lots of problems.

Quickstart - I want to build a new distro using docker

Copy the following docker-compose.yml to a folder where you want to set up your distro, and run the following:

version: '3.6'

services:
    custompios:
        image: guysoft/custompios:devel
        container_name: mydistro-create
        tty: true
        restart: always
        privileged: true
        volumes:
        - ./:/os_make
        devices:
        - /dev/loop-control

you should see:

sudo docker-compose up -d
Creating network "a_default" with the default driver
Creating mydistro-create ... done

Then create a distro, we will call it in the example ExampleDistro, the name you pick will be used in environment variables in the template, so pick a good one now:

# Create a folder where your ``docker-compose.yml`` is which holdes the distro
# Optional -g flag will also download you the latest version of raspbian in to the image folder, don't need if you are using another base image
sudo docker exec -it mydistro-create CustomPiOS/make_custom_pi_os -g /os_make/ExampleDistro

# Run this with your current user ID so you have permissions to edit the file
sudo docker exec -it mydistro-create chown 1000:1000 -R /os_make/ExampleDistro

Now you can remove the current docker-compose.yml and use a new one for the distro:

version: '3.6'

services:
    custompios:
        image: guysoft/custompios:devel
        container_name: mydistro-build
        tty: true
        restart: always
        privileged: true
        volumes:
        - ./ExampleDistro/src/:/distro
        devices:
        - /dev/loop-control

Then you can build the example distro:

sudo docker-compose up -d
sudo docker exec -it mydistro-build build --download

Base board selection

You can set a base board, for example:

sudo docker exec -it mydistro-build build --download --board raspberrypiarm64

And CustomPiOS will download set the correct variables and build (in this case) for RaspberryPi arm64 architecture.

Full list can be obtained by executing:

$ sudo docker exec -it octopi-build build --board list
Available board targest for --board are:
armbian_bananapim2zero - Banana Pi BPI-M2 ZERO
armbian_orangepi3lts - Orange Pi 3 LTS
armbian_orangepi4lts - Orange Pi 4 LTS
debian_lepotato - Le Potato AML-S905X-CC Debian image
orangepi_orangepi_zero2 - Orange Pi Zero2
raspberrypiarm64 - Official raspberrypi full 64bit image
raspberrypiarmhf - Official raspberrypi lite 32bit image
raspberrypiarmhf_full - Official raspberrypi full 32bit image
raspbian_lepotato - Le Potato AML-S905X-CC Raspbian image

Full commadline options

Full commadline options:

$ sudo docker exec -it octopi-build build --help
usage: build [-h] [-r] [-u RPI_IMAGER_URL] [-d] [-b BOARD] [WORKSPACE_SUFFIX]

positional arguments:
  WORKSPACE_SUFFIX      The workspace folder suffix used folder

options:
  -h, --help            show this help message and exit
  -r, --rpi_imager      Create a rpi-imager snipplet to be published
  -u RPI_IMAGER_URL, --rpi_imager_url RPI_IMAGER_URL
                        url to the uploaded image url
  -d, --download        Download the latest image for board type
  -b BOARD, --board BOARD
                        Set board type

Build a Distro From within Raspbian / Debian / Ubuntu / CustomPiOS Distros

CustomPiOS distros can be built from Debian, Ubuntu, Raspbian, or even within a distro itself (for other systems use the Vagrant build option). Build requires about 2.5 GB of free space available, depending on what you install. You can build it by issuing the following commands:

sudo apt-get install gawk util-linux coreutils qemu-user-static p7zip-full git

git clone https://github.com/guysoft/CustomPiOS.git
cd CustomPiOS/src
./make_custom_pi_os -g /path/to/new_distro
cd /path/to/new_distro/src
sudo modprobe loop
sudo bash -x ./build_dist

Building From OS X

MacOs have an outdated bash, we recommend checking your version of bash bash --version and updating our bash to version 5 or newer. Keep in mind for updating bash on MacOs turning off SIP is required.

Users have reported building on OS X to work, but we can't support it directly. See this issue about this.

Also you need to have a newer version of Bash installed. See: https://github.com/guysoft/CustomPiOS/issues/212#issuecomment-1786793677

A note about building from windows

Building from windows is possible theoretically, but there is no success report yet. The main way to do it would be to use WSL in windows 10+ using vagrant. However there seems to be an issue in vagrant regarding this. Here is a guide on installing WSL. Here is a guide on Vagrant with WSL.

Building Distro Variants and Flavors

CustomPiOS supports building variants, which are builds with changes from the main release build. An example and other variants are available in the folder src/variants/example.

To build a variant use:

sudo bash -x ./build_dist [Variant]

Where results are saved

The image created on a folder 'workspace' which is by default in the distro build files folder. It can be changed in the base module config variables.