Packaging Requirements

What's needed to create conformant ProteanOS packages.

Overview

Creating packages for ProteanOS requires adherence to specific format and structural requirements. This page documents what's needed to produce packages that integrate properly with the ProteanOS packaging system.

Well-structured packages are easier to maintain, audit, and deploy. Following these requirements ensures compatibility with package management tools and simplifies the review process for contributed packages.

Required Components

Every conformant package must include:

  • Control file: Metadata describing the package, including name, version, dependencies, and description
  • Build rules: Instructions for building the software from source, typically in a standard makefile or build script format
  • Source code: The actual software sources, or clear references to where they can be obtained
  • License information: Clear indication of the license(s) under which the software is distributed

Control File Format

The control file uses a simple key-value format with required and optional fields:

Example control file
Package: example-tool
Version: 1.2.3
Section: utilities
Priority: optional
Architecture: arm
Maintainer: Developer Name <[email protected]>
Depends: libc
Description: Example utility tool
 A longer description of what this package provides
 and how it's useful for embedded systems.

Required Fields

  • Package — Package name (lowercase, alphanumeric and hyphens)
  • Version — Version string following versioning conventions
  • Architecture — Target architecture(s) or "all" for arch-independent
  • Maintainer — Name and email of the package maintainer
  • Description — Brief description, with optional extended description

Common Optional Fields

  • Section — Category for organizing packages
  • Priority — Installation priority (required, important, standard, optional, extra)
  • Depends — Runtime dependencies
  • Build-Depends — Build-time dependencies
  • Conflicts — Packages that cannot be installed alongside this one
  • Provides — Virtual packages this package provides

Build System Integration

Packages should integrate with standard build systems. ProKit supports:

  • Make-based builds with standard targets (all, install, clean)
  • CMake projects with appropriate cross-compilation configuration
  • Autotools (configure/make) with cross-compilation support
  • Custom build scripts following documented conventions

Installation Paths

Packages must install files to appropriate locations. Standard paths include:

  • /usr/bin/ — User executables
  • /usr/lib/ — Libraries
  • /usr/include/ — Header files
  • /etc/ — Configuration files
  • /usr/share/ — Architecture-independent data
  • /usr/share/doc/ — Documentation

HTTP and Caching Considerations

When packages include web-related components or need to interact with HTTP services, consider proper cache control headers and content security policies. This ensures proper behavior in networked embedded environments.

Quality Requirements

Packages should meet these quality standards:

  • Build cleanly without warnings in strict compiler modes
  • Include no files outside standard installation paths
  • Have complete and accurate dependency declarations
  • Function correctly on all declared target architectures
  • Include appropriate documentation

Packaging FAQ

What happens if my package is missing required fields?

Package validation will fail and the package cannot be built or submitted. ProKit reports which fields are missing.

How do I declare architecture-independent packages?

Use "Architecture: all" in the control file for packages containing only scripts, documentation, or other arch-independent content.

Can I package software with complex build systems?

Yes, but you may need to write wrapper scripts or patches to integrate with the ProKit build process. Document any special requirements.

How are version numbers formatted?

Use semantic versioning (major.minor.patch) where possible. Additional version components are allowed for complex versioning needs.

Related Pages