Skip to content

packages.md

Latest commit

 

History

History
137 lines (111 loc) · 5.39 KB

packages.md

File metadata and controls

137 lines (111 loc) · 5.39 KB

Building the packages

This repository contains three services - aziot-certd, aziot-identityd and aziot-keyd - as well as the libaziot_keys.so library. These four components ship in a single distro package named aziot-identity-service. The package can be built for a particular distro and a particular architecture by running the /ci/package.sh script in a Docker container of that distro, with an environment variable set to identify the architecture to build the packages for.

Distro Docker image
CentOS 7 centos:7
RHEL 8 compatible redhat/ubi8:latest
Debian 9 / Raspberry Pi OS 9 debian:9-slim
Debian 10 / Raspberry Pi OS 10 debian:10-slim
Debian 11 / Raspberry Pi OS 11 debian:11-slim
Ubuntu 18.04 ubuntu:18.04
Ubuntu 20.04 ubuntu:20.04
Architecture ARCH env var
x86_64 / amd64 amd64
ARM32 v7 / armv7-gnueabihf arm32v7
ARM64 v8 / AARCH64 / aarch64-gnu aarch64

In addition, the script also needs the PACKAGE_VERSION and PACKAGE_RELEASE environment variables to be set, which control the version and release (for RPM packages) / revision (for Debian packages) number of the generated package.

Finally, the script expects the source directory to be at /src, and will create the packages under /src/packages.

For an example to put it all together, let's say you want to build the RHEL 8-compatible package for x86_64, with version 1.2.0 and release 0, ie the package version is 1.2.0-0. Let's say your clone of this repository is at ~/src/iot-identity-service. You would run:

docker run -it --rm \
    -v "$(realpath ~/src/iot-identity-service):/src" \
    -e 'ARCH=amd64' \
    -e 'PACKAGE_VERSION=1.2.0' \
    -e 'PACKAGE_RELEASE=0' \
    redhat/ubi8:latest \
    '/src/ci/package.sh'

and at the end you would have these files under ~/src/iot-identity-service/packages:

el8/amd64/aziot-identity-service-1.2.0-0.src.rpm
el8/amd64/aziot-identity-service-1.2.0-0.x86_64.rpm
el8/amd64/aziot-identity-service-debuginfo-1.2.0-0.x86_64.rpm
el8/amd64/aziot-identity-service-devel-1.2.0-0.x86_64.rpm

These files in order are:

  1. The source package. This contains the contents of this repository but pre-processed for CentOS 7-specific customizations. The other packages were built from this package.
  2. The binary package. This is the package a user would install on their device.
  3. The debug symbols package. A developer would need this package to debug coredumps generated from services in the corresponding binary package.
  4. A devel package containing the aziot-keys.h C header, which contains the API definitions of libaziot_keys.so. A user would install this package if they wanted to make their own implementation of libaziot_keys.so. It's not needed for a production device.

For another example, let's say you want to build the Debian 11 package for ARM32, with version 1.2.0 and revision 0, ie the package version is 1.2.0-0. You would run:

docker run -it --rm \
    -v "$(realpath ~/src/iot-identity-service):/src" \
    -e 'ARCH=arm32v7' \
    -e 'PACKAGE_VERSION=1.2.0' \
    -e 'PACKAGE_RELEASE=0' \
    debian:11-slim \
    '/src/ci/package.sh'

and at the end you would have these files under ~/src/iot-identity-service/packages:

debian11/arm32v7/aziot-identity-service_1.2.0-0_armhf.deb
debian11/arm32v7/aziot-identity-service_1.2.0-0.debian.tar.xz
debian11/arm32v7/aziot-identity-service_1.2.0-0.dsc
debian11/arm32v7/aziot-identity-service_1.2.0.orig.tar.gz
debian11/arm32v7/aziot-identity-service-dbgsym_1.2.0-0_armhf.deb

The first file is the binary package, the second through fourth file together constitute the source package, and the fifth is the debug symbols package. The meanings are the same as the CentOS example. Note that there is no -dev package equivalent of the CentOS -devel package; the C header is included in the binary package.

Miscellaneous

  1. Make sure to run the script in a Docker container instead of directly on your machine, even if your machine happens to be the same distro as the one you want to build the package for. The script installs dependencies and modifies system files like /etc/apt, so you don't want these to be done to your host machine.

  2. The script must be run on an x86_64 host, even for building ARM32 and ARM64 packages. The ARM32 and ARM64 packages are built via cross-compilation.

  3. Building ARM32 and ARM64 packages for CentOS 7 is currently not supported, because CentOS 7 does do not have functional cross compilers for those architectures. (It has the gcc cross compiler itself but not a cross glibc for the compiled binary to link to, because the cross compiler is only intended for cross-compiling the kernel.)

  4. Building ARM32 and ARM64 packages for RHEL 8 is currently not supported. More investigation would be required to determine feasibility.

  5. The packages script is also run in our CI, via the .github/workflows/packages.yaml file.