[Draft Guidelines] Crystal Packaging Guidelines (Changes/CrystalLanguage)

Hello Fedora Packagers & Fedora Packaging Committee,

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.

Per the Fedora Changes Policy on Essential Communication, we are sharing this draft early so the packaging committee and the wider community can evaluate the proposed packaging model.

Draft Documents


Key Architectural Highlights

  1. Shard-as-RPM Model (Unbundled Sources):

    • 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.
  2. 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".
  3. Virtual Provides & File Attributes:

    • Automatic RPM file attribute generator (/usr/lib/rpm/fileattrs/crystalshard.attr) inspects installed shard.yml files and emits:
      Provides: crystal-shard(<name>) = <version>
    • Applications specify dependencies via BuildRequires: crystal-shard(<name>).
  4. 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.
  5. 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!

Can you bring this up during a Packaging Committee meeting (bi-weekly, next one is on Sep 3)? Most of us don’t monitor Discourse regularly :slight_smile:

One thing that I noticed in the guidelines draft at https://codeberg.org/renich/crystal-in-fedora/src/branch/master/guidelines/packaging-crystal.rst#package-naming-parallel-versioning:

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 :sad_but_relieved_face:

2 Likes

Yep. I will look for the schedule and be there.

About discourse, got it. ;D

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.

2 Likes

xref

(Change Proposal discussion)

The Rust guidelines actually do both:

  • 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
2 Likes

Thanks for clarifying the clarification.

That makes a lot of sense.

I will update the draft packaging guidelines (and cr2rpm) to adopt this model.

Looking forward to discussing this at tomorrow’s Packaging Committee meeting. :slight_smile:

2 Likes

Hello everyone,

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:

:backhand_index_pointing_right: FPC PR #1568: Making sure you're not a bot!
:backhand_index_pointing_right: Tracking Issue #1567: Making sure you're not a bot!

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:

  • Track 1: Shared Shard Libraries (Unbundled Shard-as-RPM):
    • 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.
  • Track 2: Statically-Linked Standalone Applications (Vendoring Permitted):
    • 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:

  • crystal-rpm-macros v0.2.0 (Codeberg Release):
    • 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.
  • cr2rpm v0.2.0 (Codeberg Release):
    • Adds cr2rpm vendor to generate bit-for-bit reproducible <name>-<version>-vendor.tar.xz archives with normalized permissions and timestamps.
    • Automates bundled Provides: bundled(...) virtual provides and multi-license aggregation in cr2rpm generate --vendor.
    • Adds cr2rpm inspect and the DependencyInspector engine to automatically discover system C library bindings (@[Link(...)]) and stdlib C-backed modules.
    • Implements --compat generation conforming strictly to Fedora Packaging Guidelines (Naming/#multiple).

3. 100% Mass Build & Packaging Validation in Copr

To prove that this entire architecture works reliably in clean, offline mock roots, we deployed the suite to Fedora Copr (renich/crystal):

  • Cold-start bootstrap: Compiler (crystal-lang) and package manager (shards) bootstrap tested.
  • 100% build matrix success on both fedora-rawhide-x86_64 and fedora-rawhide-aarch64 across 22 packages:
    • Core toolchain: crystal-lang, shards, crystal-rpm-macros, cr2rpm, vim-crystal.
    • Base shards & drivers: crystal-db, crystal-sqlite3, crystal-pg, crystal-mysql, crystal-radix, crystal-backtracer, crystal-exception_page.
    • Web ecosystem: crystal-kemal, crystal-kemal-session, crystal-kemal-basic-auth, crystal-spec-kemal.
    • Developer tooling: crystal-ameba, crystal-flaw, crystal-tartrazine.
    • Entire Crest REST client stack: crystal-crest, crystal-http-client-digest_auth, crystal-http_proxy, crystal-cookie_jar, crystal-habitat, crystal-vcr, crystal-webmock.
    • Compiled vendored applications: cryload.

We invite the committee and packagers to review PR #1568 and test the packages in Copr!

Hello everyone!

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:

Package Bugzilla Ticket Type and Arch Summary
crystal-rpm-macros RHBZ #2560262 noarch RPM macros (%crystal_setup, %crystal_build, %crystal_install_lib), fileattrs, and shards-link offline workspace linker
cr2rpm RHBZ #2560265 noarch Automated Fedora spec, dependency inspection, and reproducible vendor archive generator for Crystal shards
vim-crystal RHBZ #2560266 noarch File type detection, syntax highlighting, and crystal tool/crystal spec integration for Vim and Neovim
crystal-lang RHBZ #2560263 x86_64, aarch64 Crystal 1.22.1 compiler (crystal), standard library, HTML docs (crystal-docs), and samples (crystal-samples)
shards RHBZ #2560264 x86_64, aarch64 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!


Note: Drafted with Gemini, AI pair programmer collaborating with Rénich Bon Ćirić.