diff --git a/app/terra/[...slug]/page.tsx b/app/terra/[...slug]/page.tsx new file mode 100644 index 00000000..c67a55e5 --- /dev/null +++ b/app/terra/[...slug]/page.tsx @@ -0,0 +1,37 @@ +import { permanentRedirect } from "next/navigation"; + +export async function generateStaticParams() { + return [ + { slug: ["appstream"] }, + { slug: ["autoupdate"] }, + { slug: ["contributing"] }, + { slug: ["faq"] }, + { slug: ["guidelines"] }, + { slug: ["index"] }, + { slug: ["infrastructure"] }, + { slug: ["installing"] }, + { slug: ["lifecycle"] }, + { slug: ["policies"] }, + { slug: ["srpm"] }, + ]; +} + +export default async function Page({ params }: { params: Promise<{ slug: string }> }) { + const { slug } = await params; + + const slugKey = slug.toString(); + const REDIRECT_MAP: Record = { + appstream: `https://docs.terrapkg.com/contributing/${slug}`, + autoupdate: `https://docs.terrapkg.com/contributing/${slug}`, + contributing: `https://docs.terrapkg.com/contributing/${slug}`, + guidelines: `https://docs.terrapkg.com/contributing/${slug}`, + policies: `https://docs.terrapkg.com/contributing/${slug}`, + srpm: `https://docs.terrapkg.com/contributing/${slug}`, + installing: `https://docs.terrapkg.com/usage/${slug}`, + lifecycle: `https://docs.terrapkg.com/usage/${slug}`, + infrastructure: `https://docs.terrapkg.com/general/${slug}`, + faq: `https://docs.terrapkg.com/reference/${slug}`, + }; + + permanentRedirect(REDIRECT_MAP[slugKey] ?? "https://docs.terrapkg.com"); +} diff --git a/content/docs/andaman/mechanisms.mdx b/content/docs/andaman/mechanisms.mdx index d8f93c8f..5a1ec52b 100644 --- a/content/docs/andaman/mechanisms.mdx +++ b/content/docs/andaman/mechanisms.mdx @@ -48,7 +48,7 @@ The following static modules (built into AndaX directly) are also available: - `anda::rpmbuild` - `anda::cfg` -Most if not all of the functions in the above static modules are well-documented in the [Terra documentation](/terra/autoupdate). +Most if not all of the functions in the above static modules are well-documented in the [Terra documentation](https://docs.terrapkg.com/contributing/autoupdate). You can pass labels into the AndaX executor during with the `--labels command-line argument`. A label is a key-value pair that can be used to tag packages (is it a nightly package?), adding special variables, etc. @@ -70,7 +70,7 @@ Which will be parsed to: ## Automatic Updates -See [Terra autoupdate documentation](/terra/autoupdate) for supported functions in AndaX +See [Terra autoupdate documentation](https://docs.terrapkg.com/contributing/autoupdate) for supported functions in AndaX Anda supports automatically updating packages via the `anda update` command. The command finds all the projects with an `update.rhai` in the same directory. diff --git a/content/docs/rpm/index.mdx b/content/docs/rpm/index.mdx index b77a7a0e..2e20381c 100644 --- a/content/docs/rpm/index.mdx +++ b/content/docs/rpm/index.mdx @@ -22,4 +22,4 @@ to [Terra], packaging a few apps you find possibly useful to other people using We hope you find this document useful. -[Terra]: https://terra.fyralabs.com +[Terra]: https://terrapkg.com diff --git a/content/docs/rpm/macros.mdx b/content/docs/rpm/macros.mdx index 684a87b6..0edd0d7e 100644 --- a/content/docs/rpm/macros.mdx +++ b/content/docs/rpm/macros.mdx @@ -18,7 +18,7 @@ Technically, there are 3 types of "macros": This document only covers the first type. - This page does not cover Terra-specific (Anda SRPM) macros. For documentation on these macros, see [here](../terra/srpm). For documentation on our AppStream MetaInfo macros, see [here](../terra/appstream). + This page does not cover Terra-specific (Anda SRPM) macros. For documentation on these macros, see [here](https://docs.terrapkg.com/contributing/srpm). For documentation on our AppStream MetaInfo macros, see [here](https://docs.terrapkg.com/contributing/appstream). @@ -978,7 +978,7 @@ Parameterized as `%patch(b:p:P:REz:)`. This list is NOT exhaustive. Some macros are not built-in. If your machine does not come with them, try `dnf install 'rpm_macro(macro_name)'{:sh}`. -Macros with the '(Terra only)' warning are part of the `anda-srpm-macros` package in Terra, documentation for these can be found on the [Terra SRPM devdocs page](https://developer.fyralabs.com/terra/srpm#directories). +Macros with the '(Terra only)' warning are part of the `anda-srpm-macros` package in Terra, documentation for these can be found on the [Terra SRPM devdocs page](https://docs.terrapkg.com/contributing/srpm#directories). ``` / diff --git a/content/docs/terra/appstream.mdx b/content/docs/terra/appstream.mdx deleted file mode 100644 index f4cc1682..00000000 --- a/content/docs/terra/appstream.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: AppStream -description: "How to use AppStream MetaInfo in Terra packages." ---- - -## Overview - -Terra supports AppStream MetaInfo, which enables your package to be picked up by graphical software 'store' applications, such as [KDE Plasma's Discover](https://apps.kde.org/discover/) or [GNOME's Software app](https://apps.gnome.org/Software/). -In Ultramarine, we encourage the use of these graphical store, so adding AppStream MetaInfo is great for discoverability. -This page will cover creating and installing AppStream MetaInfo to your package, but we also highly encourage you to read over the documentation [here](https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html). - -If you have difficulty populating the `.metainfo.xml` file, hop into our [Discord](https://fyralabs.com/discord) server, or make a draft pull request asking for assistance. - - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", - "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be - interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) - and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174). - - -## When Should I Use AppStream MetaInfo? - -Packages that fit any of the following cases SHOULD provide the metainfo file. - -- If upstream already provides the metainfo file, you SHOULD `install` it instead of making your own -- Graphical apps -- TUI applications that make sense to be opened in a graphical environment (ships a `.desktop` file) - -Other packages MAY also provide appstream metadata files. - -## Creating the `metainfo.xml` File - -Before creating your `metainfo.xml` file, check out our [AppStream helper macro](./appstream#terra_appstream), it can save a lot of effort. - -Determine your package's app ID, then start with the template below. -The metainfo file MUST be named `app_id.metainfo.xml{:ansi}`. -For example, `com.github.neohtop.metainfo.xml`. - -### Determining the App ID - -If your package has an app ID used in file names, or references an app ID in any way, you MUST use this as the app ID in your spec. -See [here](#installing-your-metainfo-file) to learn how to define the app ID in your spec file. - -If you do not know what the app ID of the package is, determine it using [reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation). - -- If your package is only hosted on GitHub (no website, not a GitHub mirror), then the app ID MUST be `com.github.APP-NAME{:ansi}`. -- If your package has its own website, or the organization that creates it does, you MUST use its website in the app ID. Using Microsoft Edit as an example, the app ID will be `com.microsoft.Edit`. - -### metainfo.xml Template - -Everything in this template SHOULD be in your metainfo.xml, but there are many optional sections not included that you may want. -We will go over the important ones in the next section. - -```xml - - - - APPID - CC0-1.0 - LICENSE - ICON DIRECTORY - - NAME - SUMMARY - - -

- DESCRIPTION. -

- - - NAME.desktop - - URL - - - - - -``` - -### Optional metainfo.xml sections - -These metainfo tags are optional, but it is RECOMMENDED to use as many as you can to properly flesh out the metainfo. -Other tags exist that are not listed, you are free to use them, but they're generally not useful. - -All information here is based on the freedesktop.org specification, and each section links to its respective Freedesktop page for more info. -Again, we highly recommend you read through the entire spec [here](https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html) and [here](https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html). - -#### Keywords - -The `{:xml}` tag[^2] will make your package easier find when users search these terms: - -```xml - - IDE - development - programming - entwicklung - programmierung - -``` - -#### Developer - -This tag[^3] is to specify the developer/s of your package. This can be a person or group/organization. - - - You MUST NOT use the `{:xml}` tag. - - -#### Screenshots - -This tag[^4] can be either a video or a picture, and is used to showcase the package in software stores. -You can (and should) use full URLs to screenshots. - -Freedesktop's example: - -```xml - - - The FooBar main window. - https://example.com/foobar/screenshot-1.png - - - Foobar showing the frobnicate functionality. - https://example.com/foobar/screenshot-2.png - - - - - - - The FooBar main window, but on Plasma Mobile - https://example.com/foobar/screenshot-1_plasma-mobile.png - - - - The FooBar main window, on GNOME in dark mode - https://example.com/foobar/screenshot-1_gnome_dark.png - - -``` - -## Using your metainfo.xml file in your .spec file - -### Macros - -#### %terra_appstream - -`%terra_appstream{:rpmspec}` will add more sections to your `metainfo.xml`, or can generate your metainfo.xml file entirely. -You SHOULD use it when installing your own metainfo.xml file. -Review the [Terra AppStream helper README](https://github.com/terrapkg/appstream-helper/blob/main/README.md) for more. -You MAY need to add this line to your spec file: `BuildRequires: terra-appstream-helper{:rpmspec}` - -`%appid{:rpmspec}` SHOULD be defined at the top of your spec file (preamble), and used in references to the metainfo file name, for example: - -```rpmspec -%{_metainfodir}/%appid.metainfo.xml -``` - -Other components may be defined, such as `name_pretty`, `developer`, `org`, etc. - -### Installing your Metainfo File - -To properly install your metainfo file: - -```rpmspec -%global appid [your package's app ID] # This defines a macro "appid" as your package's appid. - -... - -Source1: %appid.metainfo.xml # This specifies your metainfo.xml file as a source in your spec file. - -... - -%install -... -%terra_appstream -o %{SOURCE1} # Runs the %terra_appstream macro on your metainfo.xml file. - -%files -... -%{_metainfodir}/%appid.metainfo.xml # Lists your installed metainfo.xml file to be included in the package. -``` - ---- - -## Validating Your metainfo.xml File - -To validate your `metainfo.xml` file, install `appstream`, then run `appstreamcli validate NAME.metainfo.xml`. -Errors and warnings should be corrected to the best of your ability. In rare cases, errors are fine to have, such as `E: com.github.neohtop:6: metainfo-invalid-icon-type local`. -`infos` can be ignored or corrected at your discretion. - -Here is an example of the output of running `appstreamcli validate` on a proper metainfo.xml file: - -```bash -appstreamcli validate games/minecraft-java/com.mojang.Minecraft.metainfo.xml -I: com.mojang.Minecraft:50: nonstandard-gnome-extension metadata -I: com.mojang.Minecraft:~: developer-info-missing -``` - -[^1]: libraries are also supported, see Freedesktop docs for tag provides: https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-provides - -[^2]: https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-keywords - -[^3]: https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-developer - -[^4]: https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-screenshots diff --git a/content/docs/terra/autoupdate.mdx b/content/docs/terra/autoupdate.mdx deleted file mode 100644 index 9c9e9010..00000000 --- a/content/docs/terra/autoupdate.mdx +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Automatic Updates -description: "How automatic updates can be set up for your package." ---- - -## Overview - -There have been a few evolutions regarding the ways we deal with automatic updates, with many different solutions being explored in Terra. -Despite how much our automatic package update system evolves, we still -make our best effort to document the latest way to set up automatic updates in Terra. (Seriously!) - -## Solutions - -### AndaX (Andaman Rhai scripts) - -Yes, I know it sounds unusual, but `.rhai` scripts are used to update packages in Terra. You can check out the [Rhai] documentations. -Put your Rhai script in `update.rhai` next to the corresponding `anda.hcl` file. Andaman will detect it automatically. - -```ts -// An example of AndaX update script. -let ver = gh("FyraLabs/subatomic"); // gets latest version from GitHub -rpm.version(ver); // updates the version in the spec file using `ver` -``` - -you MUST have semicolons (`;`) - -Updates are triggered every 10 minutes using `anda update{:ansi}`. - - - Actually, the [full - command](https://github.com/terrapkg/packages/blob/4767e5b9560f2986accaeb8447fbb4ea742041cf/.github/workflows/update.yml#L27-L31) - for auto-updating normal packages is: (as of 2024-08-09) ```sh - RUST_BACKTRACE=full GITHUB_TOKEN=... anda update -vv --excludes nightly=1 - --excludes updbranch=1 ``` - - -#### Nightly packages - -Nightly packages are updated every 24 hours using -`anda update -vv --filters nightly=1{:ansi}`. -Their `anda.hcl` files should look something like this: - -```hcl -project pkg { - rpm { - spec = "pkg.spec" - } - labels { - nightly = 1 - } -} -``` - -#### Per-branch auto-update scripts - -Terra supports updating a package for specific branches instead of updating a package for all branches. -This is achieved using `--filters updbranch=1 --labels branch=f41{:ansi}` (`f41` is replaced by the branch name). -The update command is run every 30 minutes. - -The `anda.hcl` file should look like this: - -```hcl -project pkg { - rpm { - spec = "pkg.spec" - } - labels { - updbranch = 1 - } -} -``` - -You can obtain the branch name during runtime in Rhai using `labels.branch` (string). - - - You MUST NOT use this feature if the script ends up bumping versions across all branches at the same time. - This feature should only be used under cases where the version is different for different branch but for the same package. - - Consequently, under normal circumstances and without approval, you are NOT allowed to use GitHub/GitLab related functions. - - -#### Weekly packages - -Weekly packages are updated every 7 days using -`anda update -vv --filters weekly=$(date "+%w"){:ansi}`. -Their `anda.hcl` files should look something like this: - -```hcl -project pkg { - rpm { - spec = "pkg.spec" - } - labels { - weekly = 0 # a random number between 0~6 inclusive - } -} -``` - -To decide the random number, just search for "_random number between 0 and 6_" with your favourite search engine. -The random number decides which day in the week will the auto-update script run. - -#### Functions and Modules - -In most cases, `rpm.version(gh("..."));{:ts}` as a one-liner is enough to make it workโ„ข. -Documentations for more functions are available in the [Andaman -devdocs](/andaman/andax#custom-functions). - -Other functions are available in the `andax/` directory after `import{:ts}`ing. - -{/* - -### HeadPAT - -[HeadPAT] is a work-in-progress package version tracker. It is (going to be) a self-hosted microservice. - -#### Planned usage - -Just like `update.rhai` scripts, a `.pat` file will be used with the following format: - -``` -ver gh FyraLabs/anda -``` - -That's it. - -However, we are exploring the posibility of adding Lua into the mix to make things more extensible: - -``` -lua -``` - -Then HeadPAT will look for `pat.lua` in the same directory. -However, it is uncertain if the above will be the actual format as HeadPAT is still under heavy (but slow) development. -*/} - -## Guidelines - - - Avoid using the{" "} - GitHub API for fetching - the latest versions. You may use GitLab, crates.io, Pypi, etc. instead. This - is because GitHub has an API rate-limit. - - - You might see scripts with `if filters.contains("nightly")`. This `if` statement is no longer needed. - -Avoid running code unrelated to updating/bumping packages. - -[rhai]: https://rhai.rs/ -[headpat]: https://github.com/terrapkg/headpat diff --git a/content/docs/terra/contributing.mdx b/content/docs/terra/contributing.mdx deleted file mode 100644 index 3d373d38..00000000 --- a/content/docs/terra/contributing.mdx +++ /dev/null @@ -1,245 +0,0 @@ ---- -title: Contributing -description: "Get started contributing packages to Terra." ---- - -## Overview - -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 by raising a [GitHub issue](https://github.com/terrapkg/packages/issues), though it might take a while. (We're busy!) - -It takes effort to create a package, and as always, there is a learning curve. -If you ever need help, hop into [our Discord server](https://fyralabs.com/discord) and we will try to help you. - - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", - "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be - interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) - and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174). - - -## Creating a package - -### Before you begin... - -- Make sure the package is not in the [Fedora repositories](https://packages.fedoraproject.org/), and the package name is not taken. -- Review our [packaging policies](./policies). -- Review our [packaging guidelines](../terra/guidelines). -- Review our custom [SRPM macros](../terra/srpm), as these may be helpful to your package. - -### Preparation - -You'll need a few tools to get started, pick one of these sections, then continue to [Writing Sources](#writing-sources). - -#### Fedora/Ultramarine - -Install [Andaman](/andaman) and its Mock configs on your system: - -`sudo dnf install terra-mock-configs{:ansi}` - -#### Dev Container - -You can create, build, and push a package all from within our Dev Container. -This means you do NOT need to be running Fedora/Ultramarine to create a package. -You can run this devcontainer from Linux, macOS, or Windows. - -1. Install the Dev Containers extension in your IDE - - Zed comes with Dev Containers, see [this documentation](https://zed.dev/docs/dev-containers) - - - VSCode users need to install the Dev Containers extension - -2. Get the container runtime - - On Windows and Mac, install [Docker Desktop](https://docs.docker.com/desktop/) - - - On Linux, install `podman-docker` from your package manager - -3. Fork [terrapkg/packages](https://github.com/terrapkg/packages), and `git clone` your fork -4. Open the folder you cloned in your editor -5. It should prompt you to `reopen in Dev Container`, click this and wait for the Dev Container to open. - - - If your editor doesn't prompt you, press `Ctrl` + `Shift` + `P`, and select - the "Reopen in Dev Container" (VSCode) or "Project: Open Remote" (Zed) option. - - -You are now in the Terra Dev Container, and have all the packages and -configuration necessary to start building packages! - -#### Pet Container - -If you're on atomic system, or otherwise prefer to work with containers, you can run the Terra build container as your development environment. - -Simply run: - -```shell -podman run --rm --cap-add=SYS_ADMIN --privileged --volume ./:/anda --volume mock_cache:/var/cache/mock --workdir /anda ghcr.io/terrapkg/builder:frawhide anda` -``` - -#### Cargo - -Anda is also available via [Cargo](https://crates.io/crates/anda). - -#### Language Support in Editors - -The most common languages you will see: - -- RPMSPEC (`.spec`), for the package build scripts -- rhai, for the auto-update scripts -- hcl, for informing `anda` of the package -- xml, for AppStream MetaInfo on some packages - -VSCode should prompt you to install these extensions, and Zed should auto-install them. -If not/using a different IDE, we suggest installing language support for each of these. - -### Writing sources - -1. Fork the [Terra sources repo](https://github.com/terrapkg/packages), and `git clone` your fork. -1. Create a folder named after the package name, for example: - - A font named `lovelyfonttype` would go in `anda/fonts/lovelyfonttype`. - - A Pantheon DE package would go in `anda/desktops/elementary/`. -1. Inside the folder, create `anda.hcl` and `.spec`. - - Note that font packages in Fedora repos should end with `-fonts`, - e.g. the folder name is `lovelyfonttype` but the spec file should be `lovelyfonttype-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](./policies). -1. Edit `anda.hcl`, which tells [Andaman] how to build the package: - - ```hcl - project pkg { # NOTE - 'pkg' is NOT referring to the package name, rather, it needs to be verbatim `pkg`. - rpm { - spec = ".spec" - } - } - ``` - -1. Edit the spec file. - - It is a custom file format for RPM packages. - - This [RPM Packaging Guide] might help newbies with no prior experiences with RPM specs. - - This [Spec file format] docs goes into the details of the spec file format. - - You may use `rust2rpm` for **Rust** packages. - - You may use `go2rpm` for **Go** packages. - - Otherwise, find the source of the packages you are adding, preferably a URL to a `.tar.gz` archive - - Multiple archives are ok. - - Archives not in `.tar.gz` format are also okay, but might require extra work. - - Archives from git repositories are preferred. - -#### Editing the Spec file - -> TIP: Check out other spec files of related packages for some examples ;) - -A generic spec file looks like this: - -```rpmspec -Name: pkgname -Version: 1.2.3 # Change this to the package's version -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: runtime deps here -# We require you to add yourself as the packager here (if this is an issue for you, let us know): -Packager: Your Name - -%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 -# This macro expands to `/usr/bin`. To see what macros expand to, you can run `rpm --eval %{MACRO}` -%{_bindir}/pkgname-binary -/path/to/more/files/*/package - -%changelog -* Wed Jan 11 2006 your-username-here -- Description on what you've done -``` - -- Add `Source0:{:rpmspec}` or `Source1:{:rpmspec}` or more. - These preambles should link to a compressed file (preferably a tarball) and will be extracted during `%prep{:rpmspec}`. - You can find this by looking at the GitHub releases page (usually a .tar.gz link). -- Add a new line `%prep{:rpmspec}` - - The source file will be automatically downloaded and - extracted with `%autosetup -n ` inside `%prep{:rpmspec}`. - - If it is not a tar archive, extract the file manually with a command. -- Inside `%build{:rpmspec}`, you might need to build the package. - Macros like `%meson{:rpmspec}` and `%cmake{:rpmspec}` are supported. - - If not, manually state the command. -- List out all the files to be included inside `%files{:rpmspec}`. - - Use `%doc{:rpmspec}` to state the README file (if it exists). - - Use `%license{:rpmspec}` 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. -- Add `%changelog{:rpmspec}` (message preferably "Initial Package"). - -## Building - -Having anda installed (or in the Dev Container) run the following command: - -```ansi -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 `sudo dnf builddep path/to/pkgname.spec{:ansi}`! - -- You don't need to create `pkg`. It's not supposed to exist, just needs to be at the end of the build command -- Modify the architecture to match your machine (`x86_64`, `i386`, `aarch64`) -- If needed (404 errors when building off `rawhide`, you can also modify the version it builds on (`43`, `42`, `el10`, etc.) -- 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(s) will be inside `anda-build/` - -## Done? - -- Review our [policies](/terra/policies) and [guidelines](/terra/guidelines) -- Git commit and push; remember you must sign your commits! -- Create a pull request that merges to the `frawhide` branch, this is equivalent to main or master - -## Automatic updates - -The system regarding automatic updates [are described here](autoupdate). Here is an overview: - -[Andaman] supports updating via `.rhai` packages. -See the "book" (more like guide) for [Rhai]. - -- Create an `update.rhai` file inside the folder of your package alongside your `.spec` file. -- See references from other packages. -- You also need to add `labels { nightly = "1" }{:hcl}` in `anda.hcl` for nightly packages. - -Remember to add semicolons in Rhai scripts! (`;`) - - Anda defaults the filename to `update.rhai`. - If it's not `update.rhai`, add a new entry inside `anda.hcl`: - ```hcl - project pkg { - rpm { - update = "path/to/update.rhai" - ... - } - } - ``` - - -[rpm packaging guide]: https://rpm-packaging-guide.github.io/ -[spec file format]: https://rpm-software-management.github.io/rpm/manual/spec.html diff --git a/content/docs/terra/faq.mdx b/content/docs/terra/faq.mdx deleted file mode 100644 index c432aaa9..00000000 --- a/content/docs/terra/faq.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: FAQ -description: "Frequently Asked Questions" ---- - -## Repo Information - -### What packages does Terra have? - -A lot! - -Some popular packages include: -- [Stardust XR](https://stardustxr.org/) components -- [Zed](https://zed.dev) -- [Ghostty](https://ghostty.org/) -- [Bazzite's](https://bazzite.gg/) offical build of Mesa, and other packages used in UBlue projects. -- [Prism Launcher](https://prismlauncher.org) -- [asusctl/ROG GUI and supergfxctl](https://gitlab.com/asus-linux/asusctl) -- Various hardware enablement tools (Chromebooks, Raspberry Pis, Arduino, Coreboot utils, etc.) - -You can search packages via `dnf search`, [pkgs.org], or [Repology]. - -### Why YET another repository? Why not RPM Fusion? Why not Copr? - -The main principles that guide Terra are: -- Ease of use, for users, maintainers, distros, and projects. - - For users, we purposely chose to host the project on a monorepo on GitHub so it's easy to discover, debug, and report issues. In general, we emphasize pragmatism when it improves the user experience. - - For maintainers, we try to lower the burden required to contribute by: - - Using common and easily accessible platforms such as GitHub. - - More lenient guidelines, such as allowing anonymous contributions, online builds, and all packages that are redistributable. - - Heavily documenting our workflow and RPM packaging in general. - - Using a custom toolchain and set of packaging helpers/macros, that extend on Fedora's. - - For distros, we provide a shared infrastructure that allows them to collaborate with other distros. - - For example, [Bazzite's](https://bazzite.gg) custom build of mesa, which is hosted on Terra, is co-maintained and used by Ultramarine Linux. - - For projects, we give an easy path to distribute their software with minimal downstream modifications, near to immediate updates, and less red tape. - - For example, Terra and [Prism Launcher](https://prismlauncher.org) have worked together in order to automatically build and distrbute nightly versions of Prism Launcher, that allows users to test new changes and discover bugs, before they hit a stable release. - - Another example is with the [Stardust XR](https://stardustxr.org) project, which was a largely collaborative effort to bring their software to end-users. -- Automation that tracks, updates, and backports packages, reducing the time between upstream release and distribution to end-users. Additionally, this reduces a significant burden for maintainers, who have lives too ;p. -- The latest and greatest, which is why Terra offers nightly, preview, and rolling-release versions of packages when needed. - -Due to our principles, our goals for Terra are different than the goals of other repositories. Here is a comparison: -- [RPM Fusion](https://rpmfusion.org/) is a great repository, but it doesn't have the level of openness and transparency we're aiming for. Additionally, Terra runs on a rolling release model, which Fusion doesn't claim to meet. - - Of course, these aspects have benefits and trade-offs, rolling release means you get the latest and greatest, but has a level of implied instability. Lowering the bar for contribution allows for more people to contribute more packages, which may be a trade-off in quality. We try to balance these aspects and find a solution we think works best. -- [Copr](https://copr.fedorainfracloud.org) is great for individuals who want to utilize Fedora infrastructure to maintain and package personal repositories. - - However, this diverges from a major aspect of Terra, which is our shared infrastructure, maintainers, and community. We belive this allows for a more consistent standard of quality and discoverability of packages. - -A much more detailed answer can be found from one of our maintainers: https://github.com/terrapkg/packages/issues/6897#issuecomment-3447981771. - -### Why do you hate Fedora? - -We don't. We maintain a good relationship with the Fedora Project, several maintainers, and other downstreams. Note that Terra does not replace Fedora, it depends on and supplements Fedora. -While we may have disagreements of principle with upstream, we still highly value and respect their work, in which Terra would not be possible without. -We do market Terra in a way that some may feel provocative, but our intent is not to denegrate the work of others, but rather differentiate ourselves as a project. - -## Technical details - -### Where is the file server? - -https://repos.fyralabs.com/terrarawhide/ - -or for sources - -https://repos.fyralabs.com/terrarawhide-source/ - -Replace `rawhide` with your Fedora version release number. - -### What is your Build Infrastructure? - -[Andaman]. x86 packages are built in [Github Actions], while ARM packages are built using a cluster of Mac Minis owned and operated by Fyra Labs. These builds are then pushed to the repo. - -### Why [Andaman]? - -Written in rust, it provides an easy and efficient way to manage packages. [Ultramarine Linux] did use Koji, but the complexity makes it harder for us to maintain packages, which is why we decided to create anda. - -Anda is responsible for handling autoupdate and building the output artifacts. It supports both `rpmbuild` and `mock`, which couldn't be done using koji. - -### What is [Subatomic]? - -It manages, uploads, and signs packages. - -### Where does the package signing key live, and how is it protected? - -[Subatomic] runs on JWT tokens, and only Cappy (one of the maintainers) and the pipeline have them. The secret changes once in a while (and no one has it). The GPG signing key lives separately from the actual repositories. - -The repo server is only accessible via HTTPS at https://repos.fyralabs.com/, and is only accessible by system administrators. - -### Who has direct access to Terra? - -See [team members of `terrapkg`](https://github.com/orgs/terrapkg/people). - -### How can I grab the SRPMs? - -https://repos.fyralabs.com/terrarawhide-source/ - -You should be able to grab them by `dnf download --source ` - -[repology]: https://repology.org/repository/terra_rawhide -[pkgs.org]: https://fedora.pkgs.org/rawhide/terra/ -[github actions]: https://github.com/terrapkg/packages/actions -[andaman]: https://github.com/FyraLabs/anda -[subatomic]: https://github.com/FyraLabs/subatomic -[ultramarine linux]: https://ultramarine-linux.org diff --git a/content/docs/terra/guidelines.mdx b/content/docs/terra/guidelines.mdx deleted file mode 100644 index fa5de370..00000000 --- a/content/docs/terra/guidelines.mdx +++ /dev/null @@ -1,559 +0,0 @@ ---- -title: Guidelines -description: "Terra-specific guidelines." ---- - -import * as Split from "../../../components/split"; - -## Overview - - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL - NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and - "OPTIONAL" in this document are to be interpreted as described in - [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) and - [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174). - - - - All macro flags followed by `<โ€ฆ>` REQUIRE an argument passed to them.
- All macro flags followed by `[โ€ฆ]` MAY have an argument passed to them.
- All macro flags with `<#>` or `[#]` take only numbers as arguments.
- Additionally, if there is no space between the flag `<โ€ฆ>`/`<#>` or `[โ€ฆ]`/`[#]`, you MUST NOT have a space between the flag and the argument passed to it.
- Conversely, if there *is* a space you SHOULD assume the flag needs a space between them. - - -Packagers and maintainers MUST follow the policies and guidelines listed in this document. -Everything covered here is one of 3 things: - -- Differences from the [Fedora Packaging Guidelines] -- Changes in addition to the [Fedora Packaging Guidelines] -- Terra-exclusive guidelines - -It is highly recommended to read through the [Fedora Packaging Guidelines] on langauges/sections not listed here, or for greater detail. - -## TL;DR - -Condensed version of guidelines. - - - REMEMBER TO [BUMP](#fixing-packages) `Release:{:rpmspec}` if propose new changes (unless pkg with current release num doesn't exist in [repos](https://repos.fyralabs.com/)) - - -No period at end of `Summary:{:rpmspec}`, but add period at end of `%description{:rpmspec}`. -[`%changelog`](/terra/guidelines#fixing-packages) only for large changes. -Prefer patching e.g. `-p1` at `%autosetup` over using `%autopatch`. -Prefer `%elifarch` over `%endif` + `%ifarch`. - -Use [`%pkg_completion`](/terra/srpm#pkg_completion) for shell completions. -Use [`%pkg_devel_files`](/terra/srpm#pkg_devel_files), [`%pkg_libs_files`](/terra/srpm#pkg_libs_files), [`%pkg_static_files`](/terra/srpm#pkg_static_files). -See [Development and Shared Libraries](/terra/guidelines#development-and-shared-libraries) section. - -Install `.desktop` file to `%_appsdir` for graphical apps. [Guide here](/terra/guidelines#providing-your-own-desktop-file). -Prefer upstream provided ones over manually generating one. -Use [`%desktop_file_install`](/terra/srpm#desktop_file_install) / [`%desktop_file_validate`](/terra/srpm/#desktop_file_validate). -See [our macros](/terra/srpm#desktop-file-macros). - -Follow Fedora guidelines for interpreted (ex. Python/Ruby) & dynamically (ex. C/++) compiled langs. -Statically compiled lang guidelines follow. - -For [Rust](#rust), use `rust2rpm`, suffix `_online` to `%cargo_prep`, `%cargo_license`, `%cargo_license_summary`; -remove `%generate_buildrequires{:rpmspec}` section. -If no flags to `%cargo_build`, remove it, -else add flags to it and replace `%cargo_install` with `%crate_install_bin`. -Also `%rustup_nightly` exists btw, [see our macros](../terra/srpm#rust). - -For [Go](#go), use `go2rpm`, rename package name to sensible one, -remove `%generate_buildrequires{:rpmspec}` section, -EITHER add `%global gomodulesmode GO111MODULE=on{:rpmspec}` OR replace `%goprep` with [`%goprep_online`](/terra/srpm#goprep_online). - -For [Nim](#nim), use one of below. Also `%nim_c` = `%nim_build`, [see our macros](/terra/srpm#nim). - - -
- ```rpmspec - %prep - %autosetup - %nim_prep - - %build - %nim_c src/dive - ``` -
-
- ```rpmspec - %prep - %autosetup -Sgit - - %build - atlas init - atlas rep atlas.lock - %nim_c src/netto - ``` -
- - -For [Zig](#zig), `BuildRequires: zig zig-rpm-macros zig-srpm-macros{:rpmspec}`. -If doesn't build with build arguments provided by Fedora `%zig_build` -(e.g. `ReleaseFast` required, microarchitectures), try [`%zig_build_target`](#zig_build_target). -Remember to try e.g. `-Dstrip=false`. If still no debug info, `%global debug_package %{nil}{:rpmspec}`. -If can't dynamically link all deps / no deps to link, `%zig_build_target` with `-s`, then `-fsys=pkgname` for things dyn-linkable. - -## Terra Packaging Guidelines - -### Usage of the `mold` Linker - -We encourage the use of [`mold`](https://github.com/rui314/mold), which can 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 SHOULD follow the 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 - -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 -These are guidelines for packaging projects written in [Rust](https://rust-lang.org). - -For the official Rust language documentation, [see here](https://rust-lang.org/learn). - -- You SHOULD add (at least!) the following build dependencies to your spec file: - - `BuildRequires: anda-srpm-macros{:rpmspec}` - - `BuildRequires: cargo-rpm-macros{:rpmspec}` - - `BuildRequires: rust-srpm-macros{:rpmspec}` -- You MAY generate the spec file using `rust2rpm`. -- You SHOULD NOT use the tradtional Fedora `%cargo_prep{:rpmspec}` macro. Instead, use `%cargo_prep_online{:rpmspec}` from `anda-srpm-macros`. Also, you SHOULD remove the `%generate_buildrequires{:rpmspec}` macro, as it is useless. -- It is RECOMMENDED to use `%cargo_license_online{:rpmspec}` and `%cargo_license_summary_online{:rpmspec}`, although they are not a strict requirement. -- You SHOULD NOT use both `%cargo_build{:rpmspec}` and `%cargo_install{:rpmspec}` 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{:rpmspec}` or `%cargo_install{:rpmspec}`. In most cases, you can just omit `%cargo_build{:rpmspec}` entirely and it will build just fine. - -Example: - -```rpmspec -%prep -%autosetup -n %{crate}-%{version} -p1 -%cargo_prep_online - -%build -%{cargo_license_online} > LICENSE.dependencies - -%install -%cargo_install -``` - -In rare cases, you may need to use `%cargo_build{:rpmspec}` and `%crate_install_bin{:rpmspec}` instead: - -```rpmspec -%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{:rpmspec}` macro to `%prep{:rpmspec}`. - -Check the [Rust section on the SRPM page](../terra/srpm#rust) for more information on these macros. - -#### Go -These are guidelines for packaging projects written in [Go](https://go.dev). - -For the official Go language documentation, [see here](https://go.dev/doc). - -- You SHOULD add (at least!) the following build dependencies to your spec file: - - `BuildRequires: go-rpm-macros{:rpmspec}` - - `BuildRequires: go-srpm-macros{:rpmspec}` -- If you use `go2rpm`, you SHOULD NOT use the default naming, as an unnecessarily long package name is bad for UX. You MAY put the name generated by `go2rpm` in the `Provides:{:rpmspec}` field. -- You SHOULD remove the `%generate_buildrequires{:rpmspec}` section, and either add `%global gomodulesmode GO111MODULE=on{:rpmspec}` OR use `%goprep_online{:rpmspec}` instead of `%goprep{:rpmspec}` in the `%prep{:rpmspec}` section. - - You SHOULD add `BuildRequires: anda-srpm-macros{:rpmspec}` to your spec if using `%goprep_online{:rpmspec}`. - -#### Nim -These are guidelines for packaging projects written in [Nim](https://nim-lang.org). - -For the official Nim language documentation, [see here](https://nim-lang.org/documentation.html). - -- You SHOULD add (at least!) the following build dependencies to your spec file: - - `BuildRequires: anda-srpm-macros{:rpmspec}` - - `BuildRequires: nim{:rpmspec}` -- You SHOULD use our [Nim macros](../terra/srpm#nim). - -In most cases, use `nimble` to download dependencies in `%prep{:rpmspec}`, -then `%build{:rpmspec}` with `nim`, e.g.[^1]: - -```rpmspec -%prep -%autosetup -%nim_prep - -%build -%nim_c src/dive - -%install -install -Dm755 src/dive -t %buildroot%_bindir -``` - -The use of the [`atlas`](https://github.com/nim-lang/atlas) package cloner is also recognized, e.g.[^2]: - -```rpmspec -%prep -%autosetup -Sgit - -%build -atlas init -atlas rep atlas.lock -%nim_c src/netto -``` - -#### Zig -These are guidelines for packaging projects written in [Zig](https://ziglang.org). - -For the official Zig language documentation, [see here](https://ziglang.org/learn). - -- You SHOULD add (at least!) the following build dependencies to your spec file: - - `BuildRequires: zig{:rpmspec}` - - `BuildRequires: zig-rpm-macros{:rpmspec}` - - `BuildRequires: zig-srpm-macros{:rpmspec}` -- When building Zig projects you SHOULD keep in mind that Zig is an optimization centric language and some projects may rely on build arguments different than what the [upstream Fedora macros](https://src.fedoraproject.org/rpms/zig/blob/rawhide/f/macros.zig) set. For example, many Zig projects rely on `ReleaseFast` (or more rarely, `ReleaseSmall`) builds for runtime optimization. Additionally, 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). -- For these reasons, you SHOULD refer to upstream guidance when packaging Zig projects. -- If any of the scenarios above apply, you MAY use `%zig_build_target` with appropriate flags instead of `%zig_build`. You however SHOULD use `%zig_build` instead if none of the above apply. - - If using `%zig_build_target`, you SHOULD add `BuildRequires: anda-srpm-macros{:rpmspec}` to your spec. - - For more information on `%zig_build_target`, please see its documentation on our [macros page](/terra/srpm#zig_build_target). - -Regardless of build macro in use, they should be used in either the `%build{:rpmspec}` or `%install{:rpmspec}` section depending on how the project is built (as some can be built directly into root by setting the `DESTDIR=%{buildroot}{:rpmspec}` variable). - -Example using `%zig_build`: -```rpmspec -%build -%{zig_build} \ - -Demit-docs -``` - -Example using `%zig_build_target`: -```rpmspec -%build -%{zig_build_target -r fast -cx86_64_v2} \ - -Demit-docs -``` - -- Note that `ReleaseFast` and especially `ReleaseSmall` 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}{:rpmspec}` 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 MAY use `%zig_build_target` with the `-s` flag. You SHOULD still dynamically link compatible dependencies by using `-fsys=pkgname{:rpmspec}`. - -### Shell Completions - -- SHOULD be a subpackage. -- SHOULD use the [`%pkg_completion` macro](../terra/srpm#pkg_completion). - -### Development and Shared Libraries - -You SHOULD try to use the [`%pkg_devel_files`, `%pkg_libs_files` and `%pkg_static_files` macros](/terra/srpm#subpackages). - -Shared library packages SHOULD be suffixed with `-libs{:rpmspec}`. -These packages SHOULD NOT contain anything **except**: - -```rpmspec -%_libdir/*.so.* -%doc โ€ฆ -%license โ€ฆ -``` - - - Do not confuse the `-libs` file (`*.so.*`) with a `-devel` file (`*.so`). - - -Development library packages SHOULD be suffixed with `-devel`. -These packages SHOULD NOT contain anything **except**: - -```rpmspec -%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.). -``` -### JavaScript -These are guidelines for packaging projects written in or which utilize [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript). - -These guidelines also often cover things written in or which utilize [TypeScript](https://www.typescriptlang.org). - -#### Node Modules -Guidelines for packaging Node modules in Terra. - - - "Node modules" in this document refers to JavaScript packages run using a JavaScript runtime (usually Node.js), which are hosted on the [NPM Registry](https://www.npmjs.com).
- "JavaScript modules," however, refers to JavaScript packages run using a JavaScript runtime which are hosted on *either* the NPM Registry or the [JavaScript Registry](https://jsr.io), the latter of which are also called "modern JavaScript packages." This means Node modules are JavaScript modules, but not the other way around.
- NPM only officially uses Node modules. You can use JSR with NPX by using `npx jsr`, but not through NPM directly. Other package managers of new enough versions support both. - - -- You SHOULD add (at least!) the following build dependencies to your spec file: - - `BuildRequires: nodejs{:rpmspec}` (OR the required Node.js version if the default in a given branch of Fedora will not work) - - If using an alternate Node.js version be prepared that you may need to patch or otherwise edit some JS executables' shebangs. - - `BuildRequires: nodejs-npm{:rpmspec}` - - `BuildRequires: nodejs-packaging{:rpmspec}` -- We package them like Arch and other distros, and allow bundled dependencies unlike Fedora. You however MAY use system dependencies instead for modules by removing the installed dependency and symlinking it to the one available in the package repos, but this is likely more work than it is worth. -- You MUST either set `%global npm_name pkgname{:rpmspec}` or use `%npm_prep -n pkgname{:rpmspec}` when packaging Node modules directly. This MUST be defined as the canonical name of the module as listed on the NPM Registry. -- You SHOULD use `%npm_license` to create the license of the bundled dependencies. -- You MAY opt instead to follow Fedora's Node.js packaging methods but keep in mind this is very difficult to maintain and may not work on all modules. - -### Web Applications -These are guidelines for building [web applications](https://en.wikipedia.org/wiki/Web_application) (hereafter referred to as "webapps"), which refers to apps built using technologies such as Electron or Tauri. - -These apps embed parts of browser functionality in order to display web content. One of the most recognizable examples is [Discord](https://discord.com). - -The general guidelines for building webapps are: -- Use our [JavaScript package manager macros](/terra/srpm#javascript-package-managers) and/or [webapp build macros](/terra/srpm#webapp-build-macros). -- Use appropriate [Electron macros](/terra/srpm#electron) for Electron apps. -- Use appropriate [Tauri macros](/terra/srpm#tauri) for Tauri apps. -- Add the correct JavaScript package manager to your build dependencies. - - Examples: - - ```rpmspec - BuildRequires: bun-bin - BuildRequires: deno - BuildRequires: pnpm - BuildRequires: yarnpkg - ``` - -#### Electron -These are guidelines for packaging [Electron](https://www.electronjs.org) apps. - - - Many Electron projects will default to building distro binary packages (such as RPMs and Debs) and this rarely works well in RPM builds. Packagers should be prepared to patch or otherwise modify the Electron Builder config to rectify this. - - -- You SHOULD add `%electronmeta` and make sure it is in the correct location in the spec file. The other macros for Electron also depend on the information in this being set. - - This meta macro automatically handles MANY common issues that can happen with Electron packages including incorrect dependencies due to bundled (or private) [shared object (`*.so`) libraries](https://en.wikipedia.org/wiki/Shared_library). - - It also pulls all basic build dependencies for Electron apps. - - Like all meta macros, must be placed carefully: - - MUST always come after `Name:{:rpmspec}` is defined and before the first `%description{:rpmspec}`. - - SHOULD come before the `License:{:rpmspec}` field if using [`%{electron_license}`](#electron_license). - - MAY be used under preambles but before `%description{:rpmspec}` if not using `%{electron_license}{:rpmspec}`. - - For more information on what all this meta macro does, please read [its section in our SRPM documentation page](/terra/srpm#electronmeta). -- You SHOULD append any additional private (bundled) libraries that the Electron app has that are picked up by RPM [AutoReqProv](http://ftp.rpm.org/max-rpm/s1-rpm-depend-auto-depend.html) to `%{__requires_excludes}` and `%{__provides_excludes}` using a `%global{:rpmspec}` similar to the below examples. - - `%global __requires_excludes %{__requires_excludes}|private_library\\.so{:rpmspec}` - - `%global __provides_excludes %{__provides_excludes}|private_library\\.so{:rpmspec}` -- You MAY use the macro `%{electron_license}` which contains the licenses for bundled Electron. You SHOULD double check any additional licenses you should list and make sure any other listed licenses are not duplicated or overlapping. - - You can double check what the macro expands to with the command `rpm --eval '%{electron_license}'{:sh}` if you have `anda-srpm-macros` installed. -- You SHOULD use our [`%electron_install` macro](/terra/srpm#electron_install) for installing Electron apps. - -#### Tauri -These are guidelines for packaging [Tauri](https://v2.tauri.app) apps. - -Tauri builds webapps using Cargo and the system WebKit. For these reasons some of the [Rust](#rust) guidelines also apply to Tauri. Most relevant Cargo macros have been ported into Tauri compatible ones, however it will likely still be helpful to make yourself familiar with the original macros. - - It is important to note that unlike the original Cargo macros, Tauri macros only support passing features with the `-f` flag due to how Tauri works. - - -- You SHOULD use one of the following in your spec: - - `BuildRequires: %{tauri_buildrequires}{:rpmspec}` - - ```rpmspec - %generate_buildrequires - %tauri_generate_buildrequires - ``` - - BuildRequires generation only works in Mock. - -- You SHOULD use `%tauri_prep{:rpmspec}` in the `%prep{:rpmspec}` section. -- You SHOULD use either a [webapp build macro](/terra/srpm#webapp-build-macros) or the [`%tauri_build` macro](/terra/srpm#tauri_build), however the latter will not work with *all* Tauri projects. See its entry on our SRPM macros page for more information. -- You SHOULD use `%{tauri_cargo_license} > LICENSE.dependencies` in your spec to package the Cargo dependency licenses. -- You MAY use the `%tauri_cargo_license_summary` and `%tauri_cargo_vendor_manifest` macros in your spec for addition license and Cargo information. -- You MAY use the [configurable macros for Tauri builds](/terra/srpm#configurable-tauri-macros) if necessary, but it should rarely be needed. - -### Miscellaneous - -#### Changelog Entries - -You MUST add a Changelog entry when you submit a new package, and you MUST NOT use `%autochangelog`. -We typically use `Initial package`/`Initial commit`, but anything that describes adding the package is fine. - -##### Changing an Existing Package - -You SHOULD add a `%changelog{:rpmspec}` entry for large changes, such as file renames, new build process, etc. -Small changes like adding build dependencies or adding one-liners to make a build work MAY be omitted from adding a `%changelog{:rpmspec}` entry, it is up to you. - -##### Copying a Spec from a Different Repository - -When copying/porting/using a spec file from a different repository (SUSE, Mandriva, RPMfusion, Copr, etc.), you MUST preserve any changelogs in the spec, and then add your own changelog entry as `Port to Terra`. -You MAY specify which repo it has been ported from. - -##### Modifying Changelog Entries - -This *should* not need to be done, the only reasons are if there was a formatting error, date error, or updated name/emails. -It is also acceptable to add more to previous changelogs (for example, adding missing emails/version), but there has to be a reason to do this. - -#### Fixing Packages - -- If a PR is changing anything user-facing, the `Release:{:rpmspec}` 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:{:rpmspec}` bump: - - Installing a missing file. - - Adding any build or non-build, hard or soft, forward or backward dependencies. - - Changing any user-facing tags (`URL:{:rpmspec}`, `License:{:rpmspec}`, `Summary:{:rpmspec}`, etc.). -- If a package fix PR is *not* fixing/changing anything build-facing, the `Release:{:rpmspec}` tag SHOULD NOT need to be bumped. - - Some (not all!) examples of changes which **don't** require a `Release:{:rpmspec}` bump: - - Fixing a package that failed to build when the `Version:{:rpmspec}` tag is bumped. - - Any changes that do not affect the final package. -- If you are unsure if a bump is needed, bump it. -- Follow appropriate changelog procedures outlined in the above section. - -#### Patches - -- Packages SHOULD apply patches (usually via the `-p#` flag) in `%autosetup{:rpmspec}`. If this is not possible (typically when `%autosetup{:rpmspec}` is not used), you SHOULD use [%autopatch](../rpm/macros#autopatch). - -#### Providing Your Own .desktop File - -If you are packaging a graphical app that doesn't provide its own `.desktop` file, you SHOULD create one. - -##### Creating the .desktop File - -Copy the following template: - -``` -[Desktop Entry] -Name=PACKAGE NAME -Exec=PROVIDED_BINARY -Icon=ICON NAME -Type=Application -``` - -The `Icon` tag SHOULD NOT a contain full path, just the name of the icon file **without** the file extension. -The `Exec` tag SHOULD be a full path if the binary placed in `/usr/bin` is a symlink. -If this is not the case, it is up to you if you want to use the full path or not (it will look in the user's `$PATH`). - -You SHOULD name this file either `package-name.desktop` or `package_app-ID.desktop`. -You MAY add more tags, to see all possible tags, read through the [freedesktop specification](https://specifications.freedesktop.org/desktop-entry/latest/). - -##### Installing the .desktop File - -To install the `.desktop` file: - -1. Add it to your package's folder -2. Add it as a `Source:{:rpmspec}` in the .spec file -3. Install it -4. List it in the `%files{:rpmspec}` section - -It is RECOMMENDED to use the [`%_appsdir` macro](/terra/srpm#_appsdir) instead of `%_datadir/applications/`, and to use the [`%desktop_file_install` macro](/terra/srpm#desktop_file_install). -With [NeoHtop package] as the example: - -```rpmspec -Source1: NeoHtop.desktop - -... - -%install -%desktop_file_install %{SOURCE1} %{buildroot}%{_appsdir}/NeoHtop.desktop - -... - -%files -... -%{_appsdir}/NeoHtop.desktop -``` - -##### Validating the .desktop File - -You MUST validate your `.desktop` file. To do this, add the following to your spec file: - -```rpmspec -BuildRequires: desktop-file-utils - -... - -%check -%desktop_file_validate %{buildroot}%{_appsdir}/NeoHtop.desktop - -... -``` - -##### Finished Example - -`NeoHtop.desktop`: - -``` -[Desktop Entry] -Categories=Utility; -Comment=A cross-platform system monitor -Exec=NeoHtop -Icon=NeoHtop -Name=NeoHtop -Terminal=false -Type=Application -``` - -All custom `.desktop` file portions of a spec file: - -```rpmspec -Source1: NeoHtop.desktop - -... - -BuildRequires: desktop-file-utils - -%install -... -%desktop_file_install %{SOURCE1} - -%check -%desktop_file_validate %{buildroot}%{_appsdir}/NeoHtop.desktop - -%files -... -%{_appsdir}/NeoHtop.desktop -``` - -#### Usage of Periods in Various Package Fields -You MUST NOT have a period at the end of any `Summary:{:rpmspec}` tags, and you SHOULD have a period at the end of all `%description{:rpmspec}`s. - -#### Usage of %elifarch - -To make specs easier to read, you SHOULD use `%ifarch{:rpmspec}` followed by `%elifarch{:rpmspec}` before `%endif{:rpmspec}` in specs where build steps are arch dependent. - - -```rpmspec -%ifarch x86_64 -%define arch %{nil} -%endif -%ifarch aarch64 -%define arch arm64- -%endif -``` - - - -```rpmspec -%ifarch x86_64 -%define arch %{nil} -%elifarch aarch64 -%define arch arm64- -%endif -``` - - ---- - -[^1]: https://github.com/terrapkg/packages/blob/e65a762352246f918d12e7c5a0e032ba0b1be73b/anda/langs/nim/dive/umdive.spec -[^2]: https://github.com/terrapkg/packages/blob/e65a762352246f918d12e7c5a0e032ba0b1be73b/anda/langs/nim/netto/netto.spec - -[Fedora Packaging Guidelines]: https://docs.fedoraproject.org/en-US/packaging-guidelines/ -[NeoHtop package]: https://github.com/terrapkg/packages/tree/frawhide/anda/apps/neohtop diff --git a/content/docs/terra/index.mdx b/content/docs/terra/index.mdx deleted file mode 100644 index b7201fc3..00000000 --- a/content/docs/terra/index.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Welcome -description: Welcome to the documentation for the Terra repository. ---- - -## Overview - -Terra is a rolling repository RPM repository for Fedora Linux and its derivatives. -With Terra, you can install the latest packages knowing that quality and security are assured. -Terra is also a great way to distribute your software on Fedora and its derivatives. - - - Installation instructions are available [here](/terra/installing). - - -- Website: https://terra.fyralabs.com/ -- GitHub: https://github.com/terrapkg/packages diff --git a/content/docs/terra/infra-graph.txt b/content/docs/terra/infra-graph.txt deleted file mode 100644 index 1979581f..00000000 --- a/content/docs/terra/infra-graph.txt +++ /dev/null @@ -1,25 +0,0 @@ -โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•— Website: https://terra.fyralabs.com/ -โ•‘ Client (dnf/dnf5) โ•‘ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ -โ•‘ โ•‘ from โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ•‘ 1. fetch metalink โ•ซโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค Tetsudou (Metalink generator) โ”‚๐Ÿญฎโ”€โ”€โ•ดrepodata hashes โ”€โ”€โ” -โ•‘ โ•‘ โ”‚ โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ•‘ โ•‘ โ”‚ GitHub: terrapkg/tetsudou โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค Subatomic (RPM delivery system) โ”‚ -โ•‘ โ•‘ โ”‚ URL: tetsudou.fyralabs.com โ”‚ repodata/ โ”‚ โ”‚ -โ•‘ โ•‘ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ SRPMs/RPMs โ”‚ GitHub: FyraLabs/subatomic โ”‚ -โ•‘ โ•‘ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ โ”‚ URL: subatomic.fyralabs.com โ”‚ -โ•‘ 2. fetch repodata โ•ซโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค (One of the many) RPM Mirrors โ”‚๐Ÿญฎโ”€โ”€โ”€โ”€โ”€โ”˜ โ”Œโ”€โ”€โ”€โ”€๐Ÿญฌโ”‚ API Docs: /docs/index.html โ”‚ -โ•‘ โ•‘ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”˜ โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ•‘ 3. download RPMs โ”€โ•ซโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ•ญโ”„โ”„ info for official mirror โ”‚ โ”‚ โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ•‘ โ•‘ โ”‚ URL: repos.fyralabs.com โ”‚ โ”‚ โ”‚ Madoguchi (Simple package query API) โ”‚ -โ•‘ (install...) โ•‘ โ”‚ Software: Caddy โ”‚ โ”‚ โ”‚ โ”‚ -โ•‘ โ•‘ โ”‚ Geo-location: DE โ”‚ โ”‚ โ”‚ GitHub: terrapkg/madoguchi โ”‚ -โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ โ”‚ โ”‚ URL: madoguchi.fyralabs.com โ”‚ -โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” upload comps โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€๐Ÿญฏโ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -โ”ƒ Monorepo for Terra Sources โ” โ”€โ”€โ”ค โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ด/SRPMs/RPMs โ”‚ โ””โ•Œโ•Œโ•Œ Repology redirect URLs -โ”ƒ โ”ƒ โ”‚ GitHub โ”œโ”€โ”€โ”€โ”€โ•ดrecord build/pkg statsโ•ถโ”€โ”€โ”€โ”˜ -โ”ƒ GitHub: terrapkg/packages โ”ƒ โ”‚ Actions โ”‚๐Ÿญฎโ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”ƒ URL: [N/A] โ” โ”€โ”€โ”ค โ”‚๐Ÿญฎโ”€โ”โ””โ”€โ•ดbuild/bump packages from specsโ•ถโ”€โ” โ”‚ AndaXย โ”‚ -โ”—โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”› โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”˜ -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ Terra CI Builder at https://github.com/terrapkg/builder โ”‚๐Ÿญฎโ”€โ”€โ”€โ”ค Andaman at https://github.com/FyraLabs/anda โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ diff --git a/content/docs/terra/infrastructure.mdx b/content/docs/terra/infrastructure.mdx deleted file mode 100644 index 5608dfd0..00000000 --- a/content/docs/terra/infrastructure.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Infrastructure -description: The technical details behind the infrastructure and how different components work together. ---- - -## How Terra Works - -This document outlines the process of how a package ends up to the end users. - -### Terra Installation - -There are two ways to install Terra: - -1. By installing the `terra-release` package (recommended). This makes sure your Terra installation - won't break even if we have any server migrations, infrastructure changes, etc. -2. With `.repo` files. We provide `.repo` files at https://github.com/terrapkg/subatomic-repos. - -This document assumes Terra is installed via the first method. You should also look at the "Last -updated on" footnote (above the next page button; a feature of Nextra that you can see on all -pages) because things might change over time. - -### Overview - -![](./terra-infra-graph.png) - -### Andaman - -Also known as `anda`, a package build toolchain in Rust, designed to simplify building various package types. - -- GitHub: https://github.com/FyraLabs/anda -- Devdocs: https://developer.fyralabs.com/andaman -- Fyra Wiki Page: https://wiki.fyralabs.com/Andaman - -Anda internally calls [Mock] and `rpmbuild` to build RPM packages. - -#### AndaX (`update.rhai`) - -A scripting language based on [Rhai](https://rhai.rs) specifically made for writing update scripts. - -- GitHub: https://github.com/FyraLabs/anda -- Devdocs: https://developer.fyralabs.com/terra/autoupdate -- Rhai playground: https://rhai.rs/playground/stable/ - -### Builder - -CI images for Terra CI operations. They are based on the Fedora minimal Docker images, with tools installed so -we don't have to install them inside CI. Basically an image with preinstalled CI tools for our specific use. - -- GitHub: https://github.com/terrapkg/builder - -### Madoguchi - -API for handling Terra-related queries, recording build failures/successes, spec location in the git repo, -and redirecting Repology links to the monorepo. - -- GitHub: https://github.com/terrapkg/madoguchi -- URL: https://madoguchi.fyralabs.com - -### Monorepo for Terra Sources - -A monorepo hosted on GitHub with all the packages sources, including `.spec` files, update scripts -(`update.rhai`s), `anda.hcl`s, etc. If you want to submit package requests, go to this repository (since it's -the main issue tracker). - -- GitHub: https://github.com/terrapkg/packages -- Devdocs: you are here - -### Subatomic - -A modern package delivery system for RPMs. It generates repodata and manages package uploads. `subatomic-cli` -is the command line tool used to upload the packages. - -- GitHub: https://github.com/FyraLabs/subatomic -- URL: https://subatomic.fyralabs.com -- API Interactive Docs: https://subatomic.fyralabs.com/docs/index.html - -### Tetsudou - -A metalink generator, so the clients (dnf/dnf5) know what mirrors a repo has and which ones are preferred. - -- GitHub: https://github.com/terrapkg/tetsudou -- URL: https://tetsudou.fyralabs.com/metalink?repo=terrarawhide - -### When CI Builds a New Package - -1. The `autobuild.yml` workflow detects for changes in commits -2. In the `manifest` stage, `anda ci` finds out what directories have been changed in the last commit -3. A matrix of jobs will run for each architecture and each package -4. GitHub Actions fetches the Terra builders -5. It runs `anda build` with the Terra mock files -6. It uploads built SRPMs and RPMs to Subatomic only if the build is successful and it's not in a pull request -7. It notifies Madoguchi for a successful/failed build - -### When dnf/dnf5 Needs a Terra Package - -1. It fetches a [metalink](https://en.wikipedia.org/wiki/Metalink) XML file from Tetsudou, which - - finds the repository's mirror information: https://github.com/terrapkg/tetsudou/tree/main/repos - - uses numerous algorithms to determine which repository will be the fastest for that client - - fetches the hashes/timestamps for the repomd.xml file, which is in the mirror generated by Subatomic -2. Client fetches repodata from a mirror -3. Client downloads RPM packages from the mirror -4. Client installs them - -[Mock]: https://rpm-software-management.github.io/mock/ diff --git a/content/docs/terra/installing.mdx b/content/docs/terra/installing.mdx deleted file mode 100644 index 52a02b90..00000000 --- a/content/docs/terra/installing.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: Installing -description: "Get access to the 1000+ packages that Fedora doesn't ship." ---- - -## Adding Terra - -### Fedora and Derivatives - -Directly install `terra-release`: - -```sh -sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release -``` - - - There is also a fancy install script: - -{" "} - - - Practice caution before running any commands on your system. - - -```sh -sh <(curl https://terra.fyralabs.com/get.sh) -``` - -If you doubt the safety of the script (which you should), curl the script to stdout first: - -```sh -curl https://terra.fyralabs.com/get.sh -``` - -Or, just don't use the fancy script. I guess. - - - -#### Ultramarine Linux - -Ultramarine comes with Terra out of the box, check your app store or just `dnf`! - -#### Nobara - -Nobara comes with Terra! Simply `dnf` away! - -#### Fedora Atomic and Derivatives - -On Atomic editions of Fedora, run the following command: - -``` -curl -fsSL https://github.com/terrapkg/subatomic-repos/raw/main/terra.repo | pkexec tee /etc/yum.repos.d/terra.repo -sudo rpm-ostree install terra-release -``` - -#### Bazzite and Aurora - -Bazzite and Aurora come with Terra, but disable it. - -Edit `/etc/yum.repos.d/terra.repo` and change `enabled=0` to `enabled=1` - -Do this again for `/etc/yum.repos.d/terra-extras.repo` - -Then you can simply `rpm-ostree` away! - -#### Bluefin - -Bluefin no longer comes with Terra, and disables package layering by default. - -To enable layering, edit `/etc/rpm-ostreed.conf` and set `LockLayering` to `false`. - - - Bluefin doesn't officially support this. If you're getting support, make sure - to mention layering is on. - - -Then follow the installation instructions for Fedora Atomic. - -### Enterprise Linux - -Terra EL contains a subset of packages for RHEL 10 and its derivatives. - -#### RHEL - -Terra EL requires EPEL, which requires CodeReady Builder, let's start by enabling that: - -```sh -sudo subscription-manager repos --enable codeready-builder-for-rhel-10-$(arch)-rpms -``` - -Then install EPEL: - -```sh -sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm -``` - -Now you can install Terra! - -```sh -sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terrael$releasever' terra-release -``` - -#### AlmaLinux, CentOS Stream, and RockyLinux - -Start by enabling CodeReady Builder: - -```sh -sudo dnf config-manager --set-enabled crb -``` - -Then install `epel-release` - -```sh -sudo dnf install epel-release -``` - -Now you can install Terra! - -```sh -sudo dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terrael$releasever' terra-release -``` - -## Subrepos - - - Subrepos are not available on Enterprise Linux. - - -Terra provides additional packages in separate repositories. These packages might conflict with RPM Fusion or the Fedora repositories. Extra care and technical knowledge may be needed. - -The current list of subrepos are `extras`, `nvidia`, `mesa`, `multimedia` (f43+ only). -They can be enabled by installing `terra-release-extras`, `terra-release-nvidia`, etc. - -### Extras - -The extras subrepo provides miscellaneous packages that conflict with Fedora. Things like patched WINE and Switcheroo control are in Extras. - -Run the following to enable `terra-extras`: - -```sh -sudo dnf install terra-release-extras -``` - -### Mesa - -The Mesa subrepo provides our build of Mesa, with patches from the [Open Gaming Collective](https://opengamingcollective.org/) and most features enabled, unlike RPMFusion and Fedora's builds. - -Run the following to enable `terra-mesa`: - -```sh -sudo dnf install terra-release-mesa -``` - -If you have `mesa-va-drivers-freeworld` installed from RPMFusion, run the following command to swap it to Terra's `mesa-va-drivers` after enabling the repo: - -```sh -sudo dnf swap mesa-va-drivers-freeworld mesa-va-drivers -``` - -### NVIDIA - -The NVIDIA subrepo provides a selection of drivers and software for NVIDIA GPUs. We offer drivers based on [Negativo17](https://negativo17.org/) builds, and CUDA packages. - -Run the following to enable `terra-nvidia`: - -```sh -sudo dnf install terra-release-nvidia -``` - -### Multimedia - -The multimedia subrepo is only available on Fedora 43 and newer. It provides multimedia codecs and related software, like `gstreamer1` packages and `ffmpeg`. - -Run the following to enable `terra-multimedia`: - -```sh -sudo dnf install terra-release-multimedia -``` - -## Using Terra - -### Install - -```sh -sudo dnf install package-name another-package -``` - -### Search - -```sh -dnf search package-name -(or) -dnf provides package-name -``` - -### Remove - -```sh -sudo dnf remove package-name another-package -``` - -### Upgrade - -```sh -sudo dnf upgrade -(or) -sudo dnf upgrade package-name another-package -``` diff --git a/content/docs/terra/lifecycle.mdx b/content/docs/terra/lifecycle.mdx deleted file mode 100644 index 67ed4cc5..00000000 --- a/content/docs/terra/lifecycle.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Lifecycle -description: "Learn more about the supported lifecycle for Terra repositories, per Fedora release." ---- - - - Terra creates a repo/branch per branched Fedora release. The version number - for these repos corresponds to the Fedora release version. - - -## Latest stable version of Fedora - -Full support. This branch is the main entrypoint for contributions and new packages. Packages are updated on a rolling release basis by Terraโ€™s autoupdate system. - -## Non-latest, but supported versions of Fedora - -We will provide updates for security issues, as tracked by Repology. Additionally we _may_ provide updates to resolve critical bugs. Besides those two cases, no new updates will be issued. No new packages may be directly submitted. It is also not guaranteed that the packages are up to date. - -## Branched Development Release - - - This branch may not exist if there is no current branched development release - of Fedora. - - -When Fedora creates a new branched development release, weโ€™ll branch off Terraโ€™s stable repository to create a development/โ€preparatoryโ€ branch. This branch will automatically pull any additional contributions from stable and acts as a working ground to get Terra ready for the new release. When Fedora promotes this branched release to stable, weโ€™ll do the same, setting this one as default. No guarantees are made for this branch during the development period. - -## Rawhide (Fedoraโ€™s rolling release) - - - You shouldn't be using this branch (or Rawhide in general) unless you know - what you're doing. - - -Similarly to branched development releases, this branch will automatically pull contributions from the current stable branch. The purpose of this branch is to allow Rawhide users (usually enthusiast/developers) to have access to the vast Terra ecosystem, in addition to acting as a canary for any issues that might impact a future stable release. No guarantees are made for this branch. - -## EOL versions of Fedora - -Completely unsupported. We will not provide any updates, even for critical security issues. While these repos might stay accessible on the internet, we reserve the right to purge them without notice. diff --git a/content/docs/terra/meta.json b/content/docs/terra/meta.json deleted file mode 100644 index 6dcbe310..00000000 --- a/content/docs/terra/meta.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "title": "Terra", - "description": "The missing community repository for Fedora", - "icon": "Earth", - "root": true -} diff --git a/content/docs/terra/policies.mdx b/content/docs/terra/policies.mdx deleted file mode 100644 index de88b95b..00000000 --- a/content/docs/terra/policies.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: Policies -description: "One of Terra's main focuses is package quality. Users should be able to install software from Terra in confidence. Our policies reflect that." ---- - - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL - NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and - "OPTIONAL" in this document are to be interpreted as described in - [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) and - [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174). - - -## TL;DR - -Condensed version of policies. - -Only [submit](/terra/policy#submission-policy) packages legally distributable, proprietary or not, but try not to PR things that are (a) already in Fedora, & (b) WIP / untested code. -Get sources into most suitable folder in repo, 1 `anda.hcl` & spec file per folder. -Otherwise PR whatever the heck you want. - -Follow upstream [version](/terra/policy#versioning) if stable; prefer `%{unreleased_version}~%{commit_date}git.%{shortcommit}` over `%{latest_stable_version}^%{commit_date}git.%{shortcommit}` otherwise. -Suffix `.nightly` / `-nightly` in name for `nightly` _[tag](/terra/policy#tags)_. Upstream Git branches can be _tag_ names. - -Only 1 number is allowed in `Release: 1%?dist{:rpmspec}` / `1%{?dist}`. -`Packager: Your name {:rpmspec}` is REQUIRED. - -If new package affects existing installs, MUST include in [subrepos](/terra/policy#subrepos). - -Ship GUI apps with [appstream metadata](/terra/appstream) and desktop file. - -- Security policy: [SECURITY.md file] -- Code of conduct: [CODE_OF_CONDUCT.md file] -- Lifecycle policy: [lifecycle page] - -End. - -## Submission Policy - -- Use common sense. -- When it comes to submissions, anything is fair game, assuming that our policies are followed. -- You MUST have the rights or permission to redistribute the packaged software. Please check the license of the software. Besides that, there is no prohibition on proprietary licenses. -- Submissions must be maintained. We will reject submissions of unmaintained software. The only exception to this SHOULD be required dependencies of modern applications. -- Submissions MUST NOT be malicious. -- Submissions SHOULD include an auto-update script (`update.rhai`). -- Submissions SHOULD be placed in the corresponding directory in `anda/`, linked [here](https://github.com/terrapkg/packages/tree/frawhide/anda). - - Each folder MUST either contain folders and no source files (other files are exempted), or contain multiple files and no folders. - - The following directories have a higher priority. Categorize your new package in the following order: - 1. `fonts/` - 2. `system/` (bootloaders, kernels, drivers, ...) - 3. `buildsys/` (software used to build other software) - 4. `devs/` (tools for software development) - 5. `games/` - 6. `themes/` - 8. `desktops/` (applications specific to a Desktop Environment) - 9. `apps/` (GUI applications) - 10. `langs/` (software written in/for a specific programming language) -- When there are ambiguous or unspecified parts in our policies/guidelines, you SHOULD refer to [Fedora's packaging guidelines]. -- Low-quality contributions will be declined at the team's discretion. -- Do not include work-in-progress code or untested patches. See [https://dont-ship.it/](https://web.archive.org/web/20250320104139/https://dont-ship.it/). - -## Maintenance Policy - -- Anyone MAY make a PR (pull request) to an already existing package. -- Unmaintained packages may be removed at any time. Before doing so, we will create a GitHub issue to gauge community interest. -- Terra will only support the latest versions of Fedora, if a package doesn't build on the next version of Fedora, we might hold it back. - -## Technical Policies for Preamble - -This section describes the guidelines for the preamble items, notably naming and versioning. - -### Tags - -"_tag_" refers to different versions of the same software, as in their release schedule/model. -For example, the `zed` package has 3 _tags_: `stable`, `preview` and `nightly`. (Some packages use `tip` instead of `nightly`.) -_Tags_ may be named after Git branches from upstream. - -Having a different _tag_ of the same software warrants a separate package, -i.e., they MUST have separate spec files with separate `Name:{:rpmspec}`s. -The _tag_ SHOULD be specified in `Name:{:rpmspec}` using the format **`%{rawname}.%{tag}`** -e.g. `ghostty.tip`, `zed.preview`, and `kf6-kio.switcheroo`. - -Packages without any _tags_ specified in `Name:{:rpmspec}` MUST be regarded as stable. - -For UX reasons, some packages MAY consider specifying `Provides: %{rawname}-%{tag}{:rpmspec}`. - -### Versioning - -{/* https://github.com/terrapkg/packages/issues/1907 */} -
- | VCS | ID | |------------------|-------| | Git | `git` | | SVN | `svn` | | - CVS | `cvs` | | Bazaar | `bzr` | | Mercurial | `hg` | | Perforce (Helix) | - `p4` | | Pijul | `pjl` | | Azure DevOps | `tfs` | | darcs | `drc` | | Fossil | - `fsl` | -
- -Packages SHOULD follow one of the version formats below: - -```rpmspec -## (Release tag tracking (stable)) -Version: %{latest_stable_version} -## (Commit tacking (nightly off version tag)) -Version: %{latest_stable_version}^%{commit_date}git.%{shortcommit} -## (Commit tacking (no stable version tag)) -Version: %{unreleased_version}~%{commit_date}git.%{shortcommit} -``` - -`git` SHOULD be replaced with the correct _VCS identifier_ for **(b)** and **(c)** as listed on the right. - -If either commit tracking option is used, you MUST also include `labels { nightly = 1 }{:hcl}` in `anda.hcl` unless there is no `update.rhai`, -as these two formats rely on the assumption that there is one `%shortcommit{:rpmspec}` for each `%commit_date{:rpmspec}` (and vice versa). - -`%unreleased_version{:rpmspec}` refers to the expected version number for the next stable (or a more stable _tag_ than `nightly{:rpmspec}`) release, -while `%latest_stable_version{:rpmspec}` refers to the current latest released version number, preferably stable. - -`Commit tacking (nightly off version tag)` SHOULD be used when there is a stable and nightly version of a package. - -If upstream does not provide a version, use `Commit tacking (no stable version tag)` and replace `%unreleased_version{:rpmspec}` as `0{:rpmspec}`. - -### Release Field - -The `Release:{:rpmspec}` preamble MUST NOT contain information regarding upstream versioning, -including but not limited to commit dates, commit hashes, software versions, _tags_, etc. -Without approval from the team, packages MUST use the format `Release: 1%?dist{:rpmspec}`. - -The release number SHOULD be incremented if changes are made to the package, unless the `Version:{:rpmspec}` changes. - -### Naming - -Prefix/Suffix the packages in the following order - -- Fonts MUST be suffixed with `-fonts`. -- Shared libraries SHOULD be suffixed with `-libs`. - - Alternatively, the `lib` prefix is also allowed, but they SHOULD still provide `-libs`. -- Development libraries SHOULD be suffixed with `-devel`. -- If necessary, suffix `-bash-completion` (or other shells) and `-doc`. -- Postfix a _tag_ if necessary (e.g. `.nightly`). - -### Packager Field - -The package maintainer of a package MUST be added to the `Packager:{:rpmspec}` preamble as follows: - -```rpmspec -Packager: Raboneko -``` - -## Subrepos - -For `f*` branches, submissions that may introduce breaking changes MUST be included in our subrepos instead via the `subrepo = "extras"` label in `anda.hcl`. -Valid subrepos include `extras`, `nvidia`, `mesa`, and `multimedia` (43 and later only). - -For example, `terra-mesa` should be in extra as the dependency solver will resolve this package for matching "provides" (such as `mesa-libEGL(x86-64)`). -`libadwaita-nightly` should be in extra since it provides `pkgconfig(libadwaita-1)`, which is required by existing packages as a build dependency. -`yt-dlp-nightly` **can be included normally** because it has no common provides with Fedora's `yt-dlp`. - -## AppStream MetaInfo & Desktop Files - -Our AppStream guidelines are documented [here](/terra/appstream). - -All graphical applications that can be started by the user MUST provide a [desktop entry](/terra/guidelines#providing-your-own-desktop-file) and [AppStream MetaInfo](https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#qsr-app-example) file. Other applications are also RECOMMENDED to do so. - -## Miscellaneous Terra Policies - -### Security Policy - -Our security policy is documented in the [SECURITY.md file]. - -### Code of Conduct - -Our code of conduct is documented in the [CODE_OF_CONDUCT.md file]. - -### Lifecycle Policy - -Our support lifecycle is documented in the [lifecycle page]. - -[Terra sources repo]: https://github.com/terrapkg/packages -[Rhai]: https://rhai.rs/book/ -[Fedora's packaging guidelines]: https://docs.fedoraproject.org/en-US/packaging-guidelines -[SECURITY.md file]: https://github.com/terrapkg/packages/blob/frawhide/SECURITY.md -[CODE_OF_CONDUCT.md file]: https://github.com/terrapkg/packages/blob/frawhide/CODE_OF_CONDUCT.md -[lifecycle page]: ../terra/lifecycle -[andaman]: https://github.com/FyraLabs/anda/ diff --git a/content/docs/terra/srpm.mdx b/content/docs/terra/srpm.mdx deleted file mode 100644 index 99706c4c..00000000 --- a/content/docs/terra/srpm.mdx +++ /dev/null @@ -1,1596 +0,0 @@ ---- -title: "SRPM Macros" -description: "Documentation on the macros included in the anda-srpm-macros package." ---- - -import { SearchTerra } from '@/components/mdx/searchterra'; - -## Overview - -We provide custom Source RPM (SRPM) macros to ease packaging and better integrate our workflow. Please use these macros when possible in Terra. - -These are provided in the `anda-srpm-macros` package. If you use them, make sure to add `anda-srpm-macros` as a `BuildRequires:{:rpmspec}` in the spec file. - -You may need to refer to the [Terra packaging guidelines](./guidelines) for non-macro related Terra guidelines. -If you're looking for documentation on our MetaInfo macros, check that out [here](./appstream). - -If you would like to contribute to these macros, check out the [SRPM macros repository](https://github.com/terrapkg/srpm-macros). - -For upstream macros available in Fedora/Terra, check out our unofficial [macros list](../rpm/macros). - - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL - NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and - "OPTIONAL" in this document are to be interpreted as described in - [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) and - [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174). - - - All macro flags followed by `<โ€ฆ>` REQUIRE an argument passed to them.
- All macro flags followed by `[โ€ฆ]` MAY have an argument passed to them.
- All macro flags with `<#>` or `[#]` take only numbers as arguments.
- Additionally, if there is no space between the flag `<โ€ฆ>`/`<#>` or `[โ€ฆ]`/`[#]`, you MUST NOT have a space between the flag and the argument passed to it.
- Conversely, if there *is* a space you SHOULD assume the flag needs a space between them. - - -## Directories -These macros define certain system directories, and SHOULD be used in place of the raw directory path. - -### %_appsdir -Expands to: `%_datadir/applications{:rpmspec}` or `/usr/share/applications{:rpmspec}` - -This may seem like a directory to place the application itself into, but this directory is used for application's `.desktop` files. - - - -### %_bun_cache_dir -The directory where Bun cache files are stored in. - -Expands to: `%{_bun_home}/install/cache{:rpmspec}` - -Used for [Bun macros](#bun). - - - -### %_bun_home -The directory where Bun files are stored in. -Unfortunately, Bun doesn't actually have a way to enforce this yet. -However the proposed environment variable is `$BUN_HOME`, so we have this for the future. - -Expands to: `%{rpmbuilddir}/.bun{:rpmspec}` - -Used for [Bun macros](#bun). - - - -### %_cargo_home -Set by our [Cargo prep macros](#rust-macros). - -We set this specifically because in online builds if the directory is manually changed as a build step (such as multi Crate repo projects), the Crates could be redownloaded during build and slow down build times. Tools like Tauri also read `.cargo` differently because they change the current working directory. - -Expands to: `%{rpmbuilddir}%{?buildsubdir:/%{buildsubdir}}/.cargo{:rpmspec}` - - - -### %_deno_dir -The directory that Deno's files and cache are stored in. - -Expands to: `%{rpmbuilddir}/.deno{:rpmspec}` - -Used for [Deno macros](#deno). - - - -### %_deno_install_root -Directory where Deno installs dependency packages. - -Expands to: `%{_deno_dir}/bin{:rpmspec}` - -Used for [Deno macros](#deno). - - - -### %_dracut_confdir -The directory where Dracut config provided by system packages should be installed to. - -Expands to: `%{_prefix}/lib/dracut/dracut.conf.d{:rpmspec}` - - - -### %elvish_completions_dir -Expands to: `%_datadir/elvish/lib/completions{:rpmspec}` - -Used in [`%pkg_completion`](#pkg_completion), or manually when `%pkg_completion` cannot be used. - - - -### %_gnomeextensionsdir -Expands to: `%{_datadir}/gnome-shell/extensions%{?uuid:/%{uuid}}{:rpmspec}` - - - - -`%{uuid}` is usually defined in gnome-shell-extension packages. if the macro is defined in your spec file (`%global uuid PKG-UUID`), it will be appended to the path upon expansion as: `%{_datadir}/gnome-shell/extensions/%{uuid}`.
-Otherwise, it will expand without `%{uuid}`, as: `%{_datadir}/gnome-shell/extensions`.
-Note that you SHOULD then need to add the extension's UUID after this macro. - - -### %_hicolordir -Expands to: `%_iconsdir/hicolor{:rpmspec}` or `/usr/share/icons/hicolor{:rpmspec}` - -The directory that SHOULD be used when installing application `.png` files. Note that you then MUST install the (typically app icon) file to the `apps` folder within the fixed-size directory in `%_hicolordir{:rpmspec}`. - -For example: - -```bash -# Lets say package 'foo' has a 16x16 and 64x64 .png -install -Dm644 icons/16x16.png %{buildroot}%{_hicolordir}/16x16/apps/%{name}.png -install -Dm644 icons/64x64.png %{buildroot}%{_hicolordir}/64x64/apps/%{name}.png -``` - -If the file is an `.svg`, use the [`%_scalableiconsdir`](#_scalableiconsdir). - - - -### %_npm_cache_dir -Expands to: `%{rpmbuilddir}/.npm{:rpmspec}` - -Used with [JavaScript package manager macros](#javascript-runtimes), especially [NPM macros](#npm). - - - -### %nushell_completions_dir -Expands to: `%_datadir/nushell/vendor/autoload{:rpmspec}` - -Used in [`%pkg_completion`](#pkg_completion), or manually when `%pkg_completion` cannot be used. - - - -### %_nvm_dir -The location in the `%{rpmbuilddir}{:rpmspec}` what will be passed to `$NVM_DIR{:rpmspec}`, which is where vendored Node.js installs and cache are stored. - -Expands to: `%{rpmbuilddir}/.nvm{:rpmspec}` - -Only used for for [`%{__nvm}`](#__nvm). - - - -### %_pkgconfigdir -Expands to: `%{_libdir}/pkgconfig{:rpmspec}` - -Used in the `%files{:rpmspec}` section. - - - -### %_pnpm_home -The directory where PNPM files and cache are stored. - -Expands to: `%{rpmbuilddir}/.pnpm{:rpmspec}` - -Used for [PNPM macros](#pnpm). - - - -### %_pnpm_store -The directory where JavaScript modules installed by PNPM usually go. This will usually not be produced when using PNPM as a build tool, but exists for rare builds it may be created in. - -Expands to: `%{_pnpm_home}/store{:rpmspec}` - -Used for [PNPM macros](#pnpm). - - - -### %rpmbuilddir -This macro exists because Terra supports EL distributions (Red Hat Enterprise Linux, Alma Linux, etc.) which currently have an RPM version from before the `%{builddir}{:rpmspec}` change to address issues [like this](https://github.com/rpm-software-management/rpm/issues/3151). - -One, albeit clunky, solution is to define `%{builddir}{:rpmspec}` manually as `%{_builddir}{:rpmspec}` in specs targeting distros with different versions of RPM where one has a version older than 4.20. We have this macro instead to make the process easier without overriding any builtin RPM macros. For more information on this solution, see [these](https://github.com/rpm-software-management/rpm/issues/3151#issuecomment-2154550735) [comments](https://github.com/rpm-software-management/rpm/issues/3151#issuecomment-2154639192) on the issue linked above. - -This macro is subject to deprecation once all EL distributions with an RPM version older than 4.20 are end-of-life (likely when EL10 is end-of-life), or in the event we can no longer support EL distributions this old. - -Expands to: `%{?builddir}%{?!builddir:%{_builddir}}{:rpmspec}` - - - -### %_rustup_home -This macro is set by `%rustup_nightly`. - -It sets a specific location for Rustup install files so the toolchain information is never potentially lost during different build steps and to keep files out of `$HOME`. - -Expands to: `%{rpmbuilddir}/.rustup{:rpmspec}` - - - -### %_scalableiconsdir -Expands to: `%_hicolordir/scalable/apps{:rpmspec}` or `/usr/share/icons/hicolor/scalable/apps{:rpmspec}` -The directory that SHOULD be used when installing application `.svg` files to. -You do not need to specify any folders for this macro, the file can be added to the end of this macro. -For example: - -```bash -install -Dm644 icons/%{name}.svg %{buildroot}%{_scalableiconsdir}/%{name}.svg -``` - -If the file is a `.png`, use [`%_hicolordir`](#_hicolordir). - - - -### %_yarn_cache_dir -The directory where Yarn cache files are stored in. - -Expands to: `%{rpmbuilddir}/.yarn{:rpmspec}` - -Used for [Yarn macros](#yarn). - - - -## Desktop File Macros -These are macros used for working with [.desktop files](https://specifications.freedesktop.org/desktop-entry/latest). - -### %__desktop_file_edit -Expands to: `/usr/bin/desktop-file-edit{:rpmspec}` -Note that this should be used only when [%desktop_file_edit](#desktop_file_edit) can not be used, and that the flags listed for `%desktop_file_edit` will not work. - - - -### %__desktop_file_install -Expands to: `/usr/bin/desktop-file-install{:rpmspec}` -Note that this should be used only when [%desktop_file_install](#desktop_file_install) can not be used, and that the flags listed for `%desktop_file_install` will not work. - - - -### %__desktop_file_validate -Expands to: `/usr/bin/desktop-file-validate{:rpmspec}` -Note that this should be used only when [%desktop_file_validate](#desktop_file_validate) can not be used, and that the flags listed for `%desktop_file_validate` will not work. - - - -### %desktop_file_edit -SHOULD be used if you for any reason need to edit a .desktop file a build has already installed. - -Available flags: -- `-f <โ€ฆ>`: MAY be used to specify the file, but is actually OPTIONAL if you list the file path after the macro and all other flags. -- `-k <โ€ฆ>`: List the "keys" to change (Exec, Icon, etc.). Comma separated for multiple keys. -- `-v <โ€ฆ>`: List the "values" to set for keys you are changing. Comma separated for multiple keys. MUST be listed in the same corresponding order the keys are listed in. -- `-u <โ€ฆ>` MAY be used to set either `%u` or `%U` in the desktop file. If using this you MUST NOT use `u` as a macro name for any reason. - - `%u{:rpmspec}` means that a desktop file can only read one URL at a time, `%U{:rpmspec}` means that it can read multiple at a time. These are what are known as [exec keys](https://specifications.freedesktop.org/desktop-entry/latest/exec-variables.html). - - Defer to what the desktop file originally contained if you are unsure which to use. - - - Keys and values MUST be listed in corresponding order.
- This means if your first key is `Exec` the first value MUST be what `Exec` should be set to. - - -Example usage: -```rpmspec -%desktop_file_edit -k Exec,Icon -v pkg,pkgicon -u %u -f /path/to/file.desktop -``` - - - -### %desktop_file_install -SHOULD be used to install a .desktop file. - -Available flags: -- `-f <โ€ฆ>`: MAY be used to specify the file, but is actually OPTIONAL if you list the file path after the macro and all other flags. -- `-k <โ€ฆ>`: List the "keys" to change (Exec, Icon, etc.). Comma separated for multiple keys. -- `-v <โ€ฆ>`: List the "values" to set for keys you are changing. Comma separated for multiple keys. MUST be listed in the same corresponding order the keys are listed in. - - Example: `%desktop_file_install -k Exec -v /usr/bin/pkg /path/to/filetoedit.desktop` -- `-u <โ€ฆ>` MAY be used to set either `%u` or `%U` in the desktop file. If using this you MUST NOT use `u` as a macro name for any reason. - - `%u{:rpmspec}` means that a desktop file can only read one URL at a time, `%U{:rpmspec}` means that it can read multiple at a time. These are what are known as [exec keys](https://specifications.freedesktop.org/desktop-entry/latest/exec-variables.html). - - Defer to what the desktop file originally contained if you are unsure which to use. - - - Keys and values MUST be listed in corresponding order.
- This means if your first key is `Exec` the first value MUST be what `Exec` should be set to. - - -Example usage: -```rpmspec -%desktop_file_install -k Exec,Icon -v pkg,pkgicon -u %u -f path/to/file.desktop -``` - - - -### %desktop_file_validate -SHOULD be used if you for any reason need to edit a .desktop file a build has already installed. - -Available flags: -- `-f <โ€ฆ>`: MAY be used to specify the file, but is actually OPTIONAL if you list the file path after the macro. - -Example usage: -```rpmspec -%desktop_file_validate -f path/to/file.desktop -``` - - - -### %update_desktop_database -A post/postun script to update the .desktop database on install/uninstall of the package. Is most likely not necessary for most things. - -Expands to: `%{__update_desktop_database} --quiet || :{:rpmspec}` - - - -## Go -These macros assist with building [Go](https://go.dev) projects. - -### %goprep_online -MAY be used to prep a Go package for online builds. Replaces `%goprep{:rpmspec}` in `%prep{:rpmspec}`. - - - -## JavaScript -These are macros to assist with the general packaging of applications that are written in JavaScript and/or use JavaScript runtimes such as Node.js or Bun. - -### Node.js -Macros for using [Node.js](https://nodejs.org). These require the use of [Fedora Node.js macros](https://docs.fedoraproject.org/en-US/packaging-guidelines/Node.js/#_macros) in the `nodejs-packaging` package. - -#### %__nvm -Calls NVM (Node Version Manager) while setting `$NVM_DIR{:bash}`. Only used if vendoring Node.js. - -Expands to: `/usr/bin/env NVM_DIR=%{_nvm_dir} /usr/bin/nvm{:rpmspec}` - - - -#### %vendor_nodejs -This macro SHOULD only be used if Node.js packages available from the repos are not usable for some reason. - -Available flags: -- `-v <โ€ฆ>` is REQUIRED for this macro to pass the version to NVM. This flag accepts a full version, the major for the latest of a major version of Node.js (e.g., `24`), or `node` to use the latest version of Node.js available. - -Usecase examples: -- Fedora has not yet packaged the correct version of Node.js or the required version is older than what is supplied. - - This means that packaged Node modules will probably not meet their runtime requirements, but Electron apps may be fine. -- EL does not yet have the correct version of Node.js. - - This poses the same concern as above. - -For this reason, whatever you are packaging SHOULD be tested locally upon a successful build to see if it has any runtime issues. - -What `%vendor_nodejs{:rpmspec}` does: -1. Installs the desired Node.js version to `%{_nvm_dir}{:rpmspec}`. -1. Redefines `%{__nodejs}{:rpmspec}` to run the vendored version through NVM. -1. Sets a `%bcond{:rpmspec}` to `vendored_nodejs{:rpmspec}` so other macros will use the vendored version. - -Vendored versions of NPM and NPX are subject to limitations in commands as they must be run through `exec`. - - - You MUST add `nvm` as a build as a `BuildRequires:{:rpmspec}` if using this macro. - - - - -### Node Modules -Macros for packaging Node modules. - -#### %npm_prep -Prepare a Node module for build steps. - -Available flags: -- `-n <โ€ฆ>` MUST be used to define `%{npm_name}{:rpmspec}` if it was not defined as a global macro. - - - -#### %fetch_node_tests -Fetch self-tests from a Git repo. MUST include all necessary test files and folders. If used, it SHOULD be placed in the `%prep{:rpmspec}` section. - -Available flags: -- `-u <โ€ฆ>` MUST be used to define the URL if the one listed in the `URL:{:rpmspec}` tag for the package is not detectable as clonable. - -All necessary test files and folders MUST be listed after the macro. Test folders MUST start with `/{:rpmspec}`. - -Example usage: -```rpmspec -%prep -%npm_prep -%fetch_node_tests -u https://github.com/dev/module.git /tests .eslintrc -``` - - - -#### %npm_install -Install a Node module to `%{npm_sitelib}{:rpmspec}` and symlink its executable. - - - This macro sets the environment variable `$_js`. This environment variable has a very simple purpose: It is defined as `.js` if a Node module's executable ends in a `.js` extension.
- How this is used: If for any reason you need to execute a Node module itself as part of the build, you SHOULD do `/path/to/%{npm_name}$_js` after using `%npm_install`. `$_js` will expand to nothing if not defined and will expand to the `.js` extension if defined. - - -Real package example: -```rpmspec -%install -%npm_install -s license-checker - -# Bootstrap the license fetching -# Environment variable is one set during execution of %%npm_install -./bin/%{npm_name}$_js --limitAttributes licenses --out LICENSE.modules -``` - - - -#### %node_self_test -Runs self-defined tests on the Node module. This is not applicable for all Node modules. Also, not all tests (that are supported as Node modules) can use a wide variety of testing tools. For use in `%check{:rpmspec}`. - -Available flags: -- `-R{:rpmspec}`: Direct duplicate of an `-R{:rpmspec}` flag. Project dependent. -- `-v{:rpmspec}`: Direct duplicate of a `-v{:rpmspec}` flag. Project dependent. - -You MUST use [`%fetch_node_tests`](#fetch_node_tests) first if using this. - - - -#### %__npm_license_checker -Expands to: `/usr/bin/license-checker` - -Runs the NPM `license-checker` command, documented [here](https://www.npmjs.com/package/license-checker-rseidelsohn). - -Example output: - -``` -/usr/bin/license-checker -โ””โ”€ @fyralabs/devdocs@@0.0.1 - โ”œโ”€ licenses: MIT - โ”œโ”€ repository: https://github.com/FyraLabs/devdocs - โ”œโ”€ publisher: Lleyton Gray - โ”œโ”€ email: lleyton@fyralabs.com - โ”œโ”€ path: /home/owen/Documents/Projects/devdocs - โ””โ”€ licenseFile: /home/owen/Documents/Projects/devdocs/LICENSE -``` - - - -#### %npm_license -Expands to: `/usr/bin/license-checker --limitAttributes licenses` - -This is similar to [`%__npm_license_checker`](#__npm_license_checker), but limits the output to only the license. - -Available flags: -- `-o <โ€ฆ>` MAY be used as a shorthand for `--out{:rpmspec}`. - -Example output: - -``` -/usr/bin/license-checker --limitAttributes licenses -โ””โ”€ @fyralabs/devdocs@@0.0.1 - โ””โ”€ licenses: MIT -``` - -SHOULD be used if packaging Node modules. - -Example usage: - -```rpmspec -%{npm_license} --out LICENSE.modules -``` - -OR: - -```rpmspec -%npm_license -o LICENSE.modules -``` - -The above would create a `LICENSE.modules` file which can then be packaged using `%license LICENSE.modules{:rpmspec}`. - - - -#### %npm_license_summary -Outputs a summary of the bundled licenses. Useful for determining what to put in the `License:{:rpmspec}` section for Node modules. - -Expands to: `%{__npm_license_checker} --summary` - - - -### JavaScript Package Managers -These are macros for working with JavaScript package managers. - - -The JavaScript package manager cache directories are placed in [`%{rpmbuilddir}`](#rpmbuilddir) because `$HOME{:bash}` can be different depending on if a build is in Mock or RPM Build. - - This is very important for consistent macro behavior as well as if the cache must be modified or deleted during build for any reason. -All macros calling the package managers also call NPM environment variables because most of them are using build dependencies from the NPM Registry, some even wrap NPM commands with their own. This ensures consistent NPM behavior. - - -#### NPM -Macros for using [NPM](https://www.npmjs.com). -It is REQUIRED to have `BuildRequires: nodejs-npm{:rpmspec}`. - -For building webapps with NPM, see [%npm_build](#npm_build). - -##### %__npm_log_level -Macro that sets the logging level for NPM. Defaults to `error` because NPM logs can fill the terminal quickly. - -If desired, it can be redefined to `silent`, `warn`, `notice`, `info`, `verbose`, or `silly`. - - - -##### %npm_common_envvars - - NPM environment variables written in uppercase will be **ignored** if the project sets different ones explicitly. This is intentional behavior which these macros do not override in order to avoid build issues. For more information, please see [this issue](https://github.com/npm/npm/issues/14528) in the original NPM GitHub repository.
- If for any reason you need to hardcode an environment override, use a flag passed to NPM or manually set the environment variable in all lowercase.
- For more information on NPM config flags and environment variables, please go [here](https://docs.npmjs.com/cli/v11/using-npm/config). - - -Expands to: `NPM_CONFIG_USERCONFIG=%{rpmbuilddir}/.npmrc NPM_CONFIG_GLOBALCONFIG=%{rpmbuilddir}/npmrc NPM_CONFIG_CACHE=%{_npm_cache_dir} NPM_CONFIG_LOGLEVEL=%{__npm_log_level} NPM_CONFIG_FUND=false NPM_CONFIG_UPDATE_NOTIFIER=false NO_UPDATE_NOTIFIER=1 NPM_CONFIG_COLOR=always NPM_CONFIG_INIT_MODULE=%{rpmbuilddir}/.npm-init.js` - -What these do: -- Forces all configuration files into the `%{rpmbuilddir}{:rpmspec}` so they are easily locatable and to prevent attempting to write to the host file system for global config. -- Sets the NPM log level to errors (previously `warn` but this included warnings irrelevant to builds or Node modules). -- Disables funding notifications as this does not make sense to display in an automated build and causes log spam. -- Disables update notifications since we are using a packaged version of NPM unless using `%vendor_nodejs{:rpmspec}`. -- Sets color to `always` for more easily readable logs. - - - -##### %npm_config_opts -Explicit NPM configuration flags of the environment variables set by the Macros. - -Expands to: `--userconfig=%{rpmbuilddir}/.npmrc --globalconfig=%{rpmbuilddir}/npmrc --cache=%{_npm_cache_dir} --loglevel=%{__npm_log_level} --fund=false --update-notifier=false --color=always --init-module=%{rpmbuilddir}/.npm-init.js{:rpmspec}` - - - -##### %__npm -Macro to call NPM with predetermined enviroment variables. - -Expands to: `/usr/bin/env %{npm_common_envvars} %{?with_vendored_nodejs:%{__nvm} exec npm --}%{!?with_vendored_nodejs:/usr/bin/npm}{:rpmspec}` - -SHOULD be used in place of calling `npm` itself. - - - -##### %__npx -Remotely run Node modules with NPX. - -Expands to: `/usr/bin/env %{npm_common_envvars} %{?with_vendored_nodejs:%{__nvm} exec npx --}%{!?with_vendored_nodejs:/usr/bin/npx}{:rpmspec}` - - - -##### %npm_audit -Audit with NPM if package uses bundled Node module dependencies. For use in the `%check{:rpmspec}` section. - -Vulnerabilities for Node modules __not bundled in the final package__ SHOULD NOT be fixed. If a vulnerability is found *only* in build dependencies, you are fine to leave it as is. - - - -##### %npm_audit_fix -Fix vulnerabilities found using `%npm_audit{:rpmspec}`. Should be used in `%prep{:rpmspec}` section. - -Installed packages with fixed dependencies SHOULD be tested first to make sure the applied fix did not cause any issues. - -Available flags: -- `-d{:rpmspec}` will run with `--dry-run{:rpmspec}` so you can check what the fix would do. -- `-f{:rpmspec}` will run with `--force{:rpmspec}`, ignoring package locks or other requirements set by the module to fix the dependencies. This MUST be tested locally and verified to not cause breakage. -- `-o <โ€ฆ>` will omit a dependency or group (such as `dev{:rpmspec}`) from being fixed. -- `-O <โ€ฆ>` will only fix a specified depency or group. -- `-p{:rpmspec}` will limit the run to the package lock. - -LIMITATION: Cannot be used on modules installed using the `-g{:rpmspec}` flag (which is done in `%npm_prep{:rpmspec}`) which use a package lock. - - - -##### %npm_test -Runs NPM tests. This will not be applicable to all projects or Node modules. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. - -Expands to: `%{__npm} test{:rpmspec}` - - - -#### Bun -Macros for using [Bun](https://bun.com). -It is REQUIRED to have `BuildRequires: bun-bin{:rpmspec}`. - -For building webapps with Bun, see [%bun_build](#bun_build). - -##### %bun_common_envvars -Sets the `$BUN_HOME{:bash}` for future use and sets the cache dir. - -Expands to: `%{npm_common_envvars} BUN_HOME=%{_bun_home} BUN_INSTALL_CACHE_DIR=%{_bun_cache_dir} BUN_RUNTIME_TRANSPILER_CACHE_PATH=%{_bun_cache_dir} FORCE_COLOR=1{:rpmspec}` - - - -##### %bun_config_opts -Explicit Bun configuration flags of the environment variables set by the Macros. - -Expands to: `--cache-dir=%{_bun_cache_dir}{:rpmspec}` - - - -##### %__bun -Expands to: `/usr/bin/env %{bun_common_envvars} /usr/bin/bun{:rpmspec}` - -SHOULD be used in place of calling `bun` itself. - - - -##### %__bunx -Run JavaScript modules (downloading them if necessary) with Bun. - -Expands to: `/usr/bin/env %{bun_common_envvars} /usr/bin/bunx{:rpmspec}` - -SHOULD be used in place of calling `bunx` or `bun x` itself. - - - -##### %bun_audit -Audit with Bun if package uses bundled JavaScript module dependencies. For use in the `%check{:rpmspec}` section. - - - `bun audit` is currently just a wrapper for NPM audit but lacks the `fix` option; use `%npm_audit_fix` to fix vulnerabilities if they are found in Node modules. - - -You SHOULD NOT need to fix vulnerabilities for JavaScript modules that are __not bundled in the final package__. This means if a vulnerability is found *only* in build dependencies, you are fine to leave them be. - - - -##### %bun_pm_trust -Add JavaScript modules to trusted dependencies so their postinstall scripts can be run. Requires arguments for dependencies to approve. SHOULD only be used if necessary. - -Available flags: -- `-a{:rpmspec}` can be used to trust all dependencies, otherwise simply list the dependencies you want to trust after the command. - -Expands to: `%{__bun} pm trust{:rpmspec}` - - - -##### %bun_test -Runs Bun tests. This will not be applicable to all projects. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. - -Expands to: `%{__bun} test{:rpmspec}` - - - -#### Deno -Macros for using [Deno](https://deno.com). -It is REQUIRED to have `BuildRequires: deno{:rpmspec}`. - -For building webapps with Deno, see [%deno_build](#deno_build). - -##### %deno_common_envvars -Sets the `$DENO_DIR{:bash}`, `$DENO_INSTALL_ROOT{:bash}`, limits `$DENO_JOBS{:bash}` to `${RPM_BUILD_NCPUS}{:bash}`, disables update notifications, and forces color. - -Expands to: `%{npm_common_envvars} DENO_DIR=%{_deno_dir} DENO_INSTALL_ROOT=%{_deno_install_root} DENO_NO_UPDATE_CHECK=1 DENO_JOBS=${RPM_BUILD_NCPUS} FORCE_COLOR=1{:rpmspec}` - - - -##### %__deno -Expands to: `/usr/bin/env %{deno_common_envvars} /usr/bin/deno{:rpmspec}` - -SHOULD be used in place of calling `deno` itself. - - - -##### %__dx -Call modules directly with DX/Deno X. - -Expands to: `/usr/bin/env %{deno_common_envvars} /usr/bin/dx{:rpmspec}` - -SHOULD be used in place of calling `dx` or `deno x` itself. - - - -##### %deno_audit -Audit with Deno if package uses bundled JavaScript module dependencies. For use in the `%check{:rpmspec}` section. - -Expands to: `NPM_CONFIG_AUDIT_LEVEL=low %{__deno} audit --level=low --ignore-unfixable --socket{:rpmspec}` - - - `deno audit` currently lacks a way to fix vulnerabilities; use you MAY try using `%npm_audit_fix` to fix vulnerabilities. - - - - -##### %deno_approve_scripts -Approve dependency scripts with Deno if needed. Requires arguments for dependencies to approve. SHOULD only be used if necessary. - -Available flags: -- `-l{:rpmspec}` will limit approval to only dependencies found in the package lock. - -Expands to: `%{__deno} approve-scripts{:rpmspec}` - - - -##### %deno_test -Runs Deno tests. This will not be applicable to all projects. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. - -Expands to: `%{__deno} test --parallel{:rpmspec}` - - - -#### PNPM -Macros for using [PNPM](https://pnpm.io). -It is REQUIRED to have `BuildRequires: pnpm{:rpmspec}`. - -For building webapps with PNPM, see [%pnpm_build](#pnpm_build). - -##### %pnpm_common_envvars -Sets the NPM environment variables and the PNPM home directory. - -Expands to: `%{npm_common_envvars} PNPM_HOME=%{_pnpm_home}{:rpmspec}` - - - -##### %__pnpm -Expands to: `/usr/bin/env %{pnpm_common_envvars} %{?with_vendored_pnpm:%{_pnpm_home}/pnpm}%{!?with_vendored_pnpm:/usr/bin/pnpm}{:rpmspec}` - -SHOULD be used in place of calling `pnpm` itself. - - - -##### %__pnpx -Remotely execute JavaScript modules using PNPX. - -Expands to: `/usr/bin/env %{pnpm_common_envvars} /usr/bin/pnpx{:rpmspec}` - -SHOULD be used in place of calling `pnpx` or `pnpm dlx` itself. - - - -##### %vendor_pnpm -This SHOULD only be used if PNPM is not usable/available from the available repositories. - -Available flags: -- `-v <โ€ฆ>` MAY be used to define a desired version of PNPM. - -Usecase examples: -- Fedora's currently packaged PNPM is too old for the build. -- You want to make the package build on EL (does not have PNPM). - - In this case, you SHOULD wrap `%vendor_pnpm{:rpmspec}` in `%if{:rpmspec}` macros such as: - - ```rpmspec - %if %{defined rhel} - %vendor_pnpm - %endif - ``` - - - -##### %pnpm_audit -Audit with PNPM if the package uses bundled JavaScript module dependencies. For use in the `%check{:rpmspec}` section. - -You SHOULD NOT need to fix vulnerabilities for JavaScript modules that are __not bundled in the final package__. This means if a vulnerability is found *only* in build dependencies, you are fine to leave them be. - - - -##### %pnpm_audit_fix -Fix security issues in dependencies using PNPM. - -Expands to: `NPM_CONFIG_AUDIT_LEVEL=low %{__pnpm} audit{:rpmspec}` - - - -##### %pnpm_approve_builds -Approve dependency scripts with PNPM if needed. Requires arguments for dependencies to approve. SHOULD only be used if necessary. - -Available flags: -- `-g{:rpmspec}` can be used to trust depdendencies of globally installed packages. - -Expands to: `%{__pnpm} approve-builds{:rpmspec}` - - - -##### %pnpm_test -Runs PNPM tests. This will not be applicable to all JavaScript modules. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. - -Expands to: `%{__pnpm} test{:rpmspec}` - - - -#### Yarn Macros -Macros for using [Yarn (Yarn Classic/Yarn v1)](https://classic.yarnpkg.com) and [Yarn Berry (Yarn Modern/Yarn v2+)](https://yarnpkg.com). - -You SHOULD use `BuildRequires: yarnpkg{:rpmspec}` (Yarn Classic) unless you need `BuildRequires: yarnpkg-berry{:rpmspec}` (Yarn Berry) specifically. - -For building webapps with Yarn, see [%yarn_build](#yarn_build). - -##### %yarn_common_envvars -Sets the NPM evironment variables and Yarn's cache folder. - -Expands to: `%{npm_common_envvars} YARN_CACHE_FOLDER=%{_yarn_cache_dir}{:rpmspec}` - - - -##### %yarn_config_opts -Explicit Yarn configuration flags of the environment variables set by the Macros. - -Expands to: `--cache-folder=%{_yarn_cache_dir}{:rpmspec}` - - - -##### %__yarn -Expands to: `/usr/bin/env %{yarn_common_envvars} /usr/bin/yarn{:rpmspec}` - -SHOULD be used in place of calling `yarn` itself. - - - -##### %__yarn_dlx -Remotely execute a JavaScript module with Yarn DLX. - -Expands to: `/usr/bin/env %{yarn_common_envvars} /usr/bin/yarn dlx{:rpmspec}` - -SHOULD be used in place of calling `yarn dlx` itself. - - - `yarnpkg-berry` is REQUIRED as a build dependency instead of `yarnpkg`. - - - - -##### %yarn_audit -Audit Yarn if the package uses bundled JavaScript module dependencies. For use in the `%check{:rpmspec}` section. - -You SHOULD NOT need to fix vulnerabilities for JavaScript modules that are __not bundled in the final package__. This means if a vulnerability is found *only* in build dependencies, you are fine to leave them be. - - - -##### %yarn_test -Runs Yarn tests. This will not be applicable to all projects. For use in the `%check{:rpmspec}` section. For some projects it may be necessary to export `NODE_ENV=test` first. - -Expands to: `%{__yarn} test{:rpmspec}` - - - -### Webapp Macros -Macros for building [webapps](https://en.wikipedia.org/wiki/Web_application). - -#### Electron -These macros assist with the general packaging of applications that use [Electron](https://www.electronjs.org). - -##### %electronmeta -Set up all basic requirements including build macros for building an Electron app. - - - This does NOT install the JavaScript package managers used for builds except for NPM (e.g., `bun`, `deno`, `pnpm`, `yarnpkg`, `yarnpkg-berry`).
- Specify these `BuildRequires:{:rpmspec}` manually. - - -Available flags: -- `-a{:rpmspec}` will pull in additional build dependencies often needed particularly when building with NPM. - - Currently, this includes `nodejs-devel`, `nodejs-packaging`, and `typescript`. -- `-D{:rpmspec}` will disable debuginfo package creation. This is necessary for many Electron apps as the bundled libraries often do not contain enough to strip, meaning this step in the build will fail. SHOULD only be used if debug packages cannot be created. - -Rundown of what all `%electronmeta{:rpmspec}` does: -- Converts `%_target_cpu{:rpmspec}` (the RPM build architecture) into `%_electron_cpu{:rpmspec}`, the Electron format for compatible architectures. See the table below for conversions. See also: [%electron_arches](#electron_arches) - - These are defined because Electron names the build files and directories after the architecture. - - The [macros used to build Electron apps](#webapp-build-macros) all require this to be set. - - In some cases, these architectures are used in the source tarballs for Electron projects. - - This can also be used to help work with the files if you need to do anything manually. -- Defines `%__provides_excludes{:rpmspec}` to make sure Electron apps are not flagged as providers of their bundled dependencies, such as FFmpeg libraries. -- Defines `%__requires_excludes{:rpmspec}` based on architecture to prevent Electron projects' cross-platform builds from causing false dependency positives from RPM. -- If using the `-D` boolean, sets `%debug_package{:rpmspec}` to `%{nil}{:rpmspec}` to prevent stripping of bundled libraries and/or build failures due to not enough data to strip. -- Sets the build and runtime dependencies. -- Sets the `ExclusiveArch:{:rpmspec}` tag to only the architectures Electron supports. -- Defines a `%bcond{:rpmspec}` for whether or not Electron is bundled for other macros. -- Defines the bundled dependencies as bundled. - - This only defines Electron's bundled dependencies, not any JavaScript modules the app may also bundle. - - -
- | `%_target_cpu` | `%_electron_cpu` | - |:-------------------------------:|:----------------:| - | `%{x86_64}`[^1] | `x64` | - | `%{arm64}` (`aarch64`) | `arm64` | - | `%{ix86}`[^2] | `ia32` | - | `armv7l`, `armv7hl`, `armv7hnl` | `armv7l` | - | `%{mips64}` | `mips64el` | -
- -This ensures packagers don't need to manually set these for every Electron app's spec, hopefully eliminating depsolver problems and helping reduce common build issues. - -Like other meta macros (e.g., `%forgemeta{:rpmspec}` from Fedora), you MUST be mindful of where in the spec this macro should be placed. -- MUST always come after `Name:{:rpmspec}` is defined and before the `%description{:rpmspec}` section. -- SHOULD come before the `License:{:rpmspec}` field if using [`%{electron_license}`](#electron_license). -- MAY be used under preambles but before `%description{:rpmspec}` if not using `%{electron_license}{:rpmspec}`. - -The safest location is under `Name:{:rpmspec}` and above other preambles. When in doubt, place the macro here. - - - `%__provides_exclude` and `%__requires_exclude` can be recursively added to if needed by defining the macro again as a `%global` and appending the needed exclusions using [regex](https://wikipedia.org/wiki/Regular_expression).
- Example: `%global __provides_exclude %{__provides_exclude}|libcurl\\.so`
- MUST be done after setting `%electronmeta`.
- You SHOULD double check [the notes for regex in macros](/rpm/macro#escaping-regex-in-rpm-macros) on our macro syntax page for more information as RPM has some notable quirks with regex. - - -Example usage: -```rpmspec -Name: electron -%electronmeta -Version: 39.2.7 -``` - - - -##### %electron_arches -The architectures Electron supports. Automatically set as `ExclusiveArch:{:rpmspec}` when using `%electronmeta{:rpmspec}`. - -As written, the macro expands to: -- `%{x86_64} %{ix86} %{arm64} armv7l armv7hl armv7hnl %{mips64}` - -Which expands fully to: -- `x86_64 x86_64_v2 x86_64_v3 x86_64_v4 amd64 em64t i386 i486 i586 i686 pentium3 pentium4 athlon geode aarch64 armv7l armv7hl armv7hnl mips64 mips64el mips64r6 mips64r6el` - -Which simply means Electron supports [x86_64](https://en.wikipedia.org/wiki/X86-64), [32-bit x86 (AKA: IA-32)](https://en.wikipedia.org/wiki/IA-32), [AArch64/ARM64](https://en.wikipedia.org/wiki/AArch64), [ARMv7 (AKA: `armhf`)](https://en.wikipedia.org/wiki/ARM_architecture_family#Architecture_versions), and [MIPS64](https://en.wikipedia.org/wiki/MIPS_architecture). - -However, at this time, Terra only supports x86_64, AArch64, and 32-bit x86. - - - -##### %electron_license -The license for bundled Electron. -NOT set by default in `%electronmeta{:rpmspec}` because you cannot set the license field twice. -MAY be used in combination with manually adding the other relevant licenses (if this is done, a proper license tag would be `License: XXX-x.x AND %{electron_license}{:rpmspec}`). - -[`%electronmeta`](#electronmeta) SHOULD be used BEFORE the `License:{:rpmspec}` preamble but AFTER `Name:{:rpmspec}` if using this macro. - - - -##### %electron_install -Install files of apps built using Electron Builder or Electron Forge. MUST be used after an appropriate [build macro](#webapp-build-macros). - -Capital letter flags denote use with [desktop file](https://specifications.freedesktop.org/desktop-entry/latest) installation. - -By default, the install steps are: -1. Make the install directory. - - This will be in the `%{_libdir}{:rpmspec}` (/usr/lib on 32-bit architectures and /usr/lib64 on 64-bit ones). - - This is done because programs with bundled dependencies (Electron, JavaScript modules, and more) MUST have these dependencies kept together. -2. Install the app's files. -3. Symlink the app's binary to the bin directory. -4. Install the app's icons. - -Available flags: -- `-b <โ€ฆ>` MUST be used when the app's executable differs from the name of the package. -- `-d <โ€ฆ>` MAY be used to install the app under a different directory than the name of the package. -- `-i <โ€ฆ>` MUST be used when the app's desktop file points to an icon name different from the name of the package. -- `-I [โ€ฆ]` MAY be used to handle automatic icon installation. It can be used to point to either the folder icons are in and the icon files themselves. You MUST include the file extension if pointing it to the icon files, otherwise it will assume you are pointing it to a directory. -- `-l{:rpmspec}` MAY be used to fetch all licenses including the bundled ones and put them in a directory called `bundled_licenses`. You SHOULD then package them in the license directory using `%license bundled_licenses/*` in the `%files` section. - - If using this you MUST make sure there are no duplicate license names. For example, if the main application's license file is `LICENSE`, but one of its bundled license files is *also* `LICENSE`, you SHOULD rename the bundled license to an appropriate name indicating it is the license for a bundled dependency. - - An appropriate name would be something like `LICENSE.bundleddepname` or `bundleddepname.LICENSE`. Usually, the former is used, but you MAY use either format. - - This MUST be done because if there are two different files with the same name, the `cp` command used in the `%license` macro for the files section will either fail or overwrite the main software's license, which is not admissible for redistribution. -- `-s <โ€ฆ>` MAY be used to choose the name of the symlink. -- `-S <โ€ฆ>` MAY be used to create an additional symlink with a different name. Useful when an app has two interchangeable common names. -- `-D{:rpmspec}` MAY be used to handle automatic installation of the .desktop file. This ONLY works if Electron Builder builds an AppImage, and should not be used if the source contains a desktop file. -- `-E <โ€ฆ>` MAY be used to set the "--enable-features" flag in the desktop file. Features to enable MUST be comma separated without spaces. -- `-O[โ€ฆ]` MAY be used to set the [Ozone platform](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/ozone_overview.md) the Electron app will run on. If no arguments are supplied, it will fall back to `--ozone-platform-hint=auto`. Accepted arguments are `-Ox11` and `-Owayland` -- `-U <โ€ฆ>` MAY be used to set either `%u` or `%U` in the desktop file. If using this you MUST NOT use `u` as a macro name for any reason. - - `%u{:rpmspec}` means that a desktop file can only read one URL at a time, `%U{:rpmspec}` means that it can read multiple at a time. These are what are known as [exec keys](https://specifications.freedesktop.org/desktop-entry/latest/exec-variables.html). - - Defer to what the desktop file originally contained if you are unsure which to use. - -Example usage: -- The command `%electron_install -b app -i app -s app -S alsoapp -D -Owayland -U %u -E WaylandWindowDecorations` would install the program with: - - Icons named `app.png`. - - A symlink named `app`. - - A second symlink called `alsoapp`. - - A desktop file with the `Exec` line reading `Exec=/usr/lib(64)/pkgname/app --enable-features=WaylandWindowDecorations --ozone-platform=wayland %u`. - - - Like the webapp build macros, this macro sets the environment variable `$WEBAPP_BUILD_TOOL` to either `electron-builder` or `electron-forge` depending on which the app is built with. SHOULD NOT need to be used manually, but MAY be if needed for any reason. - - - - -#### Tauri -Macros for using [Tauri](https://v2.tauri.app). - -Tauri apps always require JavaScript package managers AND Cargo, so for this reason the [Rust macros](#rust) are also relevant. - - - Take notice of the section [System Tauri](#system-tauri)'s description. Those are macros for using Tauri *installed via the repository,* AKA installed to the system.
- You probably are *not* looking for these by default, especially because there are many cases that system Tauri may not match the version needed by a project.
- You are welcome to try them, but if you hit a version mismatch (unless it is a bug, such as noted [here](#__tauri_ignore_version_mismatches)), use the [webapp build macros](#webapp-build-macros) instead.
- TL;DR: Use [system Tauri macros](#system-tauri) for Cargo Tauri installed from the repository, use [webapp build macros](#webapp-build-macros) for JavaSript Tauri installed as a JS module dependency, and note that the latter will fit most usecases. - - -##### %tauri_buildrequires -MAY be used in a spec by setting `BuildRequires: %{tauri_buildrequires}{:rpmspec}` - -Available flags: -- `-a{:rpmspec}`: Additional BuildRequires that may be needed for some projects. - - Currently, this includes `nodejs-devel`, `nodejs-packaging`, and `typescript`. - - This would be used as `BuildRequires: %{tauri_buildrequires -a}{:rpmspec}`. -- `-t{:rpmspec}`: Pull Tauri itself from the repos. - - This would be used as `BuildRequires: %{tauri_buildrequires -t}{:rpmspec}` - - - This does NOT install the JavaScript package managers used for builds except for NPM (e.g., `bun`, `deno`, `pnpm`, `yarnpkg`, `yarnpkg-berry`).
- Specify these `BuildRequires:{:rpmspec}` manually. - - - - -##### %tauri_prep -Preps a Tauri package. Wrapper for `%cargo_prep_online` that checks that the Tauri subdirectory is correct. - -Available flags: -- `-n <โ€ฆ>`: The name of the subdirectory to `cd` into before running `%cargo_prep_online`. This value is also used when setting a macro used in other Tauri macros. If this flag is not passed, the macro will default to the most common name used for this subdirectory which is `src-tauri`. - - - -##### %tauri_install -MAY be used to install a built Tauri package. A port of `%cargo_install`. - -Available flags: -- `-f <โ€ฆ>`: Should be the same as the features that were passed to the Tauri build. Used for installing the Cargo development files. - - - -##### %tauri_install_bin -A wrapper around [`%crate_install_bin`](#crate_install_bin) for Tauri. - - - -##### %tauri_cargo_license -A port of `%cargo_license_online` that points to the Tauri app's Cargo.toml. - -Available flags: -- `-f <โ€ฆ>`: Should be the same as the features that were passed to the Tauri build. - - - Cargo license macros MUST be wrapped in `{}` when being used to write a license file. - - - - -##### %tauri_cargo_license_summary -A port of `%cargo_license_summary_online` that points to the Tauri app's Cargo.toml. - -Available flags: -- `-f <โ€ฆ>`: Should be the same as the features that were passed to the Tauri build. - - - -##### %tauri_cargo_vendor_manifest -A port of `%cargo_vendor_manifest_online` that points to the Tauri app's Cargo.toml. - - - -##### %tauri_generate_buildrequires -Generates `BuildRequires:{:rpmspec}` for a Tauri build. - -Supports the same flags as [%tauri_buildrequires](#tauri_buildrequires). - - - `BuildRequires:{:rpmspec}` generation only works in Mock. - - - This does NOT install the JavaScript package managers used for builds except for NPM (e.g., `bun`, `deno`, `pnpm`, `yarnpkg`, `yarnpkg-berry`).
- Specify these `BuildRequires:{:rpmspec}` manually. - - - - -#### Configurable Tauri Macros - -##### %__tauri_bundles -By default, all macros which call Tauri do not build bundles. Set `%global __tauri_bundles` to the bundle(s) you want to change this. - -This may be useful for, for example, building an AppImage to extract a .desktop file from. - - - -##### %__tauri_ignore_version_mismatches -This macro disables Tauri version mismatch checking. It can be set to anything. - - - Use of this macro is **heavily discouraged.** The option to ignore version mismatches only exists in Tauri, and is only enableable with this macro, because Tauri may detect a version mismatch incorrectly in some situations. You SHOULD NOT use this to force a system Tauri build with an incorrect Tauri version. - - - - -#### System Tauri -These are macros for use with Tauri if installed from the repo. Please note that using Tauri from the repo MAY NOT WORK with all projects unless you override version checking, which is not advisable in most circumstances. - -##### %__tauri -Calls Tauri while setting the Fedora Cargo environment variables. - -Expands to: `/usr/bin/env CARGO_HOME=%{_cargo_home}%{!?with_rust_nightly: RUSTC_BOOTSTRAP=1}%{?with_rust_nightly: RUSTUP_HOME=%{_rustup_home}} RUSTFLAGS='%{build_rustflags}' /usr/bin/tauri` - - - -##### %tauri_build -Build with system Tauri. - -Available flags: -- `-f <โ€ฆ>`: Features to enable in Tauri and Cargo. Comma separated. - - - -##### %tauri_build_crate -A port of [%cargo_build_crate](https://codeberg.org/rust2rpm/cargo-rpm-macros/src/commit/754ec0c9a09d8a89990f454c17dc0da07861741f/macros.d/macros.cargo#L280) for Tauri. - -Available flags: -- `-f <โ€ฆ>`: Features to enable in Tauri and Cargo. Comma separated. - - - -#### Webapp Build Macros -These are macros used to build webapps using JavaScript package managers and builders such as [Electron Builder](https://www.electron.build), [Electron Forge](https://www.electronforge.io), [Electron Vite](https://electron-vite.github.io), or [Tauri](#tauri). - -Capital letter flags generally denote options that SHOULD be used with caution or only if necessary for a build. - -For more information on each package manager, seethe [NPM macros](#npm), [Bun macros](#bun), [Deno macros](#deno), [PNPM macros](#pnpm), and [Yarn macros](#yarn). - - - All of the following macros set the environment variable `$WEBAPP_BUILD_TOOL` to `electron-builder`, `electron-forge`, or `tauri` depending on which the app is built with. SHOULD NOT need to be used manually, but MAY be if needed for any reason. - - - All webapp build macros run the `install` (or `ci` for applicable package managers) step for dependencies as part of their build process, this is never manually required when using them *unless* some other step in the build process prior to the build step requires the dependencies to be installed first. - - -##### %npm_build -SHOULD be used for building Electron or Tauri apps with NPM. Has a great deal of flags to work around NPM specific limitations. - -Available flags: -- `-c{:rpmspec}`: Run `%{__npm} ci{:rpmspec}` instead of `%{__npm} install{:rpmspec}`. May be necessary for projects with stricter build dependencies. -- `-e <โ€ฆ>`: Execute commands and modules within the NPM build environment. Some commands may need `--` in between the command itself and the following arguments. Can accept multiple arguments if they are separated using standard shell separators (`;` and `&&`). -- `-f <โ€ฆ>`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. -- `-r <โ€ฆ>`: Executes `%{__npm} run{:rpmspec}` for scripts in the `package.json`. Can run multiple scripts if they are comma separated. -- `-B{:rpmspec}`: Execute the webapp builder (Electron Builder, Electron Forge, or Tauri) directly. Will NOT work for projects that require build steps which use Node.js or executing JavaScript scripts directly. -- `-C <โ€ฆ>`: Point NPM to the build config file if it cannot automatically detect it. -- `-M <โ€ฆ>`: Mode to use in Electron Vite builds. Accepts `production`, `development`, and `staging`. Note that this differs from `$NODE_ENV` so you can run any combination of Vite environment modes and Node.js environment modes. -- `-V{:rpmspec}`: Execute Electron Vite. Same limitation as with `-B{:rpmspec}`. - -Example usage: -```rpmspec -%build -%npm_build -r script,script2 -e %{__nodejs} tasks/task1.js && %{__nodejs} tasks/tasks2.js -B -``` - -The above would run the necessary install steps, run script and script2, execute Node.js to run task1.js and task2.js, then call the build tool. - - - -##### %bun_build -SHOULD be used to build Electron or Tauri apps with Bun. - -Available flags: -- `-c{:rpmspec}`: Run `%{__bun} ci{:rpmspec}` instead of `%{__bun} install{:rpmspec}`. Analogous to `%{__bun} install --frozen-lockfile{:rpmspec}`. May be necessary for projects with stricter build dependencies. -- `-e <โ€ฆ>`: Execute commands and modules within the Bun build environment. Can accept multiple arguments if they are separated using standard shell separators (`;` and `&&`). -- `-f <โ€ฆ>`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. -- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. -- `-r <โ€ฆ>`: Executes `%{__bun} run{:rpmspec}` for scripts in the `package.json`. Can accept multiple arguments if they are comma separated. -- `-F{:rpmspec}`: Runs `--force{:rpmspec}` on the `%{__bun} install{:rpmspec}` step. This will assure all dependencies are the latest versions from the registry, reinstalling them if necessary. -- `-N{:rpmspec}`: Runs `--no-save{:rpmspec}` on the `%{__bun} install{:rpmspec}` step. This prevents updating or (re)creating a lockfile to prevent freezing. -- `-R{:rpmspec}`: Remove the bun.lock file. SHOULD only be used if the lockfile is causing build issues or upstream builds without a lock file. Built apps using this MUST be carefully tested for problems. - -Example usage: -```rpmspec -%build -%bun_build -c -r script,script2 -e ng build && echo "Done." -``` - -The above would run `%{__bun} ci`, run script and script2, the JavaScript module executable `ng` to build with, call echo, then call the build tool. - - - -##### %deno_build -SHOULD be used to build Electron or Tauri apps with Deno. - -Available flags: -- `-f <โ€ฆ>`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. -- `-t <โ€ฆ>`: Executes `%{__deno} task{:rpmspec}` for scripts in the `package.json`. Can accept multiple arguments if they are comma separated. -- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. -- `-r <โ€ฆ>`: Executes files with `%{__deno} run{:rpmspec}`. Can accept multiple arguments if they are comma separated. -- `-x <โ€ฆ>`: Execute commands and modules within the Deno build environment. Can accept multiple arguments if they are separated using standard shell separators (`;` and `&&`). -- `-F{:rpmspec}`: Runs `--force{:rpmspec}` on the `%{__deno} install{:rpmspec}` step. This will overwite the existing dependency installation (if any exists). -- `-N{:rpmspec}`: Runs `--no-lock{:rpmspec}` on the `%{__deno} install{:rpmspec}` step. This prevents updating or (re)creating a lockfile to prevent freezing. - -Example usage: -```rpmspec -%build -%deno_build -t script,script2 -r file1.js,file2.js -``` - -The above would run run script and script2, then run file1.js and file2.js with Deno before running the build tool. - - - -##### %pnpm_build -SHOULD be used for building Electron or Tauri apps with PNPM. - -Available flags: -- `-e <โ€ฆ>`: Execute JavaScript modules or installed programs in the PNPM build environment. Can accept multiple arguments if they are separated using standard shell separators (`;` and `&&`). -- `-f <โ€ฆ>`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. -- `-r <โ€ฆ>`: Executes `%{__pnpm} run{:rpmspec}` for scripts in the `package.json{:rpmspec}`. Not recommended for Electron Builder/Electron Forge or Electron Vite commands. Can accept multiple arguments if they are comma separated. -- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. -- `-F{:rpmspec}`: Executes the `%{__pnpm} install{:rpmspec}` step with `--frozen-lockfile{:rpmspec}`. May be necessary for projects expecting very strict build dependencies, but can also override projects that do not enforce a lock. -- `-N{:rpmspec}`: Executes the `%{__pnpm} install{:rpmspec}` step with `--no-frozen-lockfile{:rpmspec}`. Overrides projects that try to enforce a lockfile. -- `-R{:rpmspec}`: Makes `%{__pnpm} exec{:rpmspec}` run on every project in the worspace recursively. SHOULD be used only if necessary and with caution. - -Example usage: -```rpmspec -%build -%pnpm_build -N -v -r script,script2 -``` - -The above would run `%{__pnpm} install --no-frozen-lockfile`, run script and script2, then call Electron Vite before the build tool. - - - -##### %yarn_build -SHOULD be used to build Electron or Tauri apps with Yarn or Yarn Berry. - -Available flags: -- `-e <โ€ฆ>`: Execute JavaScript modules or installed programs in the Yarn build environment. -- `-f <โ€ฆ>`: This option is only for Tauri projects. Features to pass to Tauri/Cargo. Features should be comma separated. -- `-r <โ€ฆ>`: Executes `%{__yarn} run{:rpmspec}` for scripts in the `package.json`. Not recommended for Electron Builder, Electron Forge, or Electron Vite commands. Can accept multiple arguments if they are comma separated. -- `-v{:rpmspec}`: Run Electron Vite build steps. Not needed for all Electron apps. -- `-F{:rpmspec}`: Executes the `%{__yarn} install{:rpmspec}` step with `--frozen-lockfile{:rpmspec}`. May be necessary for projects expecting very strict build dependencies, but can also override projects that do not enforce a lock. -- `-N{:rpmspec}`: Executes the `%{__yarn} install{:rpmspec}` step with `--no-lockfile{:rpmspec}`. Makes Yarn not update the lockfile on dependency installation. - -Example usage: -```rpmspec -%build -%yarn_build -f wayland,x11 -``` - -The above would run Yarn build steps and execute a Tauri build with the features `wayland` and `x11`. - - - -### Other -JavaScript related macros that apply to all or do not fit into any of the above categories. - -#### %set_javascript_build_flags -Set the flags and environment variables used for JavaScript package manager builds. - -Based on Fedora's [`%set_build_flags` macro](https://src.fedoraproject.org/rpms/redhat-rpm-config/blob/rawhide/f/buildflags.md#using-rpm-build-flags). - -Expands to: -```rpmspec -NPM_CONFIG_USERCONFIG="${NPM_CONFIG_USERCONFIG:-%{rpmbuilddir}/.npmrc}" ; export NPM_CONFIG_USERCONFIG ; \ -NPM_CONFIG_GLOBALCONFIG="${NPM_CONFIG_GLOBALCONFIG:-%{rpmbuilddir}/npmrc}" ; export NPM_CONFIG_GLOBALCONFIG ; \ -NPM_CONFIG_CACHE="${NPM_CONFIG_CACHE:-%{_npm_cache_dir}}" ; export NPM_CONFIG_CACHE ; \ -NPM_CONFIG_LOGLEVEL="${NPM_CONFIG_LOGLEVEL:-%{__npm_log_level}}" ; export NPM_CONFIG_LOGLEVEL ; \ -NPM_CONFIG_FUND="${NPM_CONFIG_FUND:-false}" ; export NPM_CONFIG_FUND ; \ -NPM_CONFIG_UPDATE_NOTIFIER="${NPM_CONFIG_UPDATE_NOTIFIER:-false}" ; export NPM_CONFIG_UPDATE_NOTIFIER ; \ -NPM_CONFIG_COLOR="${NPM_CONFIG_COLOR:-always}" ; export NPM_CONFIG_COLOR ; \ -NPM_CONFIG_INIT_MODULE="${NPM_CONFIG_INIT_MODULE:-%{rpmbuilddir}/.npm-init.js}" ; export NPM_CONFIG_INIT_MODULE ; \ -BUN_HOME="${BUN_HOME:-%{_bun_home}}" ; export BUN_HOME ; \ -BUN_INSTALL_CACHE_DIR="${BUN_INSTALL_CACHE_DIR:-%{_bun_cache_dir}}" ; export BUN_INSTALL_CACHE_DIR \ -BUN_RUNTIME_TRANSPILER_CACHE_PATH="${BUN_RUNTIME_TRANSPILER_CACHE_PATH:-%{_bun_cache_dir}}" ; export BUN_RUNTIME_TRANSPILER_CACHE_PATH ; \ -DENO_DIR="${DENO_DIR:-%{_deno_dir}}" ; export DENO_DIR ; \ -DENO_INSTALL_ROOT="${DENO_INSTALL_ROOT:-%{_deno_install_root}}" ; export DENO_INSTALL_ROOT ; \ -DENO_NO_UPDATE_CHECK="${DENO_NO_UPDATE_CHECK:-1}" ; export DENO_NO_UPDATE_CHECK ; \ -DENO_JOBS="${DENO_JOBS:-${RPM_BUILD_NCPUS}}" ; export DENO_JOBS ; \ -PNPM_HOME="${PNPM_HOME:-%{_pnpm_home}}" ; export PNPM_HOME ; \ -YARN_CACHE_FOLDER="${YARN_CACHE_FOLDER:-%{_yarn_cache_dir}}" ; export YARN_CACHE_FOLDER ; \ -NPM_OPTS="${NPM_OPTS:-%{npm_config_opts} }" ; export NPM_OPTS ; \ -BUN_OPTS="${BUN_OPTS:-%{bun_config_opts} }" ; export BUN_OPTS ; \ -YARN_OPTS="${YARN_OPTS:-%{yarn_config_opts} }" ; export YARN_OPTS -``` - -This ensures the environment variables are explicitly exported and therefor are more likely to be picked up by all shell processes. It also creates environment variables called `$NPM_OPTS{:bash}`, `$BUN_OPTS{:bash}`, and `$YARN_OPTS{:bash}`, which can be passed to NPM in lieu of the macros `%{npm_config_opts}{:rpmspec}`, `%{bun_config_opts}{:rpmspec}`, and `%{yarn_config_opts}{:rpmspec}`, respectively, to force our config if necessary. - -This should only be needed in the event you are using [%__npx](#__npx), [%__pnpx](#__pnpx), [%__bunx](#__bunx), [%__dx](#__dx), [%__yarn_dlx](#__yarn_dlx), OR the package uses one of these buildsystems (ex. build command uses `wails`). - - - -## Nim -These macros assist with building [Nim](https://nim-lang.org) projects. -Currently `atlas` is not directly supported by the macros, but you can run it directly in `%build{:rpmspec}`: -```rpmspec -%build -atlas init -atlas rep atlas.lock -%nim_c src/my_project -``` - -### %nim_prep -Set up build environment with required packages via `nimble setup`. - -This also adds the configuration for enabling mold automatically if found in the build environment. - - - -### %nim_build (or %nim_c) -Builds a Nim package. -Requires an argument to `src/pkgname`. - -Note that this does not invoke `nimble`. All dependencies SHOULD be ready before `%build{:rpmspec}`. - - - -### %nim_tflags -C compiler flags used in `%nim_c{:rpmspec}`. - - - -### %nim_lflags -Linker flags used in `%nim_c{:rpmspec}`. - - - -## Rust -These macros assist with building [Rust](https://rust-lang.org) projects. - -### %cargo_prep_online -Enables internet access for `%cargo_prep{:rpmspec}`. Replaces `%cargo_prep{:rpmspec}` in `%prep{:rpmspec}`. - - - -### %cargo_license_online -Enables internet access for `%cargo_license{:rpmspec}`. -Replaces `%cargo_license{:rpmspec}` in `%build{:rpmspec}`. - - - Cargo license macros MUST be wrapped in `{}` when being used to write a license file. - - - - -### %cargo_license_summary_online -Enables internet access for `%cargo_license_summary{:rpmspec}`. -Replaces `%cargo_license_summary{:rpmspec}` in `%build{:rpmspec}`. - - - -### %cargo_vendor_manifest_online -Enables internet access for `%cargo_vendor_manifest_online{:rpmspec}`. -Replaces `%cargo_vendor_manifest{:rpmspec}` in `%build{:rpmspec}`. - - - -### %crate_install_bin -Used to install crates that build as single binary. -Can be used instead of `%cargo_install{:rpmspec}` when [this](https://github.com/terrapkg/packages/issues/1169) is applicable. - - - -### %rustup_nightly -Used in the `%prep{:rpmspec}` section for nightly `rustc`/`cargo` from `rustup`. - - - This macro MUST be used *before* `%cargo_prep_online` (or an equivalent prep macro) if it is used. - - - - -## Subpackages -These macros assist with packages that require certain subpackage types. -For example, some packages will build application and library files. Using `%pkg_devel_files{:rpmspec}` will greatly help you in making the library files (`-devel`) subpackage. -More information on subpackages can be found on the [Fedora Packaging Guidelines](https://docs.fedoraproject.org/en-US/packaging-guidelines/#_mixed_use_packages). - -### %files_libs -This macro creates library subpackages and installs the library files. -This is only for use in the [`%pkg_devel_files` macro](#pkg_devel_files). - - - -### %pkg_completion -This macro creates shell completion subpackages and installs the shell completion files. -This macro SHOULD be used if your package provides shell completion files. -Use the below flags according to the shell completion files your package uses: - -``` --B: bash (but the completion file doesn't have `.bash` extension) --b: bash --e: elvish --f: fish --N: nushell --z: zsh -``` - -For specifying the name (the default will be your `%name`) of the shell completion subpackages (if needed): -``` --n pkgname -``` - -Can also pass `cmd1`, etc. as the commands the completion files are for. - -Example using all flags: -```rpmspec -%pkg_completion -BbefNz -n pkgname cmd1 cmd2 ... -``` - -A good example spec that uses this macro is [yadm](https://github.com/terrapkg/packages/blob/d861164790b3d77f5ee094d303de2dfc3299ef8b/anda/devs/yadm/yadm.spec#L22). -This spec creates these packages: - -``` -yadm-x.x.x-x.fcxx.noarch.rpm - contains all core package files. -yadm-bash-completion-x.x.x-x.fcxx.noarch.rpm - contains `/usr/share/bash-completion/completions/yadm` -yadm-fish-completion-x.x.x-x.fcxx.noarch.rpm - contains `/usr/share/fish/vendor_completions.d/yadm.fish` -yadm-zsh-completion-x.x.x-x.fcxx.noarch.rpm - contains `/usr/share/zsh/site-functions/_yadm` -``` - - - -### %pkg_devel_files -Set the summary & description, then find development files and install them to a subpackages `%files`. -SHOULD be used in place of manually creating `-devel` subpackages. - - You still need to define a `%package devel`, and then use this macro below that. - -For example: - -```rpmspec -%package devel -# generates Summary:, %description devel and the file lists -# -F to omit %files -# -n : name of the devel package -# -N : name of the main package -%pkg_devel_files -``` - - - -### %pkg_static_files -Set the summary & description, then find static libraries. -SHOULD be used in place of manually creating `-static` subpackages. - - You still need to define a `%package static`, and then use this macro below that. - -For example: - -```rpmspec -%package static -# -n : name of the static package -# -N : name of the main package -%pkg_static_files -``` - - - -### %pkg_libs_files -Set the summary & description, then find dynamic library files (will be placed as `%_libdir/*.so.*`). -SHOULD be used in place of manually creating `-libs` subpackages. - - You still need to define a `%package libs`, and then use this macro below that. - -For example: - -```rpmspec -%package libs -# -n : name of the static package -# -N : name of the main package -%pkg_static_files -``` - - - -## Zig -These macros assist with building Zig projects. - -### %__zig -This macro is the same as `%zig` but formatted to match how most macros calling binaries are. Use of it is not encouraged *or* discouraged, it only exists because it's an easy mistake to make. - - - -### %zig_build_target -Build Zig projects with a specified architecture and build mode. - -Available flags: -- `-c[โ€ฆ]`: Used to set a specific CPU (micro)architecture to build for. If no argument is supplied, it will fall back to the `%{_target_cpu}` set by the build. You MUST specify a CPU architecture manually in cases where Zig's architecture format and RPM's do not match (e.g., `aarch64`). - - SHOULD ONLY be used in projects that would not perform correctly when built for baseline. - - For more information on x86_64 microarchitectures, see [here](https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels). -- `-r <โ€ฆ>`: Used to set the [release/build mode](https://zig.guide/build-system/build-modes). Accepted arguments are `fast`, `small`, `safe`, and `slow`. - - SHOULD be used if a project would have performance issues if built for `safe` (what Fedora sets by default). -- `-s{:rpmspec}`: used to allow the project to link statically. - - SHOULD ONLY be used if a project either has no dependencies to link, OR dependencies from the repos either aren't present or are incompatible versions. - - You SHOULD still dynamically link compatible dependencies using `-fsys=pkgname`. - -Example: -```rpmspec -%build -%{zig_build_target -r fast -cx86_64_v2} \ - -Demit-docs -``` - -More information can be found on our [Zig packaging guidelines](../terra/guidelines#zig). - - - -## Miscellaneous -General macros that do not fit into a specific category. - -### %evr -Used for declaring how a package interacts with others, such as, in a `Requires:{:rpmspec}` or `Obsoletes:{:rpmspec}` tag. -For example, `Requires: %{name} = %evr{:rpmspec}`. -Expands to: `%{?epoch:%{epoch}:}%{version}-%{release}`. -Real package examples: - -`Requires:{:rpmspec}` example: - -```rpmspec -BuildRequires: pkgconfig(pkgconf) -BuildRequires: pkgconfig(zlib) -BuildRequires: pkgconfig(openssl) -BuildRequires: pkgconfig(libarchive) >= 3.3.3 -Requires: %name-lib = %evr -``` - -`Recommends:{:rpmspec}` example: - -```rpmspec -Name: rnote -License: GPL-3.0 -Recommends: rnote-cli = %evr -``` - -`Provides:{:rpmspec}` example: - -```rpmspec -%package devel -Summary: Development files for %{name} -Requires: %{name}%{?_isa} = %{version}-%{release} -Provides: %realname-devel = %evr -Conflicts: %realname-devel -``` - - - -### %git_clone -Downloads the source code via `git clone`, and passes useful (in this situation) flags such as`--depth 1`, `-q`, `--recursive-submodules`, and `-j${RPM_BUILD_NCPUS}`. -A git URL and a `%version{:rpmspec}` or `%commit{:rpmspec}` MAY be passed to this macro. -Below is an example of how a spec that tracks version tages from a GitHub repo, and needs to git clone the source could handle this: - -```rpmspec -Version: 0.8.0 ---- -URL: https://github.com/ethangreen-dev/lovely-injector ---- -%prep -%git_clone %{url} v%{version} -``` - -Below is an example of how a spec that tracks the latest commit from a GitHub repo, and needs to Git clone the source could handle this: - -```rpmspec -%global commit 9417838c91aab6088778089b9a3e8330bca53fbd ---- -URL: https://github.com/ad-oliviero/uwufetch ---- -%prep -%git_clone %{url} %{commit} -``` - -`%git_clone` SHOULD only be used when the source tarballs provided by upstream does not include all required sources in the repository (e.g., if the build process expects a Git environment or the tarball doesn't contain submodules). - -It is RECOMMENDED to still fetch and include a source tarball via the spec sources even if it is not used so that the source RPM is not empty. - - - -### %go_task -Expands to: `go-task --parallel --concurrency %{?_smp_build_ncpus} --verbose --yes` -SHOULD be used in place of `go-task` if using Go Task. - - - -## Unused in Spec Files -These macros are ONLY used by other macros in their expansion processes, as programmed [here](https://github.com/terrapkg/srpm-macros). -These are documented ONLY for development and completion sake. - -### %__anda_develfiles -Expands to: `%_anda_srpm_macros_dir/find-develinfo.sh %buildroot > anda-develfiles.list{:rpmspec}` -Used as a macro within [`%pkg_devel_files`](#pkg_devel_files). - -### %__anda_libsfiles -Expands to: `%_anda_srpm_macros_dir/find-libsinfo.sh %buildroot > anda-libsfiles.list{:rpmspec}` -Used as a macro within [`%pkg_libs_files`](#pkg_libs_files). - -### %_anda_srpm_macros_dir -Expands to: `/usr/libexec/anda-srpm-macros` -Anda directory for scripts such as `find-develinfo.sh` used by `%__anda_develfiles{:rpmspec}`, which is used in [`%pkg_devel_files`](#pkg_devel_files). - -### %__anda_staticfiles -Expands to: `%_anda_srpm_macros_dir/find-staticinfo.sh %buildroot > anda-staticfiles.list{:rpmspec}` -Creates anda-staticfiles.list file in `%{buildroot}{:rpmspec}` to be used by [`%pkg_static_files`](#pkg_static_files). - -### %__update_desktop_database -Expands to: `/usr/bin/update-desktop-database{:rpmspec}` -This is not used as there is no reason not to use `%update_desktop_database`. - -### %desktop_file_args -This macro is created when using the `-F` option in `%electron_install`. It's used to pass the appropriate Exec arguments to `desktop-file-install` and has no other use. - -### %is_electron_bundled -Expands to `%bcond bundled_electron %["%{name}" != "electron"]{:rpmspec}` -A functional macro that tells other macros if Electron is bundled or if the package being worked with is Electron itself. Used by [`%electronmeta`](#electronmeta) and [`%electron_license`](#electron_license). - -### %__tauri_common_opts -Common opts passed to Tauri. Used by macros which call Tauri. - -### %terra_rustflags -This macro simply appends the [Mold linker arguments](/terra/guidelines#usage-of-the-mold-linker) onto the `%build_rustflags` macro. It should not need to be manually used as `%build_rustflags` will be appended automatically when using `%cargo_prep_online`. - ---- - -[^1]: `x86_64`, `x86_64_v2`, `x86_64_v3`, `x86_64_v4`, `amd64`, `em64t` -[^2]: `i386`, `i486`, `i586`, `i686`, `pentium3`, `pentium4`, `athlon`, `geode` -[^3]: `mips64`, `mips64el`, `mips64r6`, `mips64r6el` diff --git a/content/docs/terra/terra-infra-graph.png b/content/docs/terra/terra-infra-graph.png deleted file mode 100644 index b350889c..00000000 Binary files a/content/docs/terra/terra-infra-graph.png and /dev/null differ