In conjunction with the System-Wide Change Proposal Changes/CrystalLanguage targeting Fedora 45+, I would like to present the initial draft of the Fedora Packaging Guidelines for Crystal for community review and FPC feedback.
Shard libraries are packaged as unbundled source packages installing into versioned directories: %{_datadir}/crystal/shards/<name>-<version>.
Multiple versions of the same shard can coexist on the same system without RPM filesystem collisions, allowing applications to build against specific SemVer versions matching shard.lock.
Offline Dependency Discovery & Resolution:
Builds in Mock/Koji run with zero network access.
During %prep, %crystal_setup links required shard dependencies from %{_datadir}/crystal/shards/ into local ./lib/<name>.
Compilation and check macros configure CRYSTAL_PATH="lib:%{crystal_shards_dir}:%{_datadir}/crystal/src".
Applications specify dependencies via BuildRequires: crystal-shard(<name>).
Compiler Hardening & Standard Macros:
Packages use the standard macro suite (%crystal_build, %crystal_install, %crystal_install_lib, %crystal_check).
Binaries inherit standard Fedora hardening flags: %optflags via CFLAGS and %build_ldflags via --link-flags.
Bootstrap Policy Compliance:
Initial compiler bootstrap into Fedora uses the standard Koji side-tag workflow (identical to rustc and zig), complying fully with the No Pre-compiled Binaries Policy. Routine updates self-host natively.
We welcome feedback, questions, and suggestions from packagers and the FPC on this draft specification!
Use upstream shard name (e.g., kemal, radix), or crystal-<name> when disambiguation against existing packages is required.
I think it would make sense to just use the crystal- prefix unconditionally. It results in a clear 1:1 mapping from shard names to RPM package names. Only using the prefix to disambiguate in case of collisions means that it’s not easy to determine programmatically, and makes some things more annoying (repository queries, defining policies that are supposed to cover all “Crystal library packages”, etc.).
Side note: You’ll also need to rewrite whatever ends up being submitted as policy to the Packaging Guidelines in AsciiDoc - the docs system uses that and not reStructured Text
The thing is some shards are libraries and others might be frameworks or binaries (or mixed). Additionally, there are crystal shards that already use `crystal-` as a prefix.
I think we could consider rust’s or go’s guidelines as base and use either `shard-` or `crystal-` as prefix for libraries and use just the name when it comes to binary apps or frameworks.
This definitely needs more consideration. I would like to hear the opinion of the crystal community on this as well.
Yeah, noted. I will re-write in AsciiDoc as required once the guidelines are approved.
Thank you, Fabio, for taking the time to comment and review.
source package name is unconditionally rust-$crate
if the package also includes an application, the built binary package name defaults to $crate (but this is configurable) - i.e. dnf install ripgrep gives you ripgrep, even if the source package name is rust-ripgrep
if the package also includes a library interface, the built packages are named rust-$crate-*-devel
Following up on the discussion from earlier this week, I am glad to share that the draft Crystal Packaging Guidelines have been significantly expanded, aligned with committee feedback, and submitted as an official pull request to the Fedora Packaging Committee:
Here is a summary of the architectural refinements and validation work completed:
1. Dual-Track Packaging Model (Vendoring for Leaf Applications)
To balance distro unbundling with pragmatic leaf application maintenance, the guidelines now formally codify a Dual-Track Packaging Architecture directly mirroring Fedora’s Go and Rust packaging models:
Packaged as individual, unbundled RPMs installing uncompiled source trees to versioned directories: %{_datadir}/crystal/shards/<name>-<version>.
Allows multiple SemVer minor versions of the same library to coexist in parallel without DNF file collisions.
Primary packages provide unversioned symlinks (%{_datadir}/crystal/shards/<name> -> <name>-<version>) for zero-config CLI development (the LLVM model), while compatibility packages (--compat, %global crystal_compat 1) omit unversioned symlinks to avoid filesystem collisions.
For complex, standalone compiled binaries where unbundling the entire dependency tree is impractical or burdensome, packagers may vendor shard dependencies using an offline source tarball (Source1: %{name}-%{version}-vendor.tar.xz).
Requires explicit virtual provides for all bundled shards: Provides: bundled(crystal-shard(<name>)) = <version>.
Requires combined effective SPDX expressions in the License: tag (joined with AND), with all bundled licenses staged cleanly under %files to prevent license collisions in %{_licensedir}.
2. Tooling Ecosystem Releases (v0.2.0)
Our packaging automation and build macros have been tagged and released at v0.2.0:
Delivers the shards-link CLI workspace linker (/usr/bin/shards-link), enabling hermetic, offline dependency symlinking into local ./lib from system shard directories.
Provides %crystal_install_lib(n:c) and %crystal_files(n:c) with -c compatibility mode flags.
Standardizes build environments via %{crystal_envvars} and %crystal_env.
Great news: FESCo has officially approved the Fedora 46 System-Wide Change Proposal for Crystal with a +5, 0, -0 vote in FESCo Ticket #3690!
With FESCo approval in place and all 27 packages in our renich/crystal Copr repository building cleanly on both x86_64 and aarch64 (fedora-rawhide and fedora-44), we have submitted the Stage 1 Fedora Package Reviews on Red Hat Bugzilla.
Call for Package Reviewers: Stage 1 Toolchain and Tooling
We warmly invite Fedora packagers to help review these five foundational packages, and we are happy to do review swaps:
Official dependency manager v0.20.0 for the Crystal programming language
All five specs and SRPMs have been audited against the Fedora Crystal Packaging Guidelines in FPC PR #1568, pass rpmlint with 0 errors and 0 warnings, and are hosted directly at https://renich.fedorapeople.org/crystal/.
Tip for reviewers: crystal-rpm-macros, cr2rpm, and vim-crystal are fast, self-contained noarch packages that do not require the Crystal compiler to build or review.
Thank you to everyone who has tested, provided feedback, and supported the effort so far!