# Contrail VNC Debian Packaging Changes

Initial changes to the Contrail VNC packaging for Debian to modernize it and make it a bit more manageable.

## Changes description

Most of the changes outside of *debian/rules* and *debian/control* are fairly small - the packaging logic is contained in those two files.

### debian/rules and debian/control changes

*debian/rules* is a *Makefile* that all debian packaging executes, one step at the time, to clean, build, install [^1] and create source & binary packages. *debian/control* is the description of the package — what has to be installed in order to build & package it, what binary packages to create and their metadata (extra dependencies, relation with other packages etc.)

[^1]: Installation is done to a temporary directory under *debian/*

#### debian/control changes

In the current workflow, before we even get to package building, a separate *Makefile* `packages.make` is used to substitute various templated variables with correct text - we add per-release build and install-time dependencies:

* *BUILDDEP_SERIES* is replaced with a combination of dependencies, based on the target system, but it can be removed for master - the two main sticking points is installing `dh-systemd` only on *xenial* (which is fine but not required - the package exists on both *trusty* and *xenial* and debhelper will handle a situation when trusty has no systemd installed/running) and installing a bunch of dependencies only on trusty+ — that's probably required to support precise, but a) we are probably not going to be building 5.0+ for precise and b) going forward, this is not the right way to do that anyway - if that requirement shows up again, we should backport required packages from 18.04 to 16.04 and 14.04 as needed.
* SUPERVISORDEP_SERIES is used to add an install-time dependency on supervisor for many packages — this can be better supported by usage of a variable `${dist:Depends}` that can be then populated in *debian/rules*.
* NODEMGRDEP_SERIES adds xenial-only dependencies for nodemgr packages on python-dbus — that can be handled the same way we handle supervisor dependency, through *debian/rules* code.

I've added a number of packages to the Build-Depends list, so that they can be properly installed before the build, without depending on pre-installed packages.[^2] I'm also bumping debhelper dependency, and adding dh-exec package - that will come up handy later, when we get to the *.install* and *.dirs* files.

#### debian/rules changes

In *debian/rules* I'm fixing the `INSTALL_ROOT` variable to ensure that files are always installed in the correct location, not depending on $PWD as well as add code to support `${dist:Depends}` and `${dbus:Depends}`[^3]:

```Makefile
VER := $(shell awk -F"=" '$$1 == "DISTRIB_CODENAME" {print $$NF}' /etc/lsb-release)
ifeq ($(findstring xenial,$(VER)),xenial)
        SUBSTVARS += -Vdbus:Depends="dbus, python-pydbus (>= 0.7.0)"
        DH_WITH=python2,systemd
else
        SUBSTVARS = -Vdist:Depends="supervisor"
        DH_WITH=python2
endif
```

as well as adding code to support parallel building, based on debhelper variable (*DEB_BUILD_OPTIONS*):

```makefile
ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
        JOBS = -j$(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
else
        JOBS =
endif
```

I've also added a target to generate source tarball (which is a semi-hard requirement of the build process and is called **get-orig-source** by convention):

```makefile
get-orig-source:
        (cd ${SB_TOP}/third_party/ && python fetch_packages.py)
        tar zcf contrail_${DEB_UPSTREAM_VERSION}.orig.tar.gz \
                controller vrouter third_party tools/build tools/generateds \
                openstack/nova_contrail_vif openstack/nova_extensions \
                tools/sandesh SConstruct
```

Then, there are couple of changes to other targets:

In `override_dh_auto_clean` we make sure that all files created by the SCons, to make debuild happy [^3]

[^2]: contrail-build scripts install a number of java libraries, are they required for anything but VCenter builds? Java itself is needed for testing.

[^3]: Debian considers it an error if any file found in the source package is modified during the build process.

### debian/\*.install and debian/\*.dirs

All those files have been made executable, and debhelper exetures a command from *shebang* to process them, creating a per-release variants on the fly:
- All comments are stripped out
- Each line with [ubuntu-${release}] is present only when package is being built for the ${release}.

### debian/source/options

A number of settings telling debian packaging utilities how to generate and validate source package.

Debian has a strict policy of not modifying files that come from the source package during build - *debian/source/options* lets you tweak this policy by telling debian tools to ignore some of the files/folders. We use that to ignore *.git/* and *.repo/* as well as a bunch of folders that come from our "sandbox" but are not part of the Contrail VNC source package.

### debian/dh-exec/

Scripts that are used to generate per-release \*.install and \*.dirs files:
- *dh-exec-filter-arch-ex* — Filter lines by matching current Ubuntu release with tags
- *dh-exec-filter-comments* — Remove all lines starting with *#*