arch-bootstrap/HACKING at master · librefos/arch-bootstrap · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
Este documento contém diretrizes de teste, regras de modificação e
convenções para contribuir com os scripts de reinstalação do sistema.

--- Testando os Scripts (Orquestrador de VM) ---------------------------

Um orquestrador test_env.sh robusto garante que nossos scripts
funcionem localmente de forma idêntica ao hardware real.  O script
invoca uma máquina virtual QEMU sem estado baseada no chipset q35.
Ele emula um dispositivo TPM 2.0 CRB via swtpm e expõe o repositório
do host através de um sistema de arquivos 9p mapeado por atributos
estendidos.

1. Inicie a VM:
   ./test_env.sh
   O orquestrador solicitará a escolha entre inicializar a ISO do
   Arch Linux (para testar o install.sh) ou inicializar um disco
   virtual existente (para testar o post_install.sh).

2. Monitoramento e Log:
   A saída do terminal da VM é capturada e despojada de sequências
   ANSI, sendo gravada continuamente no arquivo vm_execution.log.
   Se os inputs quebrarem durante o teste, pressione Ctrl+Alt+2 para
   acessar o monitor do QEMU.

3. Execução:
   Siga as instruções impressas na tela pelo orquestrador para
   montar a pasta compartilhada e executar o instalador base contra
   o disco virtual (/dev/vda).

--- Modificando os Scripts de Implantação ------------------------------

O script install.sh depende da resolução dinâmica de dispositivos de
bloco para lidar de forma previsível com unidades NVMe e VirtIO.  Se
você alterar o layout do sfdisk, deverá atualizar as variáveis
PART_EFI e PART_ROOT adequadamente.

As operações em chroot são isoladas dentro de um heredoc no
install.sh.  Esse padrão elimina a necessidade de copiar scripts
secundários prematuramente.

No post_install.sh, interações com o usuário via prompts de leitura
devem sempre ser roteadas estritamente através do /dev/tty usando
referências de nome (namerefs) do Bash.  Isso impede que subshells
quebrem a captura de log durante a execução automatizada.

--- Licença ------------------------------------------------------------

Copyright (C) 2026 Thiago C Silva.  Distribuído sob a licença GPLv3 ou
posterior.  Consulte o arquivo LICENSE para mais detalhes.


--- English Version ----------------------------------------------------

--- HACKING - Arch Linux Re-installation Project -----------------------

This document contains testing guidelines, modification rules, and
conventions for contributing to the system re-installation scripts.

--- Testing the Scripts (VM Orchestrator) ------------------------------

A robust test_env.sh orchestrator guarantees our scripts work
identically locally as they do on bare metal.  The script invokes a
stateless QEMU virtual machine built on the q35 chipset.  It emulates
a TPM 2.0 CRB device via swtpm and safely exposes the host's script
repository through an extended-attribute mapped 9p filesystem.

1. Start the VM:
   ./test_env.sh
   The orchestrator will prompt you to choose between booting the Arch
   Linux ISO (to test install.sh) or booting an existing virtual disk
   (to test post_install.sh).

2. Monitoring and Logging:
   The VM's terminal output is stripped of ANSI sequences and streamed
   continuously to vm_execution.log.  If your input grabs break
   during testing, press Ctrl+Alt+2 to drop into the QEMU monitor.

3. Execution:
   Follow the on-screen instructions printed by the orchestrator to
   mount the shared folder and execute the base installer against the
   virtual disk (/dev/vda).

--- Modifying the Deployment Scripts -----------------------------------

The install.sh script relies on dynamic block device resolution to
predictably handle NVMe and VirtIO drives.  If you alter the sfdisk
layout, you must update the PART_EFI and PART_ROOT assignments.

Chroot operations are isolated within a heredoc in install.sh.  This
pattern removes the need to copy secondary scripts prematurely.

In post_install.sh, interactive user prompts must always be routed
strictly through /dev/tty utilizing Bash namerefs.  This architecture
prevents subshells from breaking the standard output log captures
during automated execution.

--- License ------------------------------------------------------------

Copyright (C) 2026 Thiago C Silva.  Distributed under the GPLv3 license
or later.  See the LICENSE file for details.