On this page
A profile defines a bootable OnixOS image: which packages go into it, which files are added to the live root, and which boot modes the image supports. The profile source is maintained separately from both the package recipes and the build-system orchestration.
Start with the profile source
Work in the OnixOS profiles repository. Choose an existing profile with a similar image type and inspect its files as a set. Changing only the package list is not enough when the image also depends on boot entries, services or desktop setup.
| Path | What it controls |
|---|---|
profiledef.sh |
Image name, label, publisher metadata, declared architecture and boot modes |
packages.<arch> |
Binary package names requested for that architecture |
pacman.conf |
Package repositories used while assembling the image |
airootfs/ |
Files, services, users and configuration copied into the live root |
syslinux/, efiboot/ |
Boot entries for the modes declared by the profile |
Makefile and build scripts |
Profile-specific image recipe and cleanup behavior |
The package list names installable packages. The build system’s repository lists name package source projects, which may produce a different binary package name. Check each new entry against the package database and its PKGBUILD; see the package inventory and package/profile map.
Keep the architecture declarations aligned
An architecture must be supported at each layer:
profiledef.shdeclares it.- The profile has a matching
packages.<arch>file and the boot files required by its declared boot modes. - Every selected package and dependency is available for that architecture.
- The build-system configuration enables the target and the selected profile source.
The build system’s list of possible targets does not make an individual profile portable. The six standard install profiles currently declare x86_64; treat other profile targets as supported only when their manifests and package set say so. See system architecture for the distinction between repository and image targets.
Add the live environment carefully
Put image-specific defaults in airootfs/ and keep the overlay limited to files required by the live image or the installed system. Check file ownership, executable bits and service enablement. If a feature depends on a package unit or binary, make sure that package is in the matching package list for every architecture you declare.
Select an installer that matches the profile. Core uses the Onix CLI installer, desktop profiles use Calamares, and Server has its own automated installer. archinstall is the fallback present in the standard profiles; it is not a replacement for testing the profile’s primary path. The installer reference and installation guide describe the current choices.
Make it selectable by the build system
The profile project must be available at the source location configured for the build system, and its name must be present in the selected profile list. The build system fetches its configured sources; an uncommitted edit in a separate local checkout is not automatically picked up. Review the profile source configuration and the active profile list before starting a build.
The build-system image stage sets release metadata, checks the profile’s declared architecture, invokes the profile recipe and collects its artifacts. For a targeted image, the documented command form is:
python build.py image --profile=PROFILE --arch=ARCHBefore running a command, check the configured image synchronization destinations. A completed image stage may publish artifacts to those destinations. The output is organized under output/<release>/<profile>/<architecture>/, with a profile README.txt and RELEASE.txt beside the image artifacts. See Building OnixOS and the build system reference for stage and output details.
Review before accepting a profile
- Confirm every package name resolves from the profile’s configured repositories for each declared architecture.
- Check that the live overlay does not shadow package-owned files or enable a missing service.
- Boot each declared firmware mode and exercise the profile’s installer or first-run path.
- Record the tested machine, architecture and image artifact; do not infer hardware support from a successful build alone.
- Link the profile page and package choices from the profile reference after the profile is included in the maintained source set.
Archiso’s profile format is documented in the ArchWiki Archiso guide. The OnixOS profile group remains the source of truth for each image’s files and current status.