This repository contains all the recipes required to build aerynOS from source.
| Resource | Description |
|---|---|
| Documentation | Learn about aerynOS concepts and packaging |
| Packaging Policy | aerynOS Package Addition Policy |
| Packaging Guide | Detailed packaging documentation |
| Zulip Chat | Community discussion (requires join) |
| Contributing Guidelines | Full contribution process and policies |
| GenAI Policy | We do not accept contributions authored using genAI/LLM chatbots or agents |
Recipes define how packages are built and packaged for aerynOS. Each recipe describes the build process, dependencies, and metadata needed to create installable packages using our tooling stack (primarily Boulder/moss).
aerynOS is currently in Alpha quality and serves as a tech preview focused on proving our tooling approach. Until our infrastructure matures, we must be selective about packages to avoid exploding manual rebuild requirements.
Where we are currently at:
- We already have 7 DE / WM environments in our repository
- We ship Flatpak w/ preconfigured flatpub
- We include the apps our staff need to dogfood aerynOS day to day
- The development tools for packaging and developing the distribution.
What packages are we likely to accept:
- Do not require complex rebuild dependency chains
- You are willing to maintain over the long term
- Have appropriate Open Source Licences with permission to redistribute
Other areas of focus:
- Stateless enabling (+ hermetic usr)
- Kernel enabling
- Metrics-based performance improvements of packages
- Package updates and bug fixes
Until our infrastructure matures, if packages are not available in our repository, you may be asked to use Flatpaks and AppImages instead.
Before submitting, ensure you understand:
- Git Commit Messages: Follow our summary format (
name: Add at v<version>,name: Update to v<version>,name: Fix <...>,[NFC] name: <description of no functional change commit>) - Repository Size: We're actively working on technology to scale the repo without ABI mismatch concerns. Until then, strict package acceptance applies.
- GenAI Policy: We do not accept contributions authored using generative AI/LLM chatbots or agents. Our goal is human skill development, not atrophy through automation. Read more in our contributing guidelines.
GitHub doesn't natively support selecting from multiple PR templates, so we've set up a semi-manual workflow:
-
Click "New Pull Request" to begin the PR creation process
-
Use the Preview Box: In the PR description area, click the Preview tab to access our template selector
-
Choose the Right Template:
- Select the template that best matches your contribution type
- Common templates include: New Recipe, Recipe Update, Bug Fix, Documentation
-
Fill Out the Template Completely: Provide all requesting information, which will vary depending on the template
-
Submit Your PR: Once complete, submit and wait for maintainer review.
- Test builds on an aerynOS host system before submitting
- Follow existing recipe patterns and coding style
- Include clear commit messages following our git summary format
- Link related GitHub issues if applicable
- Be responsive to reviewer feedback
Reviews may take some time depending on maintainer availability. Once your PR passes review, a maintainer will merge it. 🎉
Common just commands for local testing:
just bump- bump the release number in the nano recipejust build- Build the recipe locallyjust mv-local- Move the newly built.stonebuild artifacts to the local repositoryjust ls-local- List the build artifacts present in the local repositoryjust clean- Clean*.stoneartefacts from the current directoryjust clean-local- Clean*.stoneartefacts from the local repository
Refer to the justfile in the repository root for the full command list.
We provide .jsonc (JSON with comments) manifest files, however, the popular jq tool doesn't currently support .jsonc files.
That said, you can use the C preprocessor to strip any comments before passing to jq as follows:
cpp -P -E manifest.x86_64.jsonc | jq .packages
Create a .env file in the root of the recipes/ directory, next to the supplied justfile.
Example .env file:
# All installs need a default local repository set up for convenience
# If you're awkward and want to use a different path than the default,
# uncomment and change it below:
# LOCAL_REPO="${HOME}/.cache/local_repo/x86_64"
If you are not building on aerynOS using the os-supplied boulder package, or if you want to specify custom arguments
to the boulder invocation when using the just targets, you might benefit from adding some or all of the following options
to your .env file in recipes/ root next to the justfile:
# Uncomment this if you want to use a different boulder than the one in /usr/bin
# BOULDER="${HOME}/.local/bin/boulder"
# Uncomment this if you want to explicitly override the shipped boulder configuration
# BOULDER_ARGS="--data-dir=${HOME}/.local/share/boulder --config-dir=${HOME}/.config/boulder --moss-root=${HOME}/.cache/boulder"
The justfile is set up so you can also choose to specify environment variables on a command-line invocation of just:
Example:
BOULDER_ARGS="--data-dir=${HOME}/.local/share/boulder" just build
- Documentation - Start here for concepts and guides
- Zulip - Our community chat server:
- General - Open to everyone, good starting point
- Onboarding (packaging etc.) - A good place for interacting on packaging
- Questions - For general questions you may have
- GitHub Issues - For bugs and feature requests; search first to avoid duplicates
Note that while Zulip channels are publicly viewable, participation in certain channels requires the Trusted Contributor role. This is granted after demonstrating genuine interest in contributing to the project.
Unless otherwise specified, all packaging recipes are available under the terms of the MPL-2.0 licence.
Individual software releases are available under the terms specified upstream, collected in each stone.yaml recipe. Any patches against a software package is under the relevant license for each upstream.