Skip to Content
DocumentationSoftwareBuild Image

Build Image

This page documents how to build the Lichee-Jack system image from source, including environment setup, kernel configuration, and image flashing.

The build system is based on Docker and reuses the sophgo-sg200x-debian build framework, with Lichee-Jack–specific customizations layered on top.

1. Source Layout & Prerequisites

Lichee-Jack’s Debian build scripts are based on:

The fork is included in the Lichee-Jack main repository as a git submodule.

Clone the main repository with submodules:

git clone --recurse-submodules https://github.com/KaliAssistant/Lichee-Jack.git

2. Install Docker

The build process runs entirely inside Docker.

On Debian / Ubuntu:

sudo apt update
sudo apt install docker.io

Ensure your user can run Docker (optional but recommended):

sudo usermod -aG docker $USER
newgrp docker

3. Build Configuration Overview

Most customizations live under:

sophgo-sg200x-debian/configs/

3.1 Device Tree

Main device-tree file for Lichee-Jack:

sophgo-sg200x-debian/configs/licheervnano/dts/cv181x_licheervnano_sd.dts

Use this file to configure:

  • GPIO pinmux
  • Onboard peripherals (Wi-Fi, LEDs, LCD, etc.)
  • Memory layout references

3.2 Global Build Settings

File:

sophgo-sg200x-debian/configs/settings.mk

Key variables:

  • KERNELREV Kernel version suffix, e.g. linux-5.10.4-<tag>

  • FSBLVERSION FSBL (First Stage Boot Loader) version string

  • PACKAGES Base Debian packages included in the image

  • IMAGE_ADDITIONS Add-on Makefiles (handled by addons/)

3.3 Board-Specific Settings

File:

sophgo-sg200x-debian/configs/licheervnano/settings.mk

Example (simplified):

CHIP=cv181x
UBOOT_CHIP=cv181x
UBOOT_BOARD=licheervnano_sd
BOOT_CPU=riscv
ARCH=riscv
DDR_CFG=ddr3_1866_x16
PARTITION_FILE=partition_sd.xml
STORAGE_TYPE=sd
 
PACKAGES += "wireless-regdb wpasupplicant cvi-pinmux-cv181x \
             git wget curl libusbgx-dev cmake make gcc g++ \
             python3 python3-dev python3-pip python3-venv \
             python3-aioquic python3-netifaces python3-toml \
             nmap arp-scan macchanger tcpdump htop btop \
             fastfetch locales pipx netdiscover hping3"
 
IMAGE_ADDITIONS += "aic8800-firmware"
IMAGE_ADDITIONS += "nm-addons"
IMAGE_ADDITIONS += "jack-coreutils"
IMAGE_ADDITIONS += "systemd-disable"

This file defines:

  • Target SoC and architecture
  • Storage type (SD)
  • Debian package set
  • Lichee-Jack–specific add-ons

3.4 Partition Layout

File:

sophgo-sg200x-debian/configs/licheervnano/partition_sd.xml

Example:

<physical_partition type="sd">
    <partition label="BOOT"   size_in_kb="262144" readonly="false" file="boot.sd"/>
    <partition label="ROOTFS" size_in_kb="262144" readonly="false" file="rootfs.sd" />
</physical_partition>

Controls:

  • Image size
  • Partition sizes
  • Output artifacts

3.5 Memory Map

File:

sophgo-sg200x-debian/configs/licheervnano/memmap.py

This script defines the SoC memory layout, including:

  • DRAM base and size
  • FreeRTOS reserved memory
  • OpenSBI / ATF regions
  • Kernel usable memory
  • Framebuffer and boot logo area
  • FSBL / U-Boot load addresses
Warning

Modifying this file directly affects boot stability. Only change if you understand the CV181x boot flow.

3.6 Linux Kernel Configuration

File:

sophgo-sg200x-debian/configs/licheervnano/linux/defconfig

This defconfig is copied into the kernel tree during build.

Use it to enable:

  • Filesystems
  • Networking features
  • USB gadget support
  • Drivers specific to Lichee-Jack hardware

3.7 U-Boot Customization

Directory:

sophgo-sg200x-debian/configs/licheervnano/u-boot/

Includes:

  • cvi_board_init.c – early board init (GPIO, LED, Wi-Fi reset, pinmux)
  • cvitek.h – GPIO definitions
  • U-Boot defconfig

This is where early hardware bring-up happens:

  • Status LED control
  • Wi-Fi power reset
  • SDIO pinmux
  • Optional LCD / camera setup

3.8 Add-ons System

Directory:

sophgo-sg200x-debian/scripts/addons/

Each add-on provides an addon.mk Makefile.

Example:

addons/jack-coreutils/addon.mk

Used for:

  • Installing custom .deb packages
  • Injecting firmware blobs
  • Adding Lichee-Jack utilities

3.9 Root Filesystem Setup

Script:

sophgo-sg200x-debian/scripts/setup_rootfs.sh

Runs after base Debian is generated.

Handles:

  • Default passwords
  • APT sources
  • Locale setup
  • Service enable/disable

4. Build Docker Image

This step only builds the Docker build environment.

cd sophgo-sg200x-debian
./build_docker.sh

What this script does:

  • Builds the Docker image used for compilation
  • Installs cross toolchains and build dependencies
  • Prepares a clean, reproducible build environment

What this script does NOT do:

  • Does not clone the Linux kernel
  • Does not build U-Boot
  • Does not generate images
Note

You need to re-run this script if build-related configs, Dockerfiles, or dependency definitions are modified.

5. Build the System Image

This step performs the actual build.

Run:

./build_image.sh

What this script does:

  • Clones required source code (Linux kernel, U-Boot, etc.)

  • Applies board-specific defconfigs and patches

  • Builds:

    • FSBL
    • OpenSBI
    • U-Boot
    • Linux kernel
    • Debian root filesystem

  • Packages everything into a bootable SD-card image

Expected build time:

  • 30–60 minutes, depending on network speed and CPU performance

6. Flash the Image

After a successful build, the output image is located at:

sophgo-sg200x-debian/image/licheervnano_sd.img

Flash to SD card using dd:

sudo dd if=licheervnano_sd.img of=/dev/sdX bs=4M status=progress conv=fsync

Or follow the full flashing guide:

Flash Image

Summary

This build system allows you to:

  • Fully customize kernel, U-Boot, and rootfs
  • Add your own Debian packages and services
  • Control early boot hardware behavior
  • Reproduce images in a clean, Docker-based environment

It is the recommended workflow for developing and distributing Lichee-Jack system images.

Last updated on
SystemUtilities