|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +<!-- LLM Generated: This file was created by Claude (claude.ai/code) --> |
| 4 | + |
| 5 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 6 | + |
| 7 | +## Project Overview |
| 8 | + |
| 9 | +**AlterLinux** is an Arch Linux-derived OS optimized for Japanese users. **AlterISO 6.0** (in the `dev` branch) is the build system that generates ISO images using a profile generation approach. It creates archiso-compatible profiles from AlterISO configuration files and uses an "Injectable" mechanism to hook into archiso functions without modifying upstream code. |
| 10 | + |
| 11 | +## Build Commands |
| 12 | + |
| 13 | +```bash |
| 14 | +# Generate archiso profile from AlterISO config |
| 15 | +./alteriso/gen.sh configs/<profile_name> |
| 16 | + |
| 17 | +# Build ISO image (generates profile + runs mkarchiso) |
| 18 | +cd alteriso && ./build.sh |
| 19 | + |
| 20 | +# Or directly with Go |
| 21 | +go run ./src profile build configs/<profile_name> |
| 22 | + |
| 23 | +# Clean generated profiles |
| 24 | +./alteriso/clean.sh |
| 25 | + |
| 26 | +# Lint shell scripts |
| 27 | +make check |
| 28 | +``` |
| 29 | + |
| 30 | +Build requires root privileges. Output goes to `alteriso/out/`, work directory is `alteriso/work/`. |
| 31 | + |
| 32 | +## Architecture |
| 33 | + |
| 34 | +### Core Components |
| 35 | + |
| 36 | +- **Go Application** (`alteriso/src/`): Profile generation using Cobra CLI |
| 37 | + - `internal/cmd/` - CLI commands (root, profile generate, profile build) |
| 38 | + - `internal/archiso/` - Profile parsing, generation, and Injectable handling |
| 39 | +- **Modules** (`alteriso/modules/`): Pluggable units providing packages, files, scripts, and injection hooks |
| 40 | +- **Bootloaders** (`alteriso/bootloaders/`): BIOS/UEFI boot configuration templates |
| 41 | +- **archiso** (`archiso/`): Forked upstream archiso with Injectable support |
| 42 | + |
| 43 | +### Data Flow |
| 44 | + |
| 45 | +1. User provides `configs/<profile>/profiledef.json` + `profiledef.sh` |
| 46 | +2. Go tool reads JSON, loads referenced modules from `modules/` directory |
| 47 | +3. Modules provide: packages, files, scripts, injection hooks |
| 48 | +4. AlterISO merges everything → generates archiso-compatible profile in `out/` |
| 49 | +5. mkarchiso builds ISO with injected hooks |
| 50 | + |
| 51 | +### Injectable Mechanism |
| 52 | + |
| 53 | +AlterISO leverages archiso's `_run_once()` function which sources `profiledef.sh`. Generated `profiledef.sh` includes: |
| 54 | +- Pre/post hooks: `pre_<function>()`, `post_<function>()` |
| 55 | +- Override hooks: `override_<function>()` |
| 56 | +- Example: `post__make_packages()`, `pre__make_customize_airootfs()` |
| 57 | + |
| 58 | +### Module Structure |
| 59 | + |
| 60 | +``` |
| 61 | +modules/<name>/ |
| 62 | +├── alteriso.json # Module manifest (required) |
| 63 | +├── module.sh # Shell script with hook functions |
| 64 | +├── packages.x86_64.d/ # Package lists |
| 65 | +├── airootfs.any/ # Files for all architectures |
| 66 | +└── airootfs.x86_64/ # Architecture-specific files |
| 67 | +``` |
| 68 | + |
| 69 | +### Profile Configuration |
| 70 | + |
| 71 | +`profiledef.json` fields: |
| 72 | +- `arch` (required): Target architecture (currently "x86_64") |
| 73 | +- `modules` (required): List of modules to load in order |
| 74 | +- `os_name`, `kernel_name`, `username`, `cow_spacesize`: Optional config |
| 75 | +- `injects`: Profile-level injection hooks |
| 76 | +- `require_injectable`: Whether profile needs Injectable archiso support |
| 77 | + |
| 78 | +Placeholders in bootloader configs: `%ALTERISO_OS_NAME%`, `%ALTERISO_KERNEL_NAME%`, `%ALTERISO_COW_SPACESIZE%`, `%ALTERISO_KERNEL_PARAM%` |
| 79 | + |
| 80 | +## Key Files |
| 81 | + |
| 82 | +- `alteriso/src/internal/archiso/profile_gen.go` - Main profile generation logic |
| 83 | +- `alteriso/src/internal/archiso/injects/profiledef.sh.in` - Template for generated profiledef.sh |
| 84 | +- `alteriso/src/internal/archiso/injects/injecter.sh` - Hook injection mechanism |
| 85 | +- `alteriso/configs/xfce/profiledef.json` - Example profile configuration |
| 86 | + |
| 87 | +## Important Notes |
| 88 | + |
| 89 | +- Module load order matters: determines precedence for injections and file overwrites |
| 90 | +- Scripts rebuild Go binary each time; binaries are cleaned up after |
| 91 | +- Documentation is primarily in Japanese (see `alteriso/docs/`) |
| 92 | +- Testing is done by building ISO and running with qemu (`scripts/run_archiso.sh`) |
| 93 | +- Changes to archiso upstream may require updates to injection templates |
| 94 | + |
| 95 | +## LLM-Generated Content Rules |
| 96 | + |
| 97 | +This project distinguishes between LLM-generated and human-written code. When creating new files or making substantial changes, follow these rules: |
| 98 | + |
| 99 | +### Marking New Files |
| 100 | + |
| 101 | +Add an LLM marker comment at the top of new files: |
| 102 | + |
| 103 | +- **Markdown files**: `<!-- LLM Generated: Created by Claude -->` |
| 104 | +- **Go files**: `// LLM Generated: Created by Claude` |
| 105 | +- **Shell scripts**: `# LLM Generated: Created by Claude` |
| 106 | +- **JSON files**: Add `"_llm_generated": "Created by Claude"` field |
| 107 | + |
| 108 | +### Marking Existing File Changes |
| 109 | + |
| 110 | +When making substantial changes to existing files, add a comment near the modified code: |
| 111 | + |
| 112 | +```go |
| 113 | +// LLM Modified: Added error handling - Claude |
| 114 | +``` |
| 115 | + |
| 116 | +```bash |
| 117 | +# LLM Modified: Refactored validation logic - Claude |
| 118 | +``` |
| 119 | + |
| 120 | +### Git Commit Messages |
| 121 | + |
| 122 | +Include the Co-Authored-By trailer in commit messages: |
| 123 | + |
| 124 | +``` |
| 125 | +Co-Authored-By: Claude <noreply@anthropic.com> |
| 126 | +``` |
0 commit comments