Revision as of 18:26, 8 November 2021

Overview

This document describes the layout of a Debian build folder for a StarlingX upstream package.

Debian Folder Location

The top level Debian build folder is named "debian". It is found in each package folder as a peer of the CentOS build folder "centos".

For example, consider the DHCP package found in the integ repo in the directory "integ/base/dhcp". The CentOS build folder for this package is "integ/base/dhcp/centos", while the Debian build folder for the package is "integ/base/dhcp/debian".

Debian Folder Structure

The following example shows a full Debian build folder structure. It lists all of the files and directories needed to create a Debian package. Some of the folders and files are required for all kinds of Debian packages, while others are optional depending on the package type.

 path/to/package-name
 . 
 └── debian
     ├── dl_hook 
     ├── meta_data.yaml
     ├── deb_folder
     │   ├── changelog
     │   ├── compat
     │   ├── control
     │   ├── copyright
     │   ├── patches
     │   │   ├── 0001-xxx-yyy-zzz.patch
     │   │   ├── 0002-xxx-yyy-zzz.patch
     │   │   └── series
     │   ├── rules
     │   ├── source
     │   │   └── format
     │   ├── watch
     │   ├── ...
     │   └── ...
     ├── deb_patches
     │   ├── 0001-xxx-yyy-zzz-deb.patch
     │   ├── 0002-xxx-yyy-zzz-deb.patch
     │   └── series
     ├── patches
     │   ├── 0001-xxx-yyy-zzz.patch
     │   ├── 0002-xxx-yyy-zzz.patch
     │   └── series

dl_hook

The dl_hook file is a bash script file which is used when the package requires both source files from a local repo and third-party source files or files from another StarlingX repository. This file is used to create a different build root directory and copy both the external sources and local repo source files to that location prior to the build.

meta_data.yaml

The meta_data.yaml file contains information that describes the package to the build system. It consists of several fields:

   debver (mandatory) - Contains the package version. For Debian packages, you can run “apt-cache madison package-name” to get the package version. For example, the systemd the package in Debian Bullseye is 247.3-3. For third party and StarlingX packages, the debver must be specified manually.

   debname (optional) - Contains the name of the Debian package. Most packages have a uniform name for both Centos and Debian, in which case the field isn't required. If it is not specified, the build system will use the last folder name.

deb_folder

The deb_folder contains all of the Debian package build files. It corresponds to the debian folder of a native Debian package. For native Debian packages, the build system inherits the debian folder from the Debian upstream package. If a complete debian folder is included in this directory, the build system will use it to override the upstream debian folder. For 3rd party and StarlingX packages, a complete debian folder must be provided. The build system will copy this folder to the build directory.

The following table lists the most common files in a debian folder, along with a brief description and a link to the Debian documentation for each file.

deb_patches

This folder contains the patches to apply to the debian folder of an upstream Debian package. For example, if you want to modify the debian/rules file of a Debian upstream package, put the patch here and add it to the series file. This folder is not needed for 3rd party and StarlingX packages.

patches

This folder contains the patches that are applied to the source code of a Debian upstream package. A developer can also drop a patch into this directory with a series file to apply a patch to the source code of a Debian package. The series file will be appended to an existing debian/patches/series. For 3rd party and StarlingX packages it is not needed.

Examples

Examples of reviews which add Debian packaging to various StarlingX repositories can be found via this query.