diskimage-builder

History

Ian Wienand 97c01e48ed Move elements & lib relative to diskimage_builder package Currently we have all our elements and library files in a top-level directory and install them into <root>/share/diskimage-builder/[elements\|lib] (where root is either / or the root of a virtualenv). The problem with this is that editable/development installs (pip -e) do not install data_files. Thus we have no canonical location to look for elements -- leading to the various odd things we do such as a whole bunch of guessing at the top of disk-image-create and having a special test-loader in tests/test_elements.py so we can run python unit tests on those elements that have it. data_files is really the wrong thing to use for what are essentially assets of the program. data_files install works well for things like config-files, init.d files or dropping documentation files. By moving the elements under the diskimage_builder package, we always know where they are relative to where we import from. In fact, pkg_resources has an api for this which we wrap in the new diskimage_builder/paths.py helper [1]. We use this helper to find the correct path in the couple of places we need to find the base-elements dir, and for the paths to import the library shell functions. Elements such as svc-map and pkg-map include python unit-tests, which we do not need tests/test_elements.py to special-case load any more. They just get found automatically by the normal subunit loader. I have a follow-on change (I69ca3d26fede0506a6353c077c69f735c8d84d28) to move disk-image-create to a regular python entry-point. Unfortunately, this has to move to work with setuptools. You'd think a symlink under diskimage_builder/[elements\|lib] would work, but it doesn't. [1] this API handles stuff like getting files out of .zip archive modules, which we don't do. Essentially for us it's returning __file__. Change-Id: I5e3e3c97f385b1a4ff2031a161a55b231895df5b		2016-11-01 17:27:41 -07:00
..
environment.d	Move elements & lib relative to diskimage_builder package	2016-11-01 17:27:41 -07:00
pre-install.d	Move elements & lib relative to diskimage_builder package	2016-11-01 17:27:41 -07:00
test-elements	Move elements & lib relative to diskimage_builder package	2016-11-01 17:27:41 -07:00
element-deps	Move elements & lib relative to diskimage_builder package	2016-11-01 17:27:41 -07:00
element-provides	Move elements & lib relative to diskimage_builder package	2016-11-01 17:27:41 -07:00
package-installs.yaml	Move elements & lib relative to diskimage_builder package	2016-11-01 17:27:41 -07:00
pkg-map	Move elements & lib relative to diskimage_builder package	2016-11-01 17:27:41 -07:00
README.rst	Move elements & lib relative to diskimage_builder package	2016-11-01 17:27:41 -07:00

README.rst

==============
debian-minimal
==============

Create a minimal image based on Debian. We default to unstable but `DIB_RELEASE`
can be set to any series of Debian.

There are two ways to configure apt-sources:

1. Using the standard way of defining the default, backports, updates
   and security repositories is the default. In this case you can
   overwrite the two environment variables to adapt the behavior:
   `DIB_DISTRIBUTION_MIRROR`: the mirror to use
      default: http://ftp.us.debian.org/debian
   `DIB_DEBIAN_COMPONENTS`: (default) `main`
      a comma separated list of components. For Debian this can be
      e.g. `main,contrib,non-free`.

   Note it is not recommended to use http://httpredir.debian.org/ for
   `DIB_DISTRIBUTION_MIRROR` due to how unreliable it is.  Be sure to
   select a mirror from the official mirror list:

       https://www.debian.org/mirror/list

   By default only `main` component is used. If
   `DIB_DEBIAN_COMPONENTS` (comma separated) from the `debootstrap`
   element has been set, that list of components will be used instead.

   Backports, updates and security are included unless `DIB_RELEASE`
   is `unstable`.

2. Complete configuration given in the variable
   `DIB_APT_SOURCES_CONF`.
   Each line contains exactly one entry for the sources.list.d
   directory.
   The first word must be the logical name (which is used as file name
   with `.list` automatically appended), followed by a colon `:`,
   followed by the complete repository specification.
   Example:
   DIB_APT_SOURCES_CONF=\
       "default:deb http://10.0.0.10/ stretch main contrib
        mysecurity:deb http://10.0.0.10/ stretch-security main contrib"

If necessary, a custom apt keyring and debootstrap script can be
supplied to the `debootstrap` command via `DIB_APT_KEYRING` and
`DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` respectively. Both options require the
use of absolute rather than relative paths.

Use of this element will also require the tool 'debootstrap' to be
available on your system. It should be available on Ubuntu, Debian,
and Fedora. It is also recommended that the 'debian-keyring' package
be installed.

The `DIB_OFFLINE` or more specific `DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE`
variables can be set to prefer the use of a pre-cached root filesystem
tarball.

The `DIB_DEBOOTSTRAP_EXTRA_ARGS` environment variable may be used to
pass extra arguments to the debootstrap command used to create the
base filesystem image. If --keyring is is used in `DIB_DEBOOTSTRAP_EXTRA_ARGS`,
it will override `DIB_APT_KEYRING` if that is used as well.

For further information about `DIB_DEBIAN_DEBOOTSTRAP_SCRIPT` ,
`DIB_DEBIAN_USE_DEBOOTSTRAP_CACHE` and `DIB_DEBOOTSTRAP_EXTRA_ARGS`
please consult "README.rst" of the debootstrap element.

-------------------
Note on ARM systems
-------------------

Because there is not a one-to-one mapping of `ARCH` to a kernel package, if
you are building an image for ARM on debian, you need to specify which kernel
you want in the environment variable `DIB_ARM_KERNEL`. For instance, if you want
the `linux-image-mx5` package installed, set `DIB_ARM_KERNEL` to `mx5`.