Skip to main content

​
Overview

The anda.hcl file is the core configuration file for packages in Terra. It defines how packages should be built, which architectures to support, and various metadata labels for the build system. Every package directory must contain an anda.hcl file that specifies at minimum a project block with RPM configuration.

​
File Structure

​
Root Configuration

The root anda.hcl (located at the repository root) configures global settings: 
config {
	strip_prefix = "anda/"
	strip_suffix = "/pkg"
}

project {}
​
config.strip_prefix
string
Prefix to strip from package paths when determining package names.
​
config.strip_suffix
string
Suffix to strip from package paths when determining package names.

​
Project Block

Every package anda.hcl must contain a project pkg block: 
project pkg {
	arches = ["x86_64"]
	rpm {
		spec = "package-name.spec"
	}
}

​
Configuration Reference

​
Architecture Configuration

​
arches
array
List of architectures to build the package for. If omitted, defaults to all supported architectures.Common values:
  • "x86_64" - 64-bit Intel/AMD
  • "aarch64" - 64-bit ARM
  • "i386" - 32-bit Intel/AMD
Example:
arches = ["x86_64", "aarch64", "i386"]

​
RPM Configuration

​
rpm.spec
string
required
Path to the RPM spec file, relative to the package directory.Example:
rpm {
  spec = "discord.spec"
}
​
rpm.extra_repos
array
Additional repositories to enable during the build process. Useful when build dependencies are not available in standard Fedora or Terra repositories.Note: Use double backslashes (\\) to escape RPM variables like $releasever and $basearch.Examples:
# Single repository
extra_repos = ["https://packages.adoptium.net/artifactory/rpm/fedora/\\$releasever/\\$basearch"]

# Multiple repositories
extra_repos = [
  "https://repos.fyralabs.com/terrarawhide-nvidia",
  "https://repos.fyralabs.com/terrarawhide-multimedia"
]

​
Labels

Labels provide metadata to the build system and control various build behaviors.
​
labels.subrepo
string
Specifies which Terra subrepo this package belongs to.Valid values:
  • "extras" - Packages that may conflict with Fedora
  • "nvidia" - NVIDIA driver and CUDA packages
  • "mesa" - Patched Mesa packages
  • "multimedia" - Multimedia codec packages
Example:
labels {
  subrepo = "extras"
}
​
labels.mock
number
When set to 1, enables mock build environment with additional isolation.Use when:
  • Package has complex build dependencies
  • Build requires extra repositories
  • Need clean build environment
Example:
labels {
  mock = 1
}
​
labels.large
number
When set to 1, indicates this is a large package that requires more build resources.Example:
labels {
  large = 1
}
​
labels.nightly
number
When set to 1, marks this package as a nightly/development build.Example:
labels {
  nightly = 1
}
​
labels.updbranch
number
When set to 1, enables branch-specific version tracking.Example:
labels {
  updbranch = 1
}

​
Complete Examples

​
Simple Application Package

project pkg {
	arches = ["x86_64"]
	rpm {
		spec = "discord.spec"
	}
}
A minimal configuration for a simple x86_64-only application.

​
Package with Subrepo

project pkg {
	arches = ["x86_64"]
	rpm {
		spec = "anki.spec"
	}
	labels {
		subrepo = "extras"
	}
}
Package that conflicts with Fedora packages, placed in the extras subrepo.

​
Multi-Architecture Library

project pkg {
    arches = ["x86_64", "aarch64", "i386"]
    rpm {
		spec = "mesa.spec"
	}
    labels {
        mock = 1
        subrepo = "mesa"
		large = 1
    }
}
A large multi-architecture library package with mock builds enabled.

​
Package with External Dependencies

project pkg {
	rpm {
		spec = "prismlauncher.spec"
		extra_repos = ["https://packages.adoptium.net/artifactory/rpm/fedora/\\$releasever/\\$basearch"]
	}
	labels {
		mock = 1
	}
}
Package requiring dependencies from external repositories (Adoptium JDK).

​
Multimedia Package with Multiple Repos

project pkg {
    arches = ["x86_64", "aarch64", "i386"]
    rpm {
        spec = "ffmpeg.spec"
        extra_repos = [
          "https://repos.fyralabs.com/terrarawhide-nvidia",
          "https://repos.fyralabs.com/terrarawhide-multimedia"
        ]
    }
    labels {
        updbranch = 1
        mock = 1
        subrepo = "multimedia"
    }
}
Complex multimedia package requiring NVIDIA and multimedia subrepos.

​
NVIDIA/CUDA Package

project pkg {
    rpm {
		spec = "cuda.spec"
	}
	labels {
	   subrepo = "nvidia"
	   updbranch = 1
    }
}
CUDA toolkit package in the NVIDIA subrepo.

​
Nightly Build Package

project pkg {
    rpm {
        spec = "flameshot-nightly.spec"
    }
    labels {
        nightly = 1
    }
}
Nightly/development build configuration.

​
Best Practices

Architecture Selection:
  • Only specify architectures your package actually supports
  • Test on all listed architectures before submitting
  • Omit arches if package is BuildArch: noarch
Extra Repositories:
  • Always use \\$releasever and \\$basearch for distribution-independent URLs
  • Prefer Terra or Fedora repositories when possible
  • Document why external repos are needed
Subrepo Assignment:
  • extras - Packages that replace or conflict with Fedora packages
  • nvidia - All NVIDIA/CUDA related packages
  • mesa - Custom Mesa builds only
  • multimedia - Codec and multimedia packages
  • No subrepo - Standard packages that complement Fedora

​
Common Patterns

​
System Tools

project pkg {
  arches = ["x86_64"]
  rpm {
    spec = "asusctl.spec"
  }
}
Simple system utilities typically don’t need special labels.

​
Large Builds

labels {
  large = 1
  mock = 1
}
Combine large and mock for resource-intensive builds.

​
Release Packages

project pkg {
	arches = ["x86_64"]
	rpm {
		spec = "terra-release.spec"
	}
	labels {
		updbranch = 1
	}
}
Repository configuration packages often use updbranch.

​
Troubleshooting

Add the repository containing those dependencies to extra_repos:
rpm {
  spec = "mypackage.spec"
  extra_repos = ["https://repo.example.com/fedora/\\$releasever/\\$basearch"]
}
Move to extras subrepo:
labels {
  subrepo = "extras"
}
Enable the large label:
labels {
  large = 1
}
Enable mock:
labels {
  mock = 1
}

Build docs developers (and LLMs) love

Get started for freeTalk to us