Difference between revisions of "StarlingX/DebianBuildStructure"
Line 84: | Line 84: | ||
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. | 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 information | + | 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 | ||
== deb_folder == | == deb_folder == |
Revision as of 06:36, 2 December 2021
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 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
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.