Debian Packaging Reference

This guide provides comprehensive information about creating and maintaining Debian packages for StarlingX.

Overview

StarlingX uses Debian packaging for building and distributing software components. This document covers:

  • Debian package file structure and formats

  • StarlingX-specific packaging conventions

  • Build system integration files

  • Package conversion from RPM/CentOS

For information about multi-OS support and directory structures, see Building Multiple Debian Releases from Master Branch.

Environment Setup

The StarlingX build system handles most build environment setup automatically. However, for package development and testing, you may want to install some Debian packaging tools.

Development Tools (Optional)

For local package development and analysis outside the StarlingX build environment:

sudo apt install debhelper dpkg-dev devscripts apt-file

Tools:

  • debhelper: Helper scripts for debian/rules

  • dpkg-dev: Package development tools

  • devscripts: Scripts for package maintainers (dch, debdiff, etc.)

  • apt-file: Search for files in packages

Shell Configuration (Optional)

For using Debian tools like dch (changelog editor):

# Add to ~/.bashrc
export DEBFULLNAME="Your Full Name"
export DEBEMAIL="your.email@example.com"

# Apply changes
source ~/.bashrc

StarlingX Package Directory Structure

Standard Layout

StarlingX packages follow this directory structure:

<package-name>/
├── debian/
│   ├── bullseye/  (or trixie/, or all/)
│   │   ├── deb_folder/
│   │   │   ├── changelog
│   │   │   ├── compat
│   │   │   ├── control
│   │   │   ├── copyright
│   │   │   ├── <package>.install
│   │   │   ├── rules
│   │   │   ├── patches/
│   │   │   └── source/
│   │   │       └── format
│   │   ├── metadata.yaml
│   │   └── dl_hook (optional)
│   └── src/ (optional, for some layouts)
└── <source-files>

See Building Multiple Debian Releases from Master Branch for details on choosing between bullseye/, trixie/, or all/ directories.

Debian Package Files

metadata.yaml

The metadata.yaml file contains StarlingX-specific build metadata.

Basic Structure:

---
debname: package-name
debver: 1.0
src_path: src
revision:
  dist: $STX_DIST
  PKG_GITREVCOUNT: true

Fields:

  • debname: Package name (matches the package directory)

  • debver: Package version

  • src_path: Path to source code relative to the debian directory

  • src_files: List of additional source files or directories to include

  • revision: Version control information (see Revision Fields below)

With dl_hook:

For packages requiring multiple source directories or external files:

---
debname: package-name
debver: 1.0
dl_hook: dl_hook
revision:
  dist: $STX_DIST
  PKG_GITREVCOUNT: true

Revision Fields

The revision section controls version numbering and build reuse detection.

Version Format:

StarlingX package versions are composed as <debian-version>-<revision>, where:

  • <debian-version> is the debver field from metadata.yaml

  • <revision> is calculated from git commit counts and other factors

For example, if debver: 1.0 and the calculated revision is stx.15, the final package version becomes 1.0-stx.15.

Git commit counts are added to the Debian revision number to track source changes.

Common Fields:

  • dist: Distribution name. This is used as a prefix for the revision number (typically $STX_DIST, which is currently set to stx)

Git Revision Count Options:

PKG_GITREVCOUNT

Tracks changes to the debian/ directory only.

revision:
  dist: $STX_DIST
  PKG_GITREVCOUNT: true
  PKG_BASE_SRCREV: "abc123"  # optional: count commits from this base

Effect: Adds commit count from debian/ directory to package version.

FILES_GITREVCOUNT

Tracks changes to individual files or directories listed in src_files.

src_files:
  - /path/to/file1
  - /path/to/directory2
revision:
  dist: $STX_DIST
  FILES_GITREVCOUNT:
    - "commit_hash_1"  # base commit for file1
    - "commit_hash_2"  # base commit for directory2

Effect: Adds commit counts from each src_file location to package version. Requires one base commit per src_file entry.

SRC_GITREVCOUNT

Tracks changes to the src_path directory.

src_path: src
revision:
  dist: $STX_DIST
  SRC_GITREVCOUNT:
    SRC_BASE_SRCREV: "def456"  # optional: count commits from this base

Effect: Adds commit count from src_path directory to package version.

GITREVCOUNT

Tracks changes in a custom directory and affects both version and checksum calculation.

revision:
  dist: $STX_DIST
  GITREVCOUNT:
    SRC_DIR: "$MY_REPO/some/path"  # optional: defaults to debian/
    BASE_SRCREV: "xyz789"  # required

Effect:

  • Adds commit count to package version

  • Includes git log (last 10 commits) and git diff in checksum calculation

  • Changes to git history trigger rebuild even if files unchanged

  • Only GITREVCOUNT variant that affects reuse detection

Combining Multiple Options:

You can use multiple GITREVCOUNT options together:

src_path: src
src_files:
  - /external/file
revision:
  dist: $STX_DIST
  PKG_GITREVCOUNT: true
  SRC_GITREVCOUNT:
    SRC_BASE_SRCREV: "abc123"
  FILES_GITREVCOUNT:
    - "def456"

The total revision number is the sum of all git commit counts plus any uncommitted changes.

stx_patch

Adds a fixed numeric offset to the package revision number.

revision:
  dist: $STX_DIST
  PKG_GITREVCOUNT: true
  stx_patch: 5

Effect: Adds the specified integer value to the package revision.

Use Cases:

  • Force a version bump without code changes

  • Maintain version continuity when switching packaging approaches

  • Override automatic revision numbering for special releases

  • Ensure a patched package has a higher version than the base package

Example:

If PKG_GITREVCOUNT calculates revision as 10, and stx_patch is 5, the final revision becomes 15.

Requirements:

  • Must be an integer value

  • Can be combined with any GITREVCOUNT options

  • Added after all git commit counts are calculated

dl_hook Script

The dl_hook file is a bash script used when packages require sources from multiple locations.

Example:

#!/bin/bash
set -x

PKG_BUILD_NAME=$1
PKG_BUILD_ROOT=$(realpath `pwd`/${PKG_BUILD_NAME})
STX_BASE=$(realpath ${MY_REPO}/stx)
SRC=$(realpath ${STX_BASE}/repo/package)

mkdir ${PKG_BUILD_NAME}
pushd ${PKG_BUILD_NAME}
cp -pr ${SRC}/files-* ${PKG_BUILD_ROOT}/
popd

changelog

The changelog file contains version history for the package.

Create a new changelog:

# Run in the package root directory
dch --create

Format:

package-name (1.0-1) unstable; urgency=medium

  * Initial release.

 -- Developer Name <developer@example.com>  Sun, 08 Aug 2021 12:14:46 -0400

Update existing changelog:

dch -i  # Increment version
dch -v 1.0-2  # Specific version

Reference: https://www.debian.org/doc/manuals/maint-guide/dreq.en.html#changelog

compat

Specifies the debhelper compatibility level (optional, as it’s also in control).

13

control

The control file defines packages and their dependencies.

Header Section:

Source: package-name
Section: libs
Priority: optional
Maintainer: StarlingX Developers <starlingx-discuss@lists.starlingx.io>
Build-Depends: debhelper-compat (= 13),
 dh-python,
 python3-all,
 python3-setuptools
Standards-Version: 4.5.1
Homepage: https://www.starlingx.io

Header Fields:

  • Source: Package name

  • Section: Distribution section (admin, devel, doc, libs, etc.)

  • Priority: Always optional for StarlingX packages

  • Maintainer: Always StarlingX Developers <starlingx-discuss@lists.starlingx.io>

  • Build-Depends: Build-time dependencies

    • Always include debhelper-compat (= 13)

    • Python packages: add dh-python

  • Standards-Version: Currently 4.5.1

  • Homepage: Always https://www.starlingx.io

Package Section:

Package: package-name
Architecture: any
Depends: ${python3:Depends}, ${misc:Depends}
Description: Short description
 Detailed description of the package. Each line must be
 indented by one space.

Package Fields:

  • Package: Package name

  • Architecture:

    • any: Binary package (executables, shared libraries)

    • all: Architecture-independent (text, Python without native bindings)

  • Depends: Runtime dependencies

    • Always include ${misc:Depends}

    • Python packages: ${python3:Depends}

    • C++ packages: ${shlibs:Depends}

  • Description: Package description (short line + detailed lines)

Reference: https://www.debian.org/doc/manuals/maint-guide/dreq.en.html#control

<package>.install

Specifies files to include in the .deb package. All paths are relative to debian/tmp.

Example:

etc/logrotate.d/package.logrotate
etc/package/config.ini
usr/bin/package-cli
usr/lib/python3/dist-packages/package/*

Reference: https://www.debian.org/doc/manuals/maint-guide/dother.en.html#install

rules

The rules file is a Makefile that drives the package build.

Basic Structure:

#!/usr/bin/make -f

export DH_VERBOSE = 1

%:
    dh $@

Warning

Makefile syntax requires TAB characters for indentation. Spaces will cause “missing separator” errors.

Python Package:

#!/usr/bin/make -f

export DH_VERBOSE = 1
export PYBUILD_NAME=package-name

%:
    dh $@ --with=python3 --buildsystem=pybuild

With Custom Install:

#!/usr/bin/make -f

export DH_VERBOSE = 1
export ROOT=$(CURDIR)/debian/tmp
export CONFDIR=$(ROOT)/etc/package

%:
    dh $@ --with=python3 --buildsystem=pybuild

override_dh_auto_install:
    install -d -m 755 $(CONFDIR)
    install -p -D -m 644 config/config.ini $(CONFDIR)/config.ini

Common Overrides:

  • override_dh_auto_configure: Custom configuration

  • override_dh_auto_build: Custom build steps

  • override_dh_auto_install: Custom installation

  • override_dh_auto_test: Custom tests

Disable a Step:

override_dh_auto_test:
    # Leave blank to skip tests

Reference: https://www.debian.org/doc/manuals/maint-guide/dreq.en.html#rules

patches/

Directory for patch files applied to source code. Patches are applied using quilt.

Structure:

patches/
├── series
├── 0001-fix-something.patch
└── 0002-add-feature.patch

series file:

0001-fix-something.patch
0002-add-feature.patch

Reference: https://www.debian.org/doc/manuals/maint-guide/dother.en.html#patches

source/format

Specifies the source package format. Always use:

3.0 (quilt)

Reference: https://www.debian.org/doc/manuals/maint-guide/dother.en.html#sourcef

StarlingX Build System Files

Build Type Variants

Package directory lists and build configurations are organized by build type:

  • _std - Standard kernel packages (default)

  • _rt - Real-time kernel packages (low-latency, deterministic performance)

  • _sign - Kernel signing packages (secure boot support)

Most repositories only have _std variants. The _rt and _sign variants are specific to the kernel repository.

debian_build_layer.cfg

Each repository specifies which build layer it belongs to using a configuration file.

File Name:

<git>/debian_build_layer.cfg

Content:

A single line containing the layer name (e.g., distro, flock, compiler, containers, openstack).

Purpose:

This file tells the build system which layer’s package lists (os-std.lst, os-rt.lst) should include packages from this repository. The build system uses this to:

  • Organize packages into appropriate layers during download

  • Determine which mirror configuration to use

  • Group packages by layer for building

Example:

For the kernel repository (stx/kernel/debian_build_layer.cfg):

distro

For the compile repository (stx/compile/debian_build_layer.cfg):

compiler

Note

If a repository doesn’t have a debian_build_layer.cfg file, it may not be included in automated layer discovery.

Layer Build Order

Layers are built in a specific order based on priority values. Each layer has a priority file that determines its build sequence.

Priority Files:

stx-tools/debian-mirror-tools/config/debian/${os_codename}/<layer>/priority

Default Build Order:

Layers are built from lowest to highest priority number:

  1. compiler (priority: 10) - Compiler and build tools

  2. distro (priority: 20) - Core distribution packages

  3. flock (priority: 30) - Flock layer packages

  4. containers (priority: 40) - Container-related packages

  5. openstack (priority: 50) - OpenStack packages

Layers without a priority file default to priority 99.

Purpose:

The build order ensures that dependencies are built before packages that depend on them. For example:

  • Compilers must be built first (priority 10)

  • Core distribution packages are built next (priority 20)

  • Higher-level packages are built last (priority 30+)

Image Build Layers:

Not all layers are included when building ISO images. The file cgcs-root/build-tools/stx/image-layers.conf specifies which layers are needed for ISO creation:

compiler
distro
flock

The common layer is always included automatically. Layers like containers and openstack are excluded because they only contain packages for building container images.

Package List Organization

Binary package lists are organized by layer and build type in the mirror tools configuration.

Base Packages:

stx-tools/debian-mirror-tools/config/debian/${os_codename}/common/base-${os_codename}.lst

Core base packages required for all builds (shared across all layers).

Layer-Specific Packages:

stx-tools/debian-mirror-tools/config/debian/${os_codename}/<layer>/os-std.lst
stx-tools/debian-mirror-tools/config/debian/${os_codename}/<layer>/os-rt.lst

Where <layer> can be:

  • compiler - Compiler layer packages

  • containers - Container layer packages

  • distro - Distribution layer packages

  • flock - Flock layer packages

  • openstack - OpenStack layer packages

The os-rt.lst files are optional - only layers with real-time packages need them.

Note

The set of available layers may change over time. Check stx-tools/debian-mirror-tools/config/debian/${os_codename}/ for the current list of layer directories.

debian_*_pkg_dirs

Lists package directories to build. Multiple files for different build types:

  • debian_bullseye_pkg_dirs_std - Standard packages for Bullseye

  • debian_bullseye_pkg_dirs_rt - Real-time packages for Bullseye

  • debian_bullseye_pkg_dirs_installer - Installer packages for Bullseye

  • debian_trixie_pkg_dirs_std - Standard packages for Trixie

  • debian_trixie_pkg_dirs_rt - Real-time packages for Trixie

Format:

# One package directory per line
base/package1
networking/package2
storage/package3

Legacy names (Bullseye only):

  • debian_pkg_dirs → debian_bullseye_pkg_dirs_std

  • debian_pkg_dirs_rt → debian_bullseye_pkg_dirs_rt

debian_*_docker_images.inc

Lists Docker images to build.

Naming Pattern:

  • debian_stable_docker_images.inc

  • debian_dev_docker_images.inc

  • debian_bullseye_stable_docker_images.inc

  • debian_trixie_stable_docker_images.inc

Format:

# One image directory per line
path/to/image1
path/to/image2

debian_*_wheels.inc

Lists Python wheel packages to build.

Files:

  • debian_stable_wheels.inc

  • debian_dev_wheels.inc

Format:

# Python package names
package1
package2

debian_*_iso_image.inc

Defines ISO image contents and configuration.

Files:

  • debian_bullseye_iso_image_std.inc

  • debian_trixie_iso_image_std.inc

Format:

# Packages to include in ISO
package1
package2

# Configuration directives
KERNEL_VERSION=5.10.0

Building Packages

StarlingX Build System

StarlingX uses a custom build system that handles package building, dependency management, and ISO creation. Do not use standard Debian tools like dpkg-buildpackage or pbuilder directly.

Build all packages:

build-pkgs

Build specific packages:

build-pkgs -p <package-name>

Clean build:

build-pkgs -c

Build with specific options:

build-pkgs --no-descendants  # Don't build dependencies
build-pkgs --no-build-info   # Skip build info generation

The build-pkgs script automatically:

  • Applies patches (both source and meta patches)

  • Builds packages in the correct order

  • Manages build dependencies

  • Creates .deb packages in the build output directory

Note

Source tarballs and Debian packaging must be downloaded first using the downloader script. See StarlingX Build Guide for the complete workflow.

Search for Existing Packages

Before creating a new package, check if it exists in Debian:

# Search by name
apt-cache search package-name

# Get source (requires deb-src in /etc/apt/sources.list)
apt-get source package-name

Web Interface:

Package Source Scenarios

StarlingX supports three packaging scenarios based on source origin and customization needs.

Scenario 1: Local Source with StarlingX Packaging

Use Case: Package source code is maintained in the StarlingX repository.

Directory Structure:

<package-name>/
├── debian/
│   ├── bullseye/  (or all/)
│   │   ├── deb_folder/
│   │   │   ├── changelog
│   │   │   ├── control
│   │   │   ├── rules
│   │   │   └── ...
│   │   └── meta_data.yaml
│   └── src/  (or other source directory)
└── <source-files>/

meta_data.yaml:

---
debname: package-name
debver: 1.0
src_path: src
revision:
  dist: $STX_DIST
  PKG_GITREVCOUNT: true

Fields:

  • debname: Package name

  • debver: Package version

  • src_path: Path to source code relative to debian directory

  • revision: Version control settings

Example: stx/config/sysinv/cgts-client

Scenario 2: Downloaded Source with StarlingX Patches

Use Case: Source tarball is downloaded from upstream (e.g., Debian snapshot), and StarlingX provides patches and optionally custom packaging.

Directory Structure:

<package-name>/
└── debian/
    └── bullseye/
        ├── deb_folder/
        │   ├── changelog
        │   ├── control
        │   ├── rules
        │   └── ...  (optional, overrides downloaded Debian packaging)
        ├── patches/
        │   ├── series
        │   ├── 0001-fix-something.patch
        │   └── 0002-add-feature.patch
        └── meta_data.yaml

meta_data.yaml:

---
debname: isc-dhcp
debver: 4.4.1-2.3
archive: https://snapshot.debian.org/archive/debian/20210529T084123Z/pool/main/i/isc-dhcp/
revision:
  dist: $STX_DIST
  PKG_GITREVCOUNT: true

Fields:

  • debname: Debian package name (may differ from directory name)

  • debver: Debian package version

  • archive: Base URL to download source and Debian packaging (build system finds matching files)

  • revision: Version control settings

patches/ Directory:

Contains patches applied to the source code:

patches/
├── series                    # List of patches to apply
├── 0001-fix-bug.patch       # Patch files
└── 0002-add-feature.patch

series file:

0001-fix-bug.patch
0002-add-feature.patch

deb_folder/ Directory (Optional):

If present, files here override the downloaded Debian packaging. Use this when you need to completely replace Debian’s control, rules, or other packaging files.

Build Process:

  1. Build system downloads from archive URL:

    • Source tarball: <debname>_<debver>.orig.tar.xz

    • Debian packaging: <debname>_<debver>.debian.tar.xz (if available)

    • Or .dsc file and extracts sources

  2. Extracts source and Debian packaging

  3. Applies patches from patches/ directory to source code

  4. If deb_folder/ exists, uses those files instead of downloaded Debian packaging

  5. Builds package

When to use deb_folder/:

  • Debian packaging doesn’t exist upstream (new package)

  • Need to completely rewrite debian/rules or debian/control

  • Simpler than maintaining many deb_patches

Example: stx/integ/base/dhcp (uses downloaded Debian packaging + patches)

Scenario 3: Downloaded Source with Debian Packaging and Meta Patches

Use Case: Both source and Debian packaging are downloaded from upstream, and StarlingX provides patches to both the source code and the Debian packaging files.

Directory Structure:

<package-name>/
└── debian/
    └── bullseye/
        ├── patches/
        │   ├── series
        │   └── *.patch          # Patches to source code
        ├── deb_patches/
        │   ├── series
        │   └── *.patch          # Patches to Debian packaging
        ├── meta_data.yaml
        └── dl_hook              # Script to extract tarballs

meta_data.yaml:

---
debname: grub2
debver: 2.06-1
serial: true
dl_hook: dl_hook
dl_files:
  grub2_2.06.orig.tar.xz:
    topdir: null
    url: "https://snapshot.debian.org/archive/debian/20211128T160803Z/\
           pool/main/g/grub2/grub2_2.06.orig.tar.xz"
    sha256sum: b79ea44af91b93d17cd3fe80bdae6ed43770678a9a5ae192ccea803ebb657ee1
  grub2_2.06-1.debian.tar.xz:
    topdir: null
    url: "https://snapshot.debian.org/archive/debian/20211128T160803Z/\
           pool/main/g/grub2/grub2_2.06-1.debian.tar.xz"
    sha256sum: 16a1a89d93abf8beb148dc30738be1bda05ed3c09cfffd4a1f5e1a0328c74b26
revision:
  dist: $STX_DIST
  PKG_GITREVCOUNT: true

Fields:

  • debname: Debian package name

  • debver: Debian package version

  • serial: Build serially (optional, for packages with build ordering requirements)

  • dl_hook: Script to extract and prepare downloaded files

  • dl_files: Dictionary of files to download

    • Each file has: url, sha256sum, topdir (null if no top-level directory)

  • revision: Version control settings

dl_hook Script:

The dl_hook script extracts both tarballs:

#!/bin/bash
# Parameter $1 is the target directory name

# Extract source tarball
tar xvf grub2_2.06.orig.tar.xz
mv grub-2.06 $1

# Extract Debian packaging into the source directory
cd $1
tar xvf ../grub2_2.06-1.debian.tar.xz

This creates a structure where the Debian packaging (debian/ directory) is inside the source tree.

patches/ Directory:

Patches applied to the source code (same as Scenario 2).

deb_patches/ Directory:

Patches applied to Debian packaging files (control, rules, etc.):

deb_patches/
├── series
├── 0001-dhclient-dhcp6-set-hostname.patch
├── 0002-Update-dn-and-dns-only-with-diff-upon-RENEW.patch
└── 0003-Use-prefixlen-for-IPv6-address-operations.patch

series file:

0001-dhclient-dhcp6-set-hostname.patch
0002-Update-dn-and-dns-only-with-diff-upon-RENEW.patch
0003-Use-prefixlen-for-IPv6-address-operations.patch

Build Process:

  1. Build system downloads files listed in dl_files (source + Debian packaging tarballs)

  2. Verifies SHA256 checksums

  3. Runs dl_hook script to extract both tarballs

  4. Applies patches from patches/ directory to source code

  5. Applies patches from deb_patches/ directory to Debian packaging files

  6. Builds package

Key Differences from Scenario 2:

  • Two tarballs: Source tarball (*.orig.tar.xz) AND Debian packaging tarball (*.debian.tar.xz)

  • dl_files: Explicit list of files to download with checksums

  • dl_hook: Required to extract both tarballs into correct structure

  • No archive field: Uses dl_files instead of archive URL

Use Cases for deb_patches:

  • Modify debian/control to add/remove dependencies

  • Update debian/rules to change build behavior

  • Patch debian/patches/series to enable/disable upstream patches

  • Modify debian/*.install files to change file installation

  • Update debian/changelog

Example: stx/integ/grub/grub2

Choosing the Right Scenario

Scenario

Source Location

Debian Packaging

Customization

1: Local Source

StarlingX repo

StarlingX

Full control
2: Downloaded

Source

Upstream tarball

StarlingX or Downloaded

Source patches
3: Downloaded

with Meta

Upstream tarball

Downloaded + Meta patches

Source + meta patches

Decision Guide:

  • Scenario 1: New StarlingX-specific packages or heavily modified upstream packages

  • Scenario 2: Upstream packages needing source code fixes or features

  • Scenario 3: Upstream packages needing both source fixes and packaging modifications (e.g., dependency changes, build flag changes)

Converting from CentOS/RPM

When converting CentOS packages to Debian, choose the appropriate scenario based on the package characteristics.

Mapping to Debian

CentOS Spec File

Debian Files

Name

meta_data.yaml - debname

Version

meta_data.yaml - debver

BuildRequires

control - Build-Depends

Requires

control - Depends

%description

control - Description

%package

control - Package section

%build

rules

%install

rules

%files

<package>.install

Conversion Decision Tree

  1. Is the source code in the StarlingX repository?

    • Yes → Use Scenario 1 (Local Source)

    • No → Continue to step 2

  2. Does the package exist in Debian/Ubuntu repositories?

    • No → Extract source from SRPM, use Scenario 1

    • Yes → Continue to step 3

  3. Do you need to modify Debian packaging files (control, rules, etc.)?

    • No → Use Scenario 2 (Downloaded Source with patches)

    • Yes → Use Scenario 3 (Downloaded Source with meta patches)

Conversion Steps

For Scenario 1 (Local Source):

  1. Create debian directory structure

  2. Create meta_data.yaml with src_path

  3. Create deb_folder/ with control, rules, changelog, etc.

  4. Test build with build-pkgs -p <package-name>

For Scenario 2 (Downloaded Source):

  1. Find package in Debian snapshot archive

  2. Create meta_data.yaml with archive URL

  3. Create patches/ directory for source code modifications

  4. Optionally create deb_folder/ to override Debian packaging

  5. Test build with build-pkgs -p <package-name>

For Scenario 3 (Downloaded with Meta Patches):

  1. Find package in Debian snapshot archive

  2. Create meta_data.yaml with archive URL

  3. Create patches/ directory for source code modifications

  4. Create deb_patches/ directory for Debian packaging modifications

  5. Test build with build-pkgs -p <package-name>

Build and test:

debuild -S -sa
sudo pbuilder build ../*.dsc

Useful Commands

Package Information

# List package contents
dpkg -L package-name

# Show package info
apt show package-name

# Search for files
apt-file search /path/to/file

# Find which package provides a file
dpkg -S /path/to/file

Source Package Analysis

# Fetch and extract Debian source
dget -x http://archive.debian.org/path/to/package.dsc

# Compare two source packages
debdiff old-package.dsc new-package.dsc

# Extract source from .dsc
dpkg-source -x package.dsc

Package Quality Checks

# Compare two source packages
debdiff old-package.dsc new-package.dsc

# Verify package dependencies
dpkg-deb --info package.deb
dpkg-deb --contents package.deb

StarlingX Build Commands

# Build all packages
build-pkgs

# Build specific package
build-pkgs -p <package-name>

# Clean build
build-pkgs -c

# Build without dependencies
build-pkgs --no-descendants -p <package-name>

# Download dependencies
downloader -b  # Binary packages
downloader -s  # Source packages

Best Practices

General Guidelines

  • Use debhelper-compat (= 13) for all packages

  • Set Maintainer to StarlingX Developers <starlingx-discuss@lists.starlingx.io>

  • Set Homepage to https://www.starlingx.io

  • Use Standards-Version: 4.5.1

  • Follow Debian Policy: https://www.debian.org/doc/debian-policy/

Package Naming

  • Use lowercase names with hyphens (not underscores)

  • Python packages: python3-<name>

  • Development packages: <name>-dev

  • Documentation: <name>-doc

Dependencies

  • Minimize build dependencies

  • Use ${misc:Depends} for all packages

  • Use ${python3:Depends} for Python packages

  • Use ${shlibs:Depends} for packages with shared libraries

  • Specify version constraints when necessary: package (>= 1.0)

Multi-OS Support

References

Official Documentation

StarlingX Documentation