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. The following example shows a full meta_data.yaml structure.

 debver: 
 debname: 
 dl_hook:
 dl_path:
   name: DEF.tar.gz
   url: https://xxx/ABC.tar.gz
   md5sum: xxx
 dl_files:
   AAA.tar.gz:
     topdir: BBB
     url: https://xxx/AAA.tar.gz
     md5sum: xxxx
   CCC.tar.gz:
     topdir: DDD
     url: https://xxx/CCC.tar.gz
     md5sum: xxx
 src_path:
 src_files:
 - AAA/BBB/CCC
 - DDD/EEE/FFF
 - GGG/HHH/III
 archive:
 revision:
   dist: $STX_DIST
   PKG_GITREVCOUNT:
   PKG_BASE_SRCREV:
   SRC_GITREVCOUNT:
   SRC_BASE_SRCREV:

   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.

   dl_path(needed by 3rd part and Debian native package) - Contains the download information of the tar ball of source codes. It has 3 sub-fields: "name" is the name of local tar ball file, "url" is the upstream link of source codes tar ball, and "md5sum". An example of dl_path of 3rd part package is https://review.opendev.org/c/starlingx/integ/+/809517/7/base/pf-bb-config/debian/meta_data.yaml, and an example of dl_path of Debian native package is https://review.opendev.org/c/starlingx/integ/+/810563/12/base/base-passwd/debian/meta_data.yaml

   archive(needed by Debian native package) - Contains the download url of the .dsc, .orig.tar.xx, .debian.tar.xx of a Debian native package. The url link is end with the last folder name, not specific file. An example of archive is https://review.opendev.org/c/starlingx/integ/+/819591/1/kubernetes/docker-distribution/debian/meta_data.yaml.

   src_path(needed by a package with local source codes) - Contains abs path or relative path to the package folder. It also supports environment variable. As example is https://review.opendev.org/c/starlingx/integ/+/818211/1/kubernetes/k8s-pod-recovery/debian/meta_data.yaml. The source codes locations is integ/kubernetes/k8s-pod-recovery/centos/files.

   dl_path, archive and src_path are mutually exclusive, only one of them can exist in a meta_data.yaml

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.

File	Mandatory	Description
changelog	Yes	Contains the version information, distribution and urgency of the package.
compat	Yes	Defines the debhelper compatibility level.
control	Yes	Contains the definitions of the .deb files which comprise the Debian package.
copyright	No	Contains copyright and license information for the upstream sources included in the package.
patches/*	No	Contains copyright and license information for the upstream sources included in the package.
rules	Yes	Contains the build rules for the package.
source/format	Yes	Contains the desired format for the package.
watch	No	Contains the desired format for the package.

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.

StarlingX/DebianBuildStructure

Contents