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

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 realpath 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.