The build.sh Script
Relevant source files
The following files were used as context for generating this wiki page:
The build.sh script serves as the primary entry point for local font generation within the AFIO project. It orchestrates a containerized build environment to compile custom Iosevka font variants and subsequently apply Nerd Font icon patches. By utilizing Docker, the script ensures a consistent and reproducible build environment across different host systems, abstracting away the complexities of Iosevka's build dependencies and the Nerd Font patcher's requirements.
The script manages the lifecycle of the build process, from environment preparation and image acquisition to the execution of multi-stage compilation and patching logic. It integrates with the project's configuration files, specifically private-build-plans.toml, to define the aesthetic and technical characteristics of the resulting font files.
Sources: build.sh:1-48, README.md:58-62
Build Process Orchestration
The build.sh script follows a structured execution flow that begins with environment setup and ends with the generation of patched font files in the _output directory.
Environment Initialization and Image Management
The script sets DOCKER_BUILDKIT=1 to leverage modern Docker build features and defines several environment variables to control the build behavior. It automatically cleans and recreates the _output directory to ensure a fresh build state. A critical component is the IMAGE_REF management: the script attempts to pull a pre-built Docker image from the GitHub Container Registry (ghcr.io/awnion/custom-iosevka-nerd-font) based on the version specified in the VERSION file. If the remote image is unavailable, it triggers a local build of the Docker container.
Sources: build.sh:5-30
Build Execution Flow
The core of the build occurs inside a temporary Docker container. This container executes two primary tasks:
- Iosevka Compilation: Uses
bun run buildto generate TTF files based on the specifiedFONT_NAMEandBUILD_PLAN. - Nerd Font Patching: Invokes
src/nerd-patcher.pyto inject 9000+ icons into the newly generated base fonts.
This diagram illustrates the high-level flow of the build script from local initialization to containerized execution.
Sources: build.sh:32-48, README.md:16-17
Configuration and Input
The script is highly configurable via environment variables and external files. The primary configuration for the font's appearance is stored in private-build-plans.toml, which is mounted into the container as a read-only volume.
Variable Summary
| Variable | Default Value | Description |
|---|---|---|
FONT_NAME | afio | The identifier for the font family being built. |
BUILD_PLAN | private-build-plans.toml | Path to the TOML file containing Iosevka customization rules. |
OUTPUT_DIR | $(pwd)/_output | The host directory where generated assets are stored. |
IMAGE | ghcr.io/awnion/custom-iosevka-nerd-font | The base repository for the Docker image. |
VERDA_CACHE | (Empty) | Optional path for persistent Iosevka build cache. |
Sources: build.sh:8-14
Cache Management
If VERDA_CACHE is provided, the script maps this host directory to the Iosevka build directory (/build/iosevka/.build). This significantly speeds up subsequent builds by persisting intermediate compilation results.
Sources: build.sh:34-40
Downstream Patching and Distribution
Once build.sh triggers the containerized environment, it hands off the process to src/nerd-patcher.py. This Python script processes the raw TTF files generated by the Iosevka build.
Patching Logic
The patcher uses a Pool of 8 workers to parallelize the execution of the font-patcher utility. It applies specific flags such as --careful and --makegroups -1 to preserve font naming while adding the necessary Nerd Font glyphs. After patching, the script packages the resulting TTF files into a compressed ZIP archive named with the current date (e.g., afio-2023-10-27.zip).
Sources: src/nerd-patcher.py:12-32, src/nerd-patcher.py:44-55
Dependency Retrieval
Before the patching can occur (typically during the Docker image build process or as a setup step), nerd/download_glyphs.sh is responsible for fetching the necessary icon source files (SFD and TTF) from the official Nerd Fonts repository.
This sequence diagram shows the interaction between the primary build script, the containerized environment, and the patching logic.
Sources: build.sh:42-48, src/nerd-patcher.py:35-42, nerd/download_glyphs.sh:10-26
Summary
The build.sh script is the central automation tool that bridges the gap between raw font source code and a distribution-ready patched font. By managing Docker images, mounting local build plans, and orchestrating parallelized patching tasks, it allows users to generate a highly customized "AFIO" font or their own fork with minimal manual configuration.
Sources: build.sh:1-48, README.md:58-62