Contributing
Thanks for contributing to Terra! Terra is specifically designed to be as package-maintainer-friendly as possible -- you don't need to know everything about the infrastructure to create a package for Terra! See the following guide for creating a new package yourself. Quick and easy.
It's also ok to suggest packages to include into Terra, though it might take a while. (We're busy!)
Remember, it takes effort to create a package. If you ever need help, hop into our Discord server (opens in a new tab) and we will try to help you.
Creating a package
Before you begin...
- Make sure the package name is not taken by other packages in Fedora repositories.
- Review our packaging policies.
- Review our custom SRPM macros
Preparation
- Install Andaman (opens in a new tab) on your system and its mock configs
sudo dnf install anda terra-mock-configs
via Terra- anda is also available via rust crates.io
- Use
rust2rpm
for Rust packages - Use
pyp2rpm
for Python packages - Use
go2rpm
for Go packages - else, find the source of the packages you are adding, preferably a URL to a
.tar.gz
archive- multiple archives are ok
- non
.tar.gz
archives are also ok, but might require additional build dependencies - we also prefer archives from git repositories
Writing sources
- Fork/clone the Terra sources repo (opens in a new tab)
- Create a folder named after the package name.
- e.g. you are creating a font package
lovelyfonttype
. Createanda/fonts/lovelyfonttype
- A Pantheon DE package goes into
anda/desktops/elementary/
.
- e.g. you are creating a font package
- Inside the folder, create
anda.hcl
and<packagename>.spec
- note: font packages in Fedora repos should end with
-fonts
, i.e. the folder name islovelyfonttype
but your spec file should belovelyfonttype-fonts.spec
- The name of the folder name actually is just for identifications for Terra package maintainers.
What matters is that the spec file name must match with the package name defined in the spec file later.
This is a Fedora
mock
limitation. - For more information, check out our packaging policies.
- note: font packages in Fedora repos should end with
- Edit
anda.hcl
, which tells Andaman (opens in a new tab) how to build the package:
project pkg {
rpm {
spec = "<packagename>.spec"
}
}
- Edit the spec file.
- It is a custom file format for RPM packages.
- This RPM Packaging Guide (opens in a new tab) might help newbies with no prior experiences with RPM specs.
- This Spec file format (opens in a new tab) docs goes into the details of the spec file format.
Editing the Spec file
TIP: Check out other spec files for other packages for some examples ;)
A generic spec file looks like this:
Name: pkgname
Version: 1.2.3
Release: 1%?dist
Summary: A package example
URL: https://example.com
Source0: https://github.com/some/repo/archive/%{version}.tar.gz
# You should change the above link to the source tarball you got from the preparation section
License: MIT
BuildRequires: some dependencies >= 3.2.1 another-dep
Requires: deps here
# We *highly* encourage you to add yourself as the packager here:
Packager: Your Name <[email protected]>
%description
This is a description of the package that literally does nothing.
%prep
%autosetup -n name-of-folder-after-source0-expansion
# if you are not using a tarball, simply use normal shell commands to extract the sources
echo "hai"
%build
echo "this will run when building pkg"
%install
echo "this will also run when building pkg but for installing it into %{buildroot} so that anda (mock) can package it"
%files
/usr/bin/pkgname-binary
/path/to/more/files/*/package
%changelog
* Wed Jan 11 2006 your-username-here <[email protected]>
- Description on what you've done
- Add
Source0
orSource1
or more. These preambles should link to a compressed file (preferablytar
) and will be extracted during%prep
You should've had the link prepared during #Preparation :3 - Add a new line
%prep
- The source file will be automatically downloaded and
extracted with
%autosetup -n <root dir name in tar file>
inside%prep
. Check outblackbox-terminal.spec
as an example - If it is not a tar archive, extract the file manually with a command.
See
authy.spec
as an example (unsquashfs
)
- The source file will be automatically downloaded and
extracted with
- Inside
%build
, you might need to build the package. Macros like%meson
and%cmake
are supported. Check outblackbox-terminal
orprismlauncher
- if not, manually state the command
- List out all the files to be included inside
%files
- Use
%doc
to state the README file (if it exists) - Use
%license
to state the COPYING or LICENSE file (if it exists) - TIP: If you are unsure about the files to install, run the build first.
mock
will show you the files not packaged but installed via an error
- Use
- Add
%changelog
(message preferably "Initial Package")
Building
- Having anda installed, run the following command:
anda build -c terra-rawhide-x86_64 anda/fonts/lovelyfonttype-fonts/pkg
If you would like to use the rpmbuild
mode instead (which will instead not set up a container), add --rpm-builder=rpmbuild
. Remember to install the build dependencies using dnf builddep path/to/pkgname.spec
!
- You don't need to create
pkg
. It's not supposed to exist - Modify the architecture to match your machine
- If the package fails to build, fix your spec file accordingly
- Usually the actual useful error message can be found before the Python traceback (from mock).
- The built RPM will be inside
anda-build/
Done?
- Git commit and push; remember you must sign your commits!
- Create a pull request that merges to the
main
branch
Automatic updates
The system regarding automatic updates are described here. Here is an overview:
Andaman (opens in a new tab) supports updating via .rhai
packages.
See the "book" (more like guide) for Rhai (opens in a new tab).
- Create
update.rhai
inside the package folder. - See references from other packages.
- You also need to add
labels { nightly = "1" }
in anda.hcl for nightly packages.
;
)Anda defaults the filename to update.rhai
.
If it's not update.rhai
, add a new entry inside anda.hcl
:
project pkg {
rpm {
update = "path/to/update.rhai"
...
}
}
SRPM Macros
We provide SPRM macros to ease packaging and better integrate into our workflow. Please use these macros over their counterparts when possible.
These are provided in the anda-srpm-macros
package, if you use them, make sure to add anda-srpm-macros
as a BuildRequires
in the spec file.
Macro | Function |
---|---|
%cargo_prep_online | Enables internet access for cargo . Replaces %cargo_prep and should be used in %prep |
%cargo_license_online | Replaces %cargo_license in %build |
%cargo_license_summary_online | Replaces %cargo_license_summary in %build |