The Devuan SDK more in-depth
============================

The following parts will explain the Devuan SDK more technically. It
will show its configuration, important functions, and show how it all
glues together.


Configuration
-------------

Much of the _libdevuansdk_ configuration is done in
`libdevuansdk/config`.  Here you can edit the defaults if you wish to
do something your needs are expressing. However, overriding these
through upper levels is recommended.


### `config` file

`vars` and `arrs` are global arrays for holding other global variables
and arrays, respectively. This is required for `zuper` and helps a lot
with debugging. If you declare new variables or arrays, add them to the
aforementioned variables.


* `os` holds the name of the distribution being worked on.

* `release` holds the release codename of the distribution. Used for apt
  repositories mostly.

* `version` is the version of the distribution being worked on.

* `mirror` is a mirror holding the required packages for `debootstrap`.

* `section` are the sections of the repository. For adding in
  `/etc/apt/sources.list`. Separate them with whitespaces.

* `image_name` is the output name of the raw image. If you declare a
  blend or a device name (arm-sdk), they will be appended to this name.

* `rootcredentials` and `usercredentials` are currently placeholders.

* `core_packages` is an array holding the core packages that will be
  installed in the bootstrap process.

* `base_packages` is an array holding the base packages that will be
  installed at a later point in the bootstrap process.

* `purge_packages` is an array of packages that will get purged at the
  end of the bootstrap process.


Helper functions
----------------

You can find useful helper functions in `libdevuansdk/zlibs/helpers`.
They are intended to help when it comes to writing wrappers, as well
as making the developers' jobs easier for developing
_libdevuansdk_. Some of these functions are required for
_libdevuansdk_ to work properly as well.


### `build_image_dist()`

This function is a kind of a wrapper function. It's used in _arm-sdk_
to build a complete dd-able image from start to end. To run, it
requires `$arch`, `$size`, `$parted_type`, `$workdir`, `$strapdir`,
and `$image_name` to be declared. See the section dedicated to
"Creating wrappers" for insight on these variables.

The workflow of this function is bootstrapping a complete _rootfs_,
creating a raw image, installing/compiling a kernel, rsyncing
everything to the raw image, and finally compressing the raw image.

This same workflow is applied in the next two functions in this file,
which are `build_iso_dist` and `build_vagrant_dist`. To get a better
understanding of _libdevuansdk_, it's recommended to go through one of
these functions and following it deeper to find and figure out the
other functions and how they work together.


### `devprocsys()`

This function is a simple helper function that takes two arguments. It
mounts or unmounts `/dev`, `/proc`, and `/sys` filesystems to or from
wherever you tell it to. For example:

```
$ devprocsys mount $strapdir
$ devprocsys umount $strapdir

```

It is very necessary to use this if one wants to do anything requiring
access to hardware or the system's resources, i.e. cryptography.


### `dpkgdivert()`

This function, like `devprocsys` takes two arguments and will create
or remove a dpkg diversion in the place you tell it to and remove
`invoke-rc.d` so that _apt_ does not autostart daemons when they are
installed.


### `chroot-script()`

This very useful functions allows you to _chroot_ into `$strapdir` and
execute the script/binary that's passed as a parameter to this
function.  It also takes an optional argument `-d` that will call
`dpkgdivert` on and off before and after execution.

The `chroot-script` is also an example on its own that shows how to use
the `chroot-script` function.


Mandatory variables
-------------------

* `$R` is the root directory of a wrapper. It's defined already in all
  the existing ones. In almost evert situation it can be `$PWD`.

* `$workdir` is the working directory of the current build. A sane
  default is `$R/tmp/workdir`

* `$strapdir` is the bootstrap directory of the build. It holds the
  rootfs when you debootstrap it, and customize it further on. Default
  is `$workdir/rootfs`.

* `$arch` is the CPU architecture of the build. I.e. `amd64`, `armhf`,
  etc.