Source Package Format 2.0

Format Overview

Source Package Format 2.0 (SPF 2.0) defines the structure and conventions for distributing software sources in the ProteanOS ecosystem. This format enables consistent package building, dependency tracking, and distribution across the project infrastructure.

The format balances simplicity with the flexibility needed to handle diverse software projects, from simple utilities to complex system components.

Package Structure

A source package following SPF 2.0 consists of:

package-name-1.0.0/
├── control           # Package metadata
├── rules             # Build instructions
├── changelog         # Version history
├── copyright         # License information
├── patches/          # Optional: patches to apply
│   ├── series
│   └── *.patch
└── src/              # Source code (or tarball reference)
    └── ...

Control File Specification

The control file contains package metadata in a structured format. Each field begins at the start of a line, with values following after a colon.

Header Fields

Source: example-library
Format: 2.0
Section: libraries
Priority: optional
Maintainer: Package Team <packages@proteanos.com>
Build-Depends: build-essential, cmake
Standards-Version: 2.0.1

Package: example-library
Architecture: any
Depends: ${shlibs:Depends}
Description: Example shared library
 This package provides a shared library demonstrating
 the source package format conventions.

Source Stanza Fields

• Source — Source package name
• Format — Package format version (2.0)
• Section — Package category
• Priority — Installation priority
• Maintainer — Package maintainer contact
• Build-Depends — Build-time dependencies
• Standards-Version — Version of packaging standards followed

Binary Package Stanza

Each binary package produced from the source has its own stanza with fields describing that specific output package.

Build Rules

The rules file contains build instructions executed by ProKit. Common targets include:

• configure — Prepare the build (run configure scripts, cmake, etc.)
• build — Compile the software
• install — Install to staging directory
• clean — Remove build artifacts

#!/usr/bin/make -f

%:
	prokit-helper $@

override_configure:
	cmake -DCMAKE_INSTALL_PREFIX=/usr \
	      -DCMAKE_BUILD_TYPE=Release \
	      ..

override_build:
	$(MAKE) -j$(NPROC)

override_install:
	$(MAKE) DESTDIR=$(DESTDIR) install

Tarball Handling

Source packages can reference upstream tarballs rather than including source directly. Archive tools in the ecosystem, such as those documented at kernel.org, follow similar conventions for patch application.

Patch Management

When upstream sources need modification, patches are stored in the patches/ directory and applied in order specified by the series file.

# Applied in order listed
01-fix-cross-compilation.patch
02-add-arm-support.patch
03-documentation-typos.patch

Version 2.0 Improvements

SPF 2.0 introduced several improvements over earlier formats:

• Clearer separation of source and binary package metadata
• Improved dependency expression syntax
• Support for architecture-specific build options
• Standardized patch management conventions
• Better integration with cross-compilation workflows

Validation

ProKit includes validation tools to check packages against the format specification:

prokit lint .
prokit check-format --version 2.0