Understanding the parameters used by livecd-rootfs
==================================================

livecd-rootfs is a confusing codebase. One of the confusing things is
how information flows into and around the image build process. There
is IMAGEFORMAT and IMAGE_TARGETS and PROJECT and many other
variables. It is not obvious when looking at the code if a given
variable is something passed as a parameter or something derived from
it.

All (or almost all) production use of livecd-rootfs is via
launchpad-buildd so the set of potential parameters is limited by the
set of environment variables launchpad-build can set in response to
the build request. These variables can be set for both lb config and
lb build:

 PROJECT
 ARCH
 SUBPROJECT
 SUBARCH
 CHANNEL
 IMAGE_TARGETS
 REPO_SNAPSHOT_STAMP
 SNAPSHOT_SERVICE_TIMESTAMP
 COHORT_KEY
 http_proxy / HTTP_PROXY / LB_APT_HTTP_PROXY

In addition the following variables can be set for lb config only (why
are some things set for lb config only? no idea):

 SUITE
 NOW
 IMAGEFORMAT
 PROPOSED
 EXTRA_PPAS
 EXTRA_SNAPS

Here is an opinionated and slightly angry attempt to describe what
each of these is for:

PROJECT
-------

This is the big one, the main variable that defines what is being
built. It can be ubuntu, ubuntu-server, xubuntu, ubuntu-mini-iso, that
sort of thing. Generally PROJECT determines the set of packages
installed but it (unfortunately?) has a bit more impact than that.

It's unarguable that we need a parameter like this.

ARCH
----

The architecture being built for. This is always the same as `dpkg
--print-architecture` for us, we don't do any cross builds.

It's kind of redundant but it's not really a problem that this exists.

SUBPROJECT
----------

This is used for some builds to build a different sort of build of the
project. It can be set to:

 * "minimized" for ubuntu-cpc builds to make a minimal cloud image
 * "minimal" for xubuntu builds to make a smaller ISO
 * "desktop-preinstalled" for ubuntu builds to make a preinstalled
   image instead of the parts for an installer.
 * "buildd" for images to be used as build images by craft tools, and also
   buildd chroots used on launchpad builders?
 * "live" for ubuntu-server builds, historically to distinguish d-i
   style installers from subiquity style installers
 * "desktop" for ubuntu-core-installer builds, to influence which
   model is use to build the ubuntu core system that will be
   installed.

_This_ parameter is a total mess. The desktop-preinstalled use feels
particularly egregious.

SUBARCH
-------

This identifies the target machine more specifically than ARCH,
e.g. "tegra-jetson" or "licheerv". Used mostly but not exclusively for
preinstalled builds.

We probably do need something like this.

CHANNEL
-------

Influences which channel snaps included in the build are taken from
(via a few different mechanisms).

IMAGE_TARGETS
-------------

Passed for CPC (and ubuntu-oem, for some reason) builds to
`config/hooks.d/make-hooks` which uses it to select which binary hooks
to run (and so determines which artifacts get produced).

It is probably reasonable that this exists.

REPO_SNAPSHOT_STAMP
-------------------

Currently unused.

SNAPSHOT_SERVICE_TIMESTAMP
--------------------------

Also currently unused, and unclear how it differs from
REPO_SNAPSHOT_STAMP.

COHORT_KEY
----------

Used to make sure that different builds run at the same time don't get
different versions of snaps due to phasing differences.

This is a totally valid thing to need to supply.

http_proxy / HTTP_PROXY / LB_APT_HTTP_PROXY
-------------------------------------------

Nothing complex here!

SUITE
-----

This is the series being built (e.g. noble, questing). It is misnamed
really -- a suite is usually a combination of a series and a pocket
(noble-proposed, questing-security).

As with ARCH this is sort of redundant as we do builds in a chroot of
the series being built but OTOH it is definitely information the
build needs to know!

NOW
---

The serial for the build, e.g. 20250519 or 20240418.4.

It is a totally reasonable parameter.

IMAGEFORMAT
-----------

This is one of the more incoherently handled parameters. In rough
outline it is the filesystem of the image we produce, but relatively
few builds produce raw images so _mostly_ it is set to 'plain' (which
causes live-build to just leave the rootfs as a directory tree) or
'none' (which causes live-build to do roughly the same thing but in a
different way?).

It can be set when starting an image build, but most builds do not and
the behavior when it is not set explicitly is pretty confusing.

This place is not a place of honor.

PROPOSED
--------

Should packages from proposed by included?

This is not really as useful as it used to be for a bunch of reasons
but it conceptually makes sense.

EXTRA_PPAS
----------

Extra archives to get packages from.

Production builds shouldn't really use this but it's definitely useful
for development.

EXTRA_SNAPS
-----------

Extra snaps to include (but only for ubuntu-image based builds).