StarlingX/CentosToDebian
Contents
Overview
The purpose of this wiki is to provide some guidance for converting a CentOS package to a Debian package.
CentOS Package Files
There are two main files which specify the CentOS build of a package:
- build_srpm.data - Specifies the input sources for the build (both within and external to the package repository).
- <packageName>.spec - Specification file which defines the package(s), dependencies, build rules and install rules.
These files are found in the "centos" directory which is generally a top-level directory in the root package directory. For example:
- Repository: nfv
- Package directory: nfv/nova-api-proxy
- CentOS build directory: nfv/nova-api-proxy/centos
The "debian" build directory is a peer of the "centos" directory (i.e. nfv/nova-api-proxy/debian).
build_srpm.data
The build_srpm.data file defines the source inputs for the package build. The inputs may be files from the package repo itself, files from another repo or files from a download mirror.
The following variables are commonly used for these inputs:
- CGCS_BASE - An import mirror (/import/mirrors/starlingx).
- PKG_BASE - The root package directory.
- STX_BASE - The root directory for all StarlingX repositories.
Specification File
The specification file drives the CentOS package build. It contains two main sections:
- Preamble - Defines metadata for the build.
- Body - Contains the build instructions.
The following table describes the commonly used fields (SPEC directives) in the specification file.
| Directive | Type | Description |
|---|---|---|
| Summary | Preamble | A brief description of the package. |
| Name | Preamble | The name of the package. |
| Version | Preamble | The current version of the package. |
| Source* | Preamble | Specifies a source file for the build. |
| BuildRequires | Preamble | Specifies a dependency for the package. |
| Requires | Preamble | Specifies a dependency for the package. |
| %package | Body | Defines an RPM file to be built. This is used if multiple RPMs are built from the SPEC file. |
| %description | Body | A detailed description of the package |
| %prep | Body | Steps for preparing the software to be built. This might include extracting a tar file of upstream source code, for example. |
| %build | Body | Specifies the rules to build the software of the package. |
| %install | Body | Specifies the install rules for the package. Files are copied from the build directory to the directory structure containing the files to be installed. |
| %files | Body | Defines the files to be installed on a a system when the package is installed |
Mapping a CentOS Specification file to Debian Build Files
The following table shows at a high level how to map sections of Centos .spec:
| Centos Specification File Section | Debian Build Files |
|---|---|
| Name | meta_data.yml - debname |
| Version | meta_data.yml - debver |
| BuildRequires | control - Build-Depends |
| Requires | control - Per package Depends |
| %description | control - Per package Description |
| %build | rules |
| %global | rules |
| %install | rules |
| %files | *.install |
Creating the Debian Package Files
Files in the deban Directory
'meta_data.yaml
Most of the meta_data.yaml file contents are the same for all packages. You will need to set the following fields:
- debname: The name of the package. This matches the package directory in the target repository.
- debver: The package version.
- src_path: The path to the source code for the package (relative to the directory that contains the debian directory).
---
debname: mtce-storage
debver: 1.0
src_path: src
revision:
dist: $STX_DIST
PKG_GITREVCOUNT: true
If you encounter a package that has multiple top-level source code directories or one that uses third party files or files from another repo, a single source path cannot be specified. In this case, a dl_hook script file is used to copy any required sources to a custom build root prior to building the package. This file is described in the next section.
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. A meta_data.yaml file which refers to a dl_hook script is shown below.
--- debname: nfv debver: 1.0 dl_hook: dl_hook revision: dist: $STX_DIST PKG_GITREVCOUNT: true
An example dl_hook script file is shown below. It copies sources from various directories into a custom build root directory.
#!/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}/nfv/nfv)
mkdir ${PKG_BUILD_NAME}
pushd ${PKG_BUILD_NAME}
cp -pr ${SRC}/nfv-* ${PKG_BUILD_ROOT}/
Files in the deb_folder Directory
changelog
The changelog file contains a version history for the package.
A new changelog file can be created using the command "dch --create". This command must be issued in the root package directory where the debian folder resides.
This command will pop up an editor with the text shown below.
PACKAGE (VERSION) UNRELEASED; urgency=medium * Initial release. (Closes: #XXXXXX) -- STX Builder <stx.builder@opendev.org> Fri, 29 Oct 2021 18:22:14 +0000
tsconfig (1.0-1) unstable; urgency=medium * Initial release. -- Chuck Short <charles.short@windriver.com> Sun, 08 Aug 2021 12:14:46 -0400
compat"
The compat file is used to specify the debhelper compatibility level for the package build. This file is optional. The debhelper version is also specified in the control file in the build dependencies.
control
The control file is where the packages and their dependencies are defined. The control file has a header section and one or more package sections.
For more information on the control file, refer to the Control File section of the Debian maintainers' guide.
An example header section is shown below.
Source: nfv Section: libs Priority: optional Maintainer: StarlingX Developers <starlingx-discuss@lists.starlingx.io> Build-Depends: debhelper-compat (= 13), dh-python, python3-all, python3-requests, python3-setuptools Standards-Version: 4.5.1 Homepage: https://www.starlingx.io
