Skip to content

AI.md

Latest commit

 

History

History
67 lines (50 loc) · 3.92 KB

AI.md

File metadata and controls

67 lines (50 loc) · 3.92 KB

AI Assistant Developer Guide: CrocNetDistro

This guide is designed for future AI coding assistants and LLMs working on the CrocNetDistro repository. It outlines the project's architecture, workflows, and key conventions.

🚀 Repository Purpose

CrocNetDistro is a lightweight builder system that generates customized root filesystems (rootfs) for various Linux distributions (Debian/Ubuntu) targeting ARM64 and RISC-V architectures.

It uses Docker, QEMU user-static translation, and debootstrap to build target filesystem images in a containerized environment, which are then packaged as .tar.gz archives.

📂 Repository Structure

The project has a modular design where each subdirectory represents a supported distribution.

CrocNetDistro/
├── Dockerfile          # Multi-stage Dockerfile matching host build tools & cross-compilation packages
├── run.sh              # Interactive CLI entrypoint (scans and builds)
├── makeTar.sh          # Packaging script for build outputs
├── debian-sid/         # Configuration for Debian Unstable (Sid)
├── debian-trixie/      # Configuration for Debian 13 (Trixie)
└── ubuntu-resolute/    # Configuration for Ubuntu 26.04 LTS (Resolute Raccoon)

📦 Distribution Directory Layout

Every distribution directory must contain the following files:

  • ENV: Environment variables definition (e.g. DISTRO, DISTRO_URL, default DISTRO_HOSTNAME, ROOTPW).
  • bootstrap.sh: The post-install customization script that runs inside the chroot jail of the target filesystem (sets hostname, repository sources, installs baseline packages, setups SSH and root passwords).
  • build.sh: The script that orchestrates debootstrap stage 1 & 2, mounts /proc, initiates bootstrap.sh, and copies static configurations.
  • kernel.conf: Tailored Linux kernel options required/desired for the distribution.
  • etc/: Custom files copied directly into the target filesystem's /etc directory.
    • etc/fstab: Filesystem mounts.
    • etc/resolv.conf: Nameservers configuration.
    • etc/network/interfaces: Network interface defaults.

🛠️ How the Build Process Works (run.sh)

  1. Dynamic Discovery: run.sh scans the workspace using find to detect directories containing an ENV file: 
    find . -maxdepth 2 -type f -name "ENV" -exec dirname {} \;
  2. User Input: It presents a text-based menu using whiptail to select the target distribution directory and the CPU architecture (ARM64 or RISC-V).
  3. Docker Build: It triggers a multi-stage Docker build targeting distro-arm64 or distro-riscv64, passing the target distribution directory and target rootfs name as build arguments.
  4. Chroot Build Execution: The container runs with --privileged and -v ./rootfs:/rootfs to execute build.sh which populates the host's ./rootfs directory.
  5. Packaging: Finally, run.sh invokes makeTar.sh which generates a distro-arch-date.tar.gz archive in the project root.

✍️ Guidelines for Adding a New Distro

If requested to add a new distribution (e.g., ubuntu-generic):

  1. Create Directory: Create a folder named ubuntu-generic/.
  2. Add Configuration Files: Implement the structure defined in Distribution Directory Layout.
  3. Update ENV: Set the correct distribution codename (e.g. export DISTRO=generic) and source repositories URL.
  4. Set Script Permissions: Ensure bootstrap.sh and build.sh are executable (chmod +x).
  5. No Script Updates Needed: You do not need to modify run.sh or Dockerfile for new distributions, as they dynamically search for ENV files.

📝 Common Commands

  • Run Build Command: ./run.sh
  • Clean Artifacts: git clean -fdx (be careful, as this removes all built .tar.gz packages since they are gitignored).