EasyLFS

1. Introduzione e Scopo

EasyLFS è un’implementazione moderna e containerizzata del processo di build di Linux From Scratch. Trasforma il tradizionale build manuale di LFS in una pipeline Docker Compose modulare, ripetibile e pensata sia per scopi educativi che per build riproducibili.

Caratteristiche Principali:

2. Contesto e Motivazioni

Questo progetto nasce come strumento didattico per Linux User Groups (LUG) per dimostrare:

3. Diagrammi UML — Dettagli Implementativi

Questa sezione fornisce una visione approfondita dell’architettura Docker e dei flussi di esecuzione attraverso diagrammi UML dettagliati.

3.1 Component Diagram — Architecture

Architettura a microservizi Docker: 6 servizi di build sequenziali (download → toolchain → basesystem → configure → kernel → package), 2 servizi web opzionali, 5 volumi persistenti per sorgenti/tools/rootfs/dist/logs.

graph TD subgraph Host["🖥️ Host Environment"] User((Utente)) CLI[easylfs / build.sh] end subgraph Docker["🐳 Docker Infrastructure"] direction TB subgraph Build["Build Services - Sequenziali"] S1[download-sources] S2[build-toolchain] S3[build-basesystem] S4[configure-system] S5[build-kernel] S6[package-image] end subgraph Web["Web Services - Opzionali"] W1[lfs-web-terminal] W2[lfs-web-screen] end subgraph Volumes["📦 Persistent Volumes"] V1[lfs-sources] V2[lfs-tools] V3[lfs-rootfs] V4[lfs-dist] V5[lfs-logs] end end User --> CLI CLI --> S1 S1 -->|Scarica| V1 V1 -.->|Input| S2 S2 -->|Crea| V2 S2 -->|Inizializza| V3 V1 -.->|Input| S3 V2 -.->|Strumenti| S3 S3 -->|Chroot Build| V3 S4 -->|Configura| V3 V1 -.->|Kernel src| S5 S5 -->|Installa| V3 V3 -.->|Input| S6 S6 -->|Genera .img| V4 S1 & S2 & S3 & S4 & S5 & S6 -.->|Logs| V5 V4 -.->|Immagine| W1 & W2

3.2 Sequence Diagram — Build Pipeline Flow

Orchestrazione temporale della pipeline completa: wrapper script → Docker Compose → esecuzione sequenziale dei 6 container con calcolo tempi e gestione exit code.

sequenceDiagram autonumber actor User participant Host as ./easylfs participant DC as Docker Compose participant S1 as download-sources participant S2 as build-toolchain participant S3 as build-basesystem participant S4 as configure-system participant S5 as build-kernel participant S6 as package-image User->>Host: build Host->>Host: auto_setup() Host->>Host: build.sh rect rgb(230, 255, 230) Note over DC,S1: Stage 1 - Download Host->>DC: run download-sources DC->>S1: Start Container S1->>S1: Check/Download Packages S1-->>DC: Exit 0 DC-->>Host: Completed end rect rgb(220, 250, 220) Note over DC,S2: Stage 2 - Toolchain Host->>DC: run build-toolchain DC->>S2: Start Container S2->>S2: Build Binutils/GCC Pass 1&2 S2-->>DC: Exit 0 DC-->>Host: Completed end rect rgb(210, 245, 210) Note over DC,S3: Stage 3 - Base System Host->>DC: run build-basesystem DC->>S3: Start Container S3->>S3: Mount Virtual FS S3->>S3: Chroot & Build Final System S3-->>DC: Exit 0 DC-->>Host: Completed end rect rgb(200, 240, 200) Note over DC,S4: Stage 4 - Configure Host->>DC: run configure-system DC->>S4: Start Container S4->>S4: Create fstab, net, bootscripts S4-->>DC: Exit 0 DC-->>Host: Completed end rect rgb(190, 235, 190) Note over DC,S5: Stage 5 - Kernel Host->>DC: run build-kernel DC->>S5: Start Container S5->>S5: Compile Linux Kernel S5-->>DC: Exit 0 DC-->>Host: Completed end rect rgb(180, 230, 180) Note over DC,S6: Stage 6 - Package Host->>DC: run package-image DC->>S6: Start Container S6->>S6: Create .img & Install GRUB S6-->>DC: Exit 0 DC-->>Host: Completed end Host->>User: Build Complete → lfs-dist/

3.3 Flowchart — Logica di Checkpointing

Sistema di idempotenza: verifica checkpoint globale servizio, itera pacchetti con hash MD5, skip se già compilato, crea checkpoint su successo. Permette resume dopo interruzioni.

flowchart TD Start([🚀 Start Service Script]) --> Init[Inizializza Logging & Checkpointing] Init --> GlobalCheck{Checkpoint Globale
Esiste?} GlobalCheck -- Sì --> LogSkip[📝 Log: Service Already Completed] LogSkip --> EndSuccess([✅ Exit 0]) GlobalCheck -- No --> LoopPkgs[🔄 Itera Lista Pacchetti] LoopPkgs --> CalcHash[🔐 Calcola Hash MD5 Sorgente] CalcHash --> CheckPkg{Checkpoint Pkg
Esiste & Valido?} CheckPkg -- Sì, Hash Match --> SkipPkg[⏭️ Skip: già compilato] SkipPkg --> NextPkg CheckPkg -- No --> BuildStep[🔨 Esegui configure/make/install] BuildStep --> Success{Compilazione
OK?} Success -- No --> LogError[❌ Log Error] LogError --> ExitFail([💥 Exit 1]) Success -- Sì --> CreateCheck[💾 Crea Checkpoint File
+ Salva Hash] CreateCheck --> NextPkg NextPkg{Altri
pacchetti?} NextPkg -- Sì --> LoopPkgs NextPkg -- No --> Finalize[🏁 Crea Checkpoint Globale] Finalize --> EndSuccess style Start fill:#00aa00,color:#fff style EndSuccess fill:#00ff00,color:#000 style ExitFail fill:#ff4444,color:#fff style BuildStep fill:#ffaa00,color:#000

3.4 Class Diagram — Struttura Moduli Bash

Architettura modulare OOP-like in Bash: moduli comuni (logging, checkpointing) inclusi via source dagli script servizio. Pattern simile a ereditarietà/composizione.

classDiagram class CommonLogging { +init_logging() +log_info(msg) +log_step(msg) +log_error(msg) +log_success(msg) +finalize_logging(exit_code) } note for CommonLogging "Bash Module" class CommonCheckpointing { +CHECKPOINT_DIR +init_checkpointing() +should_skip_package(name, source_dir) +create_checkpoint(name, stage) +is_checkpoint_valid() +get_source_hash(dir) } note for CommonCheckpointing "Bash Module" class BaseServiceScript { #LFS_ROOT #SOURCES_DIR #LOG_FILE +main() +cleanup() } note for BaseServiceScript "Interface" class DownloadService { +PACKAGE_LIST +download_with_retry(url, dest) +verify_checksums() +extract_package(archive) } class BuildToolchainService { +build_binutils_pass1() +build_gcc_pass1() +build_glibc() +build_binutils_pass2() +build_gcc_pass2() } class BuildBaseSystemService { +prepare_chroot() +mount_virtual_fs() +build_in_chroot() +unmount_virtual_fs() } class ConfigureSystemService { +create_fstab() +configure_network() +install_bootscripts() } class BuildKernelService { +configure_kernel() +compile_kernel() +install_modules() } class PackageImageService { +create_disk_image() +format_partitions() +install_grub() +finalize_image() } BaseServiceScript ..> CommonLogging : source BaseServiceScript ..> CommonCheckpointing : source BaseServiceScript <|-- DownloadService BaseServiceScript <|-- BuildToolchainService BaseServiceScript <|-- BuildBaseSystemService BaseServiceScript <|-- ConfigureSystemService BaseServiceScript <|-- BuildKernelService BaseServiceScript <|-- PackageImageService

4. Quick Start

# Clone e entra nel progetto
git clone https://github.com/gnovelli/easylfs.git
cd easylfs

# Costruisci il sistema LFS completo (setup automatico incluso)
./easylfs build

# Lo script automaticamente:
# ✓ Inizializza i volumi Docker
# ✓ Costruisce tutte le immagini dei servizi
# ✓ Esegue la pipeline completa a 6 fasi
# ✓ Crea un sistema LFS bootabile

Comandi Utili

./easylfs status     # Controlla progresso e stato volumi
./easylfs logs       # Visualizza log di build
./easylfs export     # Esporta immagine disco finale
./easylfs shell      # Apri shell nel rootfs LFS
./easylfs clean      # Rimuovi container (mantieni volumi)
./easylfs reset      # Reset completo (rimuove tutto)
./easylfs help       # Mostra tutti i comandi disponibili

5. Accesso Web al Sistema LFS

Dopo aver costruito il sistema LFS, è possibile accedervi direttamente dal browser:

Web Terminal (ttyd)

Web Screen (noVNC)

# Avvia entrambe le interfacce
make web

# Oppure singolarmente
make web-terminal    # http://localhost:7681
make web-screen      # http://localhost:6080/vnc.html

# Ferma le interfacce
make web-stop

6. Requisiti di Sistema

7. Output Finali

Il sistema produce i seguenti deliverable:

8. Boot con QEMU

# Modalità console (raccomandato per SSH/remote)
qemu-system-x86_64 \
    -m 2G \
    -smp 2 \
    -drive file=lfs-12.4-sysv.img,format=raw \
    -boot c \
    -nographic \
    -serial mon:stdio

# Oppure con GUI (se eseguito localmente)
qemu-system-x86_64 \
    -m 2G \
    -smp 2 \
    -drive file=lfs-12.4-sysv.img,format=raw \
    -boot c

9. Struttura del Progetto

easylfs/
├── docker compose.yml          # File di orchestrazione principale
├── easylfs                     # Script CLI unificato
├── services/                   # Implementazioni dei servizi
│   ├── common/                 # Utility condivise
│   │   └── logging.sh          # Sistema di logging centralizzato
│   ├── download-sources/
│   ├── build-toolchain/
│   ├── build-basesystem/
│   ├── configure-system/
│   ├── build-kernel/
│   └── package-image/
├── tests/                      # Suite di test automatizzati
└── dist/                       # Immagini di output

10. Stato del Progetto

✅ PRODUCTION READY - Pipeline completa, funzionante e verificata!

Versione Attuale: v1.1.2

Tutte le funzionalità chiave sono complete:

11. Riferimenti

12. Riconoscimenti

Questo progetto è costruito sul progetto Linux From Scratch (LFS), utilizzando le istruzioni e comandi di build da LFS 12.4, forniti sotto licenza MIT.

EasyLFS automatizza e containerizza queste istruzioni preservando il valore educativo dell’approccio LFS. Si raccomanda fortemente di leggere il libro LFS originale per comprendere i concetti dietro ogni passaggio.

Crediti:

Scopri il progetto su GitHub

Link Correlati