StarlingX/DebianBuildStructure
Contents
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 sha256sum: xxxxxx dl_files: AAA.tar.gz: topdir: BBB url: https://xxx/AAA.tar.gz md5sum: xxxx sha256sum: xxxxxx CCC.tar.gz: topdir: DDD url: https://xxx/CCC.tar.gz md5sum: xxx sha256sum: xxxxxx 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: FILES_GITREVCOUNT: - githash1 - githash2 - githash3 GITREVCOUNT: SRC_DIR: 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", "sha256sum". An example of dl_path of 3rd part package meta_data.yaml, and an example of dl_path of Debian native package 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 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 meta_data.yaml. The source codes locations is integ/kubernetes/k8s-pod-recovery/centos/files.
NOTE: dl_path, archive and src_path are mutually exclusive, one and only of them can exist in a meta_data.yaml.
dl_files (optional) - Contains the download information for the additional files if needed, besides the source codes getting through dl_path, src_path, or archive. The download folder of dl_files is the source codes directory in build directory. It has 3 sub-fields, "topdir" is the top directory name after untar, that is same with the second field of each line (separator is #) in centos_tarball-dl.lst. Set "topdir" to null if don't want to change the top directory, or the download file is not a tar ball. "url" and "md5sum" are same with "dl_path". An example meta_data.yaml.
src_files (optional) - Contains the path of local files, which is outside src_path. It can be abs path or relative path to package folder and also supports environment variable. The copy to folder of src_files is the source codes directory in build directory. An example meta_data.yaml
revision (mandatory) - Contains the components to make up package's revision. "dist" is a short name of the distribution appends to the package version. The default value is the environment variable "$STX_DIST". PKG_GITREVCOUNT counts git revisions relative to package's debian folder, optionally only count from PKG_BASE_SRCREV. The simplest setting of revision is meta_data.yaml. SRC_GITREVCOUNT counts git revisions relative to package's source codes folder(The folder defined in "src_path"), only count from SRC_BASE_SRCREV, for example: ====== revision: dist: $STX_DIST PKG_GITREVCOUNT: true SRC_GITREVCOUNT: SRC_BASE_SRCREV: 48a2e836ffc983c68283a6cfe7666228cee140f7 ====== GITREVCOUNT counts git revisions relative to package's source git repository. SRC_DIR and BASE_SRCREV is needed if GITREVCOUNT is defined. SRC_DIR points to package's source git repository, and BASE_SRCREV is the base commit to count, for example: ====== revision: dist: $STX_DIST PKG_GITREVCOUNT: true GITREVCOUNT: SRC_DIR: ${STX_GIT_SRC_DIR}/ceph BASE_SRCREV: ca74598065096e6fcbd8433c8779a2be0c889351 ======
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.
