Skip to content

Building Calculinux

This guide covers building the Calculinux distribution from source.

Prerequisites

System Requirements

  • Host OS: Linux (Ubuntu 22.04 LTS or similar recommended)
  • Disk Space: Minimum 50GB free space (100GB+ recommended)
  • Memory: 8GB RAM minimum (16GB+ recommended for parallel builds)
  • CPU: Multi-core processor (builds can take 2-6 hours depending on hardware)

Required Software

Install the required packages on your build host:

# Ubuntu/Debian
sudo apt install gawk wget git diffstat unzip texinfo \
    gcc build-essential chrpath socat cpio python3 \
    python3-pip python3-pexpect xz-utils debianutils \
    iputils-ping python3-git python3-jinja2 libegl1-mesa \
    libsdl1.2-dev pylint3 xterm python3-subunit mesa-common-dev \
    zstd liblz4-tool

Build System Overview

Calculinux uses the Yocto Project build system with:

  • Build Tool: KAS for simplified configuration
  • Base: Yocto Scarthgap (4.2)
  • Distribution: Calculinux (based on Poky)
  • Layers: Multiple meta-layers for hardware support and software packages

Quick Start

1. Clone the Repository

mkdir calculinux-build && cd calculinux-build
git clone https://github.com/Calculinux/meta-calculinux.git
cd meta-calculinux

2. Build with KAS

The simplest way to build is using the KAS container:

./kas-container --ssh-dir ~/.ssh build --update kas-luckfox-lyra-bundle.yaml

This command will:

  1. Download all required Yocto layers
  2. Configure the build for Luckfox Lyra
  3. Build the complete distribution image
  4. Generate IPK packages

3. Locate Build Output

After the build completes (2-6 hours), find your images in:

build/tmp/deploy/images/luckfox-lyra/

Key outputs:

  • calculinux-image-luckfox-lyra.rootfs.wic.gz - Full disk image for initial installation
  • calculinux-bundle-luckfox-lyra.raucb - RAUC update bundle for updating existing installations

Build Types and Package Feed Configuration

Calculinux images are automatically configured with the appropriate package feed based on how they are built. Feeds are pre-configured in the image and typically do not require manual intervention. This section is primarily informational to help you understand the feed structure.

Understanding Feed Configuration

Package feeds are organized by:

  1. DISTRO_CODENAME - The Yocto/Poky codename (e.g., walnascar for Scarthgap 4.2)
  2. FEED_SUBFOLDER - Either continuous (development) or release (stable tags)

The feed URL structure is: 

https://opkg.calculinux.org/ipk/{DISTRO_CODENAME}/{FEED_SUBFOLDER}/

CI Build Configuration (Automated)

When building via GitHub Actions CI, the build system automatically generates build/conf/auto.conf to configure the package feeds:

Build Trigger DISTRO_CODENAME FEED_SUBFOLDER Resulting Feed URL
main branch push walnascar continuous https://opkg.calculinux.org/ipk/walnascar/continuous/
develop branch push develop continuous https://opkg.calculinux.org/ipk/develop/continuous/
Tagged release (e.g., v1.0.0) walnascar release https://opkg.calculinux.org/ipk/walnascar/release/
Pre-release tag (e.g., v1.0.0-rc1) walnascar release https://opkg.calculinux.org/ipk/walnascar/release/

Example auto.conf generated by CI: 

# For main branch:
DISTRO_CODENAME = "walnascar"
CALCULINUX_FEED_SUBFOLDER = "continuous"

# For develop branch:
DISTRO_CODENAME = "develop"
CALCULINUX_FEED_SUBFOLDER = "continuous"

# For tagged release (v1.0.0):
DISTRO_CODENAME = "walnascar"
CALCULINUX_FEED_SUBFOLDER = "release"

Manual Build Configuration

When you build manually (without CI), auto.conf is not created, so the configuration comes from the distribution defaults in meta-calculinux-distro/conf/distro/calculinux-distro.conf:

# Default values from calculinux-distro.conf:
DISTRO_CODENAME = "walnascar"           # Inherited from poky.conf
CALCULINUX_FEED_SUBFOLDER ??= "continuous"  # Defaults to continuous

Manual Build Behavior:

What You Do DISTRO_CODENAME FEED_SUBFOLDER Feed URL
kas-container build kas-luckfox-lyra-bundle.yaml walnascar (from Poky) continuous (default) ipk/walnascar/continuous/
Add CALCULINUX_FEED_SUBFOLDER = "release" to build/conf/local.conf walnascar (from Poky) release (override) ipk/walnascar/release/
Add DISTRO_CODENAME = "develop" to build/conf/local.conf develop (override) continuous (default) ipk/develop/continuous/

Feed Configuration Variables

These variables control which package feed your image will use:

  • DISTRO_CODENAME: Distribution codename
  • Inherited from poky.conf (currently walnascar for Scarthgap 4.2)
  • CI overrides this to develop for develop branch builds

  • Can be manually overridden in build/conf/local.conf or build/conf/auto.conf

  • CALCULINUX_FEED_SUBFOLDER: Feed subdirectory

  • Defaults to continuous if not specified
  • CI sets to release for tagged builds
  • Can be manually overridden in build/conf/local.conf

When to Change Feed Configuration

You typically don't need to change feed configuration unless:

  1. Testing a different feed: You want to test your local build with a different package repository
  2. Custom deployment: You're creating a custom image variant with specific package sources
  3. Development workflow: You're developing packages and want to use a test feed

To change the feed configuration for manual builds, create or edit build/conf/local.conf:

# Example: Use the release feed instead of continuous
CALCULINUX_FEED_SUBFOLDER = "release"

# Example: Use the develop feed
DISTRO_CODENAME = "develop"
CALCULINUX_FEED_SUBFOLDER = "continuous"

Verifying Feed Configuration

To check which feed your image will use:

# Inside kas-container shell:
./kas-container shell kas-luckfox-lyra-bundle.yaml

# Query the feed configuration:
bitbake -e calculinux-image | grep -E "^(DISTRO_CODENAME|CALCULINUX_FEED_SUBFOLDER|PACKAGE_FEED_BASE_PATHS)="

Example output: 

DISTRO_CODENAME="walnascar"
CALCULINUX_FEED_SUBFOLDER="continuous"
PACKAGE_FEED_BASE_PATHS="ipk/walnascar/continuous"

How Feed Configuration Works

The feed configuration is baked into the image during build:

  1. Build Time: Yocto reads DISTRO_CODENAME and CALCULINUX_FEED_SUBFOLDER variables
  2. Image Creation: Feed URL is written to /etc/opkg/opkg.conf in the image
  3. Runtime: opkg uses the configured feed URL to install/update packages

Users can still manually change feeds after installation by editing /etc/opkg/opkg.conf, but this is only needed for advanced use cases (see Package Management for details).

Configuring Your Build

Setting Distribution Codename

To manually set the distribution codename, edit conf/local.conf:

# For stable builds
DISTRO_CODENAME = "walnascar"

# For development builds
DISTRO_CODENAME = "develop"

Setting Feed Subfolder

To configure the package feed subfolder, edit conf/local.conf:

# For continuous/rolling releases
CALCULINUX_FEED_SUBFOLDER = "continuous"

# For stable releases
CALCULINUX_FEED_SUBFOLDER = "release"

Complete Build Configuration Example

For a development build:

# conf/local.conf
DISTRO_CODENAME = "develop"
CALCULINUX_FEED_SUBFOLDER = "continuous"

For a release build:

# conf/local.conf
DISTRO_CODENAME = "walnascar"
CALCULINUX_FEED_SUBFOLDER = "release"

Build Targets

Calculinux provides several build targets:

Main Image

bitbake calculinux-image

The primary Calculinux image with desktop environment and applications.

Minimal Image

bitbake calculinux-image-minimal

A minimal base system without desktop environment.

SDK

bitbake calculinux-image -c populate_sdk

Generates a cross-compilation SDK for application development.

Build Options

Clean Build

To perform a clean build:

# Clean everything
bitbake -c cleanall calculinux-image

# Clean specific package
bitbake -c cleanall <package-name>

Parallel Builds

Configure parallel builds in conf/local.conf:

# Number of parallel BitBake tasks
BB_NUMBER_THREADS ?= "8"

# Number of parallel make tasks
PARALLEL_MAKE ?= "-j 8"

Adjust numbers based on your CPU cores and available RAM.

Disk Space Management

Monitor disk usage:

# Check build directory size
du -sh build/tmp

# Clean shared state cache
rm -rf build/sstate-cache/*

# Clean downloads (only if needed)
rm -rf build/downloads/*

Build Output

After a successful build, find images in:

build/tmp/deploy/images/luckfox-lyra/

Key files:

  • calculinux-image-*.wic.gz - Flashable SD card image
  • calculinux-image-*.tar.gz - Root filesystem archive
  • calculinux-image-*.manifest - List of installed packages

Flashing the Image

To SD Card (Linux)

# Decompress the image
gunzip calculinux-image-*.wic.gz

# Flash to SD card (replace /dev/sdX with your card)
sudo dd if=calculinux-image-*.wic of=/dev/sdX bs=4M status=progress
sudo sync

To SD Card (Cross-platform)

Use Etcher or Raspberry Pi Imager with the .wic.gz file.

CI/CD Integration

Calculinux uses GitHub Actions for automated builds. The CI system automatically:

  1. Detects the branch or tag being built
  2. Sets appropriate DISTRO_CODENAME and CALCULINUX_FEED_SUBFOLDER
  3. Builds the image
  4. Publishes packages to the correct feed location
  5. Uploads build artifacts

CI Configuration Files

The build behavior is controlled by:

  • .github/workflows/build.yml - Main CI workflow
  • conf/auto.conf - Auto-generated build configuration
  • conf/calculinux.conf - Distribution configuration

Package Feed Publishing

After building, packages can be published to the opkg feed:

# Upload to continuous feed (development)
rsync -avz tmp/deploy/ipk/ \
  user@opkg.calculinux.org:/var/www/opkg/ipk/walnascar/continuous/

# Upload to release feed (stable)
rsync -avz tmp/deploy/ipk/ \
  user@opkg.calculinux.org:/var/www/opkg/ipk/walnascar/release/

The CI system handles this automatically for official builds.

Troubleshooting

Build Failures

If a build fails:

  1. Check the error message in the build log
  2. Clean the failing package: bitbake -c cleanall <package>
  3. Retry the build
  4. Check Common Issues

Disk Space Issues

If you run out of disk space:

# Remove old build artifacts
bitbake -c clean calculinux-image

# Clear shared state cache
rm -rf build/sstate-cache/*

Network Issues

If downloads fail:

# Use mirrors
# Add to conf/local.conf:
PREMIRRORS_prepend = "\
  git://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
  ftp://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
  http://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n \
  https://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \n"

Next Steps

See Also