Basic Packaging Workflow

Building packages locally and testing them

Once the prerequisites have been handled, it is time to learn how to install newly built local moss-format .stone packages.

Understanding moss-format repositories

When building and testing packages locally, boulder (and moss) can be configured to consult a local moss-format repository containing moss-format .stone packages and a stone.index local repository index.

`stone.index` files

The stone.index file is what both moss and boulder consult when they check which packages are available to be installed into moss-maintained system roots.

Adding a moss-format repository is as simple as registering a new location from where to fetch stone.index files, which will be shown in detail later on this page.

`moss` build roots

Every time a package is built, boulder calls out to moss to have it construct a pristine build root directory (called a ‘buildroot’) with the necessary package build prerequisites installed.

The packages in this buildroot are resolved from one or more moss stone.index files, sorted in descending priority, such that the highest priority repository “wins” when package providers are resolved.

The lowest priority repository will typically be the official Serpent OS upstream package repository.

If higher priority repositories are added, packages from these will in turn override the packages available in the official Serpent OS upstream package repository.

The next section deals with how to create and register a higher priority local moss-format repository, which is colloquially referred to as a “local repo”.

Creating a local repository

After the helper script has been activated in bash, open a new tab or a new terminal, and execute the following commands:

# create a new tab or open a new terminal
gotoserpentrepo
just create-local
just index-local

The just create-local invocation will set up an empty ~/.cache/local_repo/x86_64/ directory, and the just index-local invocation will create a stone.index file for the directory.

Making boulder use the local repository

Boulder will need to have its list of “build profiles” be updated before it will consult the ~/.cache/local_repo/x86_64/stone.index moss-format repository index created above:

boulder profile list
# output
default-x86_64:
  - volatile = https://packages.serpentos.com/volatile/x86_64/stone.index [0]

# add new local-x86_64 build profile
boulder profile add \
  --repo name=volatile,uri=https://packages.serpentos.com/volatile/x86_64/stone.index,priority=0 \
  --repo name=local,uri=file://${HOME}/.cache/local_repo/x86_64/stone.index,priority=100 \
  local-x86_64
boulder profile list
# output
default-x86_64:
 - volatile = https://packages.serpentos.com/volatile/x86_64/stone.index [0]
local-x86_64:
 - volatile = https://packages.serpentos.com/volatile/x86_64/stone.index [0]
 - local = file:///home/ermo/.cache/local_repo/x86_64/stone.index [100]

Behind the scenes, boulder builds and saves an appropriately named build profile to ~/.config/boulder/profile.d/.

This is what local-x86_64.yaml should look like after the above commands have been run successfully:

local-x86_64:
  repositories:
    local:
      description: ''
      uri: file:///home/ermo/.cache/local_repo/x86_64/stone.index
      priority: 100
      active: true
    volatile:
      description: ''
      uri: https://packages.serpentos.com/volatile/x86_64/stone.index
      priority: 0
      active: true

Making `moss` use the local repository

Listing and adding moss-format repositories containing stone.index files is done as follows:

moss repo list
# output
 - unstable = https://dev.serpentos.com/volatile/x86_64/stone.index [0]
# add repositories
sudo moss repo add volatile https://packages.serpentos.com/volatile/x86_64/stone.index -p 10
sudo moss repo add local file://${HOME}/.cache/local_repo/x86_64/stone.index -p 100
moss repo list
# output
 - unstable = https://dev.serpentos.com/volatile/x86_64/stone.index [0]
 - volatile = https://packages.serpentos.com/volatile/x86_64/stone.index [10]
 - local = file:///home/ermo/.cache/local_repo/x86_64/stone.index [100]

Package resolution order

In the above priority tower, each moss-format package would first get resolved via the local repository (priority 100), then from the volatile repository (priority 10), and finally from the unstable repository (priority 0), the latter of which is the official upstream Serpent OS moss-format .stone package repository.

Disabling moss-format repositories

Users of Serpent OS should generally not have the volatile repository be enabled, because this repository is where new .stone packages land right after being built, which means the repository can potentially be in an undefined and volatile state when building large build queues (hence the name).

Therefore, it can be useful to disable moss-format repositories without deleting their definitions from the local system:

sudo moss repo disable volatile 
sudo moss repo disable local
moss repo list
# output
 - unstable = https://dev.serpentos.com/volatile/x86_64/stone.index [0]
 - volatile = https://packages.serpentos.com/volatile/x86_64/stone.index [10] (disabled)
 - local = file:///home/ermo/.cache/local_repo/x86_64/stone.index [100] (disabled)

Enabling moss-format repositories

However, when testing locally built packages, they must be built against the local-x86_64 boulder build profile, which in turns relies on the volatile repository via the boulder local-x86_64 build profile.

Hence, when testing locally built packages, you may need to temporarily enable the volatile repository for moss to resolve from.

sudo moss repo enable volatile 
sudo moss repo enable local
moss repo list
# output
 - unstable = https://dev.serpentos.com/volatile/x86_64/stone.index [0]
 - volatile = https://packages.serpentos.com/volatile/x86_64/stone.index [10]
 - local = file:///home/ermo/.cache/local_repo/x86_64/stone.index [100]

Building recipes using the `local-x86_64` profile

To actually build a recipe, it is recommended that new packagers start out by building nano.

# Go into the root of the serpent recipe directory 
gotoserpentrepo
# change to the directory holding the nano recipe
chpkg nano
# bump the release number in the nano recipe
just bump
# check the difference between the local state and the upstream recipe state
git diff
# build the bumped nano recipe
just build
# check the difference between the local state and the upstream recipe state
git status
# move the newly built .stone build artifacts to the local repository
just mv-local
# list the build artifacts present in the local repository
just ls-local

Note that the basic packaging workflow in Serpent OS assumes that you are using a local repository.

If you are building multiple package recipes, you will need to just build and just mv-local for each package recipe sequentially.

Updating the installed system state

Testing your package(s) is now as simple as:

Enabling (or disabling) the relevant moss-format repositories with:
```
sudo moss repo enable/disable <the repository>
```
Updating moss’ view of the enabled moss-format repository indices with:
```
sudo moss sync -u
```

Cleaning the local repository

Often, it will be prudent to clean out the local repository after the associated recipe PR has been accepted upstream.

gotoserpentrepo
just clean-local
sudo moss repo disable volatile
sudo moss repo disable local
sudo moss sync -u

This will sync the the local system to a new installed system state made only from the upstream unstable moss-format .stone package repository state.

This will effectively make the new system state “forget” the nano version installed from the local repository in the previous system state.

Ending notes

If you have made it this far, congratulations! You should now understand the basic workflow of packaging and managing repositories with Serpent OS.

Tip: execute just -l to see a list of supported just ‘recipes’, which are common actions that have been automated by the Serpent OS developers.