Terra Guidelines

Packagers and maintainers MUST follow the policies and guidelines listed in this document.

These are packaging guidelines for Terra. Everything covered here is one of 3 things:

• A difference in the Fedora Packaging Guidelines (opens in a new tab)
• In addition to the Fedora Packaging Guidelines (opens in a new tab)
• Adding a new guideline

If something seems missing, please refer to the Fedora Packaging Guidelines (opens in a new tab).

Terra Packaging Guidelines

Packager Field

The package maintainer of a package SHOULD be added to the Packager: preamble as follows:

Packager: Raboneko <raboneko@fyralabs.com>

Usages of the mold Linker

We encourage the use of mold (opens in a new tab), which may speed up build times especially in large projects. You MAY enable it in C/++ projects by adding -fuse-ld=mold in CFLAGS/CXXFLAGS.

The %with_mold flag is enabled by default in anda-srpm-macros. mold is also preinstalled in the builders.

You can disable mold for Rust and Nim by using %bcond_with mold.

Interpreted Languages (Python, Ruby, etc.)

All packages using interpreted languages follow the traditional Fedora guidelines. All dependencies must be packaged individually as they are considered runtime dependencies.

Dynamically Compiled Languages (C, C++, Vala)

Dependencies required for runtime MUST be packaged separately.

Statically Compiled Languages

As Terra does not strictly follow Fedora's reproducibility requirements, and we do not want large amounts of development libraries for them, packagers SHOULD vendor dependencies on build time.

Terra's mock sandbox has networking enabled, so builders can download the dependencies directly on build time.

Rust

• You may generate the spec file using rust2rpm.
• You SHOULD NOT use the tradtional Fedora %cargo_prep macro. Instead, use %cargo_prep_online from anda-srpm-macros. Also, you SHOULD remove the %generate_buildrequires macro, as it is useless.
• It is RECOMMENDED to use %cargo_license_online and %cargo_license_summary_online, although they are not a strict requirement.
• You SHOULD NOT use both %cargo_build and %cargo_install in the same spec file as anything that calls cargo install might cause a rebuild due to a cargo bug. You SHOULD only include %cargo_build or %cargo_install. In most cases, you can just omit %cargo_build entirely and it will build just fine. Example:

%prep
%autosetup -n %{crate}-%{version} -p1
%cargo_prep_online
 
%build
%{cargo_license_online} > LICENSE.dependencies
 
%install
%cargo_install

In some rare cases, you may need to use %cargo_build and %crate_install_bin instead:

%prep
%autosetup -n %{crate}-%{version}
%cargo_prep_online
 
%build
%{cargo_license_online} > LICENSE.dependencies
%{cargo_build} --locked
 
%install
# install the binary from target/rpm/%{crate} to %buildroot%_bindir
%crate_install_bin

If Rust nightly is required, add the %rustup_nightly macro to %prep.

Check the Rust section on the SRPM page for more information on these macros.

Go

If you use go2rpm, you SHOULD NOT use the default naming (except for non-leaf packages), as an unnecessarily long package name is bad for UX. You MAY put the name generated by go2rpm in the Provides: field.

Remove the %generate_buildrequires section, and add %global gomodulesmode GO111MODULE=on.

Nim

Use our Nim macros.

Zig

Many Zig projects rely on ReleaseFast (opens in a new tab) (or more rarely, ReleaseSmall (opens in a new tab)) builds for runtime optimization. Also, some Zig projects only work correctly when built for certain microarchitectures or higher (usually, this is x86_64_v2 instead of baseline due to reliance on SIMD).

If either of the above are the case for your package, you can use %zig_build_target with appropriate options in the %build or %install section depending on how the project is built (as some can be built directly into root by setting the DESTDIR=%{buildroot} variable).

Example:

%build
%{zig_build_target -r fast -c x86_64_v2} \
  -Demit-docs

Note that -c also works as a fallback option to the target architecture set by RPM if no following argument is supplied. However, this MUST be used when RPM and Zig architecture formats are the same, otherwise the build will fail.

Also, note that ReleaseFast (opens in a new tab) and especially ReleaseSmall (opens in a new tab) will strip some debug info from the binaries. Some Zig projects have enabled build flags to override this and those SHOULD be used if available (this will usually be -Dstrip=false). If they are not, you may need to disable debug packages using the global variable %global debug_package %{nil} if not enough debug info is preserved to strip.

For projects where dynamic linking of all dependencies is simply not possible (such as the version in the Fedora repos is too new or too old) or that have no dependencies to link, you can pass the -s flag. You SHOULD still dynamically link compatible dependencies by using -fsys=pkgname.

Shell Completions

• SHOULD be a subpackage.
• SHOULD use the %pkg_completion macro.

Development and Shared Libraries

You SHOULD try to use the %pkg_devel_files, %pkg_libs_files and %pkg_static_files macros.

Shared library packages SHOULD be suffixed with -libs. These packages SHOULD NOT contain anything except:

%_libdir/*.so.*
%doc …
%license …

Development library packages SHOULD be suffixed with -devel. These packages SHOULD NOT contain anything except:

%doc …
%license …
%_includedir/*
# ^ source files, depending on the language, could be in other locations
%_libdir/*.so
%_libdir/*.a
%_libdir/pkgconfig/%{name}.pc
# and other development files (.vapi, .typelib, .gir, etc.).

Miscellaneous

Patches

• A packages' %autosetup macro SHOULD use the -p1 flag only if patches are being applied.
• Packages SHOULD apply patches during %autosetup. If this is not possible (typically when %autosetup is not used), you SHOULD use %autopatch.

Fixing Packages

• If a package fix PR is fixing/changing anything user-facing, the Release: tag SHOULD be bumped. The only exception SHOULD be if you are fixing a package where the current version does not and has never built.
  • Some (not all!) examples of user-facing fixes requiring a Release: bump:
    • Installing a missing file.
    • Adding a package to the Requires:.
    • Changing any user-facing tags (URL:, License:, Summary:, etc.).
• If a package fix PR is fixing/changing anything build-facing, the Release: tag SHOULD NOT need to be bumped.
  • Some (not all!) examples of 'user-facing' fixes requiring a Release: bump:
    • Adding a package to the BuildRequires:.
    • Fixing a package that failed to build when the Version: tag is bumped.
    • Adding/changing new macros, build steps, install steps, or general source code handing during build time (assuming this does not affect the installed files the user will see).
• If you are unsure if a Release: bump is needed, please open the PR and ask, and we are happy to provide guidance!

Usage of Periods in Package Fields

• You MUST NOT have a period at the end of the Summary: tag, and you SHOULD have a period at the end of all %description descriptions.

Usage of %elifarch

To make specs easier to read, you SHOULD use %elifarch instead of %endif followed by %ifarch

Incorrect:

%ifarch x86_64
%define arch %{nil}
%endif
%ifarch aarch64
%define arch arm64-
%endif

Correct:

%ifarch x86_64
%define arch %{nil}
%elifarch aarch64
%define arch arm64-
%endif