# Building Debian packages with Ick

This chapter describes how to actually use Ick to build Debian
packages. We'll use Ick to actually build a toy package. This assumes
we have the necessary access to localhost.

## Single repository and branch ("a la liw")

First, we'll do a simple case where the Debian packaging and the
upstream source code are kept in one repository and branch.

    SCENARIO build Debian packages from one branch

First of all, we need a git repository with some source code.

    GIVEN a source code repository for project foo version 3.2-1

Then we need an Ick file.

    GIVEN an ick file foo.ick containing
    ... {
    ...     "state": "foo.state",
    ...     "targets": {
    ...         "ci_unstable": {
    ...             "address": "$ICK_UNSTABLE_TEST_TARGET",
    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/ci.tgz"
    ...         },
    ...         "release_jessie": {
    ...             "address": "$ICK_JESSIE_TEST_TARGET",
    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/release.tgz"
    ...         },
    ...         "release_unstable": {
    ...             "address": "$ICK_UNSTABLE_TEST_TARGET",
    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/release.tgz"
    ...         }
    ...     },
    ...     "projects": {
    ...         "foo": {
    ...             "git": "foo",
    ...             "branch": "master",
    ...             "pipelines": ["debian-ci", "debian-release"]
    ...         }
    ...     }
    ... }

Then we do the build.

    WHEN user runs ick foo.ick

As a result, there's several resulting packages that should exist.
First of all, a CI build for unstable:

    THEN the APT repository for foo.ick contains
    ... foo_3.2.0ci1-1.unstable.dsc
    THEN the APT repository for foo.ick contains
    ... foo_3.2.0ci1-1.unstable_all.deb

We tag a release and build it. Because our test package is
architecture independent, there aren't versions for each architecture
separately.

    GIVEN a git tag foo-3.2 on tip of master in foo
    WHEN user runs ick foo.ick
    THEN the APT repository for foo.ick contains foo_3.2-1.dsc
    THEN the APT repository for foo.ick contains foo_3.2-1_all.deb
    THEN the APT repository for foo.ick contains foo_3.2-1.debian8*.dsc
    THEN the APT repository for foo.ick contains foo_3.2-1.debian8*_all.deb

## Separate repositories for upstream code and package ("a la Daniel")

Some people prefer to keep Debian packaging and upstream code
entirely separate. In this case, the repository with packaging
contains only the packaging, and it contains the contents of the
`debian` directory, not the directory itself. In other words, the
repository contains `changelog` and `rules`, not `debian/changelog`
and `debian/rules`.

To accomodate this, Ick allows a project to specify any number of git
repositories and branches that are stitched together to form a source
tree.

    SCENARIO build Debian packages from separate repositories

First of all, we need a git repository with some upstream source code,
but no packaging, and a separate repository with the corresponding
packaging.

    GIVEN an upstream source repository for project foo
    AND a packaging repository called deb for project foo version 3.2-1

Then we need an Ick file.

    GIVEN an ick file foo.ick containing
    ... {
    ...     "state": "foo.state",
    ...     "targets": {
    ...         "ci_unstable": {
    ...             "address": "$ICK_UNSTABLE_TEST_TARGET",
    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/ci.tgz"
    ...         },
    ...         "release_jessie": {
    ...             "address": "$ICK_JESSIE_TEST_TARGET",
    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/release.tgz"
    ...         },
    ...         "release_unstable": {
    ...             "address": "$ICK_UNSTABLE_TEST_TARGET",
    ...             "pbuilder-ci-tgz": "/var/cache/pbuilder/release.tgz"
    ...         }
    ...     },
    ...     "projects": {
    ...         "foo": {
    ...             "gits": [
    ...                 { "git": "foo", "branch": "master", "root": "." },
    ...                 { "git": "deb", "branch": "master", "root": "debian" }
    ...             ],
    ...             "pipelines": ["debian-ci", "debian-release"]
    ...         }
    ...     }
    ... }

Then we do the build.

    WHEN user runs ick foo.ick

As a result, there's several resulting packages that should exist.
First of all, a CI build for unstable:

    THEN the APT repository for foo.ick contains 
    ... foo_3.2.0ci1-1.unstable.dsc
    THEN the APT repository for foo.ick contains 
    ... foo_3.2.0ci1-1.unstable_all.deb

We tag a release and build it. Because our test package is
architecture independent, there aren't versions for each architecture
separately.

    GIVEN a git tag foo-3.2 on tip of master in foo
    WHEN user runs ick foo.ick
    THEN the APT repository for foo.ick contains foo_3.2-1.dsc
    THEN the APT repository for foo.ick contains foo_3.2-1_all.deb
    THEN the APT repository for foo.ick contains foo_3.2-1.debian8*.dsc
    THEN the APT repository for foo.ick contains foo_3.2-1.debian8*_all.deb