WARNING: This is a work in progress. There should be enough to get you started. There is more to come. (including formatting this page)

INTRODUCTION

Devuan's live-sdk uses shell scripts to create a live-CD/DVD iso. With no configuration, live-sdk will make a small, cli-only live iso. To create a live iso with your choice of packages and configurations, you can make your own blend. A blend consists of a config file and a blend file, and it may also contain customized files for the live system and deb packages or even source code for items that aren't in the devuan repository.

The config file contains lists of packages to install or remove along with any variables you want to set. The blend file contains functions to control the build process. Some of these functions may be copied from the sdk and customized. The customized version will override the stock version during the build. It's also possible to add functions that don't exist in the sdk.

For a more complex example and some explanation of the parts of the sdk, see:
Heads Developer Guide (PDF) and also
Heads git repository

REQUIREMENTS

You need these packages installed:
git zsh debootstrap sudo  xz-utils xorriso squashfs-tools live-boot syslinux-common

You will also need live-build.  (I think this can easily be changed to require either syslinux and isolinux or live-build.)

You probably want these, too:
live-config live-config-sysvinit

sudo must be enabled for your user.
(If physical access is not a security issue, do yourself a favor and set sudo with no password, or set the timeout longer than the build time, so you only have to enter the password once.)

These are listed as required by libdevuansdk, but I don't have them, and I'm building isos with live-sdk.
kpartx cgpt

GET LIVE-SDK

git clone https://github.com/parazyd/live-sdk.git
cd live-sdk
git submodule update --init

You can build a minimal live iso without creating a blend. You'll get a very small system with no desktop, the root password will be "toor", there will be no unprivileged user, and most of the standard system utilities will be missing. To do that, use the same commands you would use to build the blend, but leave out the blend_name. You can run this bare build to make sure you have all the requirements; if it doesn't work, you know the problem is not in your blend.

zsh -f
source sdk
load devuan <arch> <blend_name>
build_iso_dist

STEPS TO CREATE A BLEND
Each blend gets its own directory in live-sdk/blends. The example we'll use is simple-ice, and we'll make a small live system with icewm and very few apps. We'll be creating two files in live-sdk/blends/simple-ice/. One is config and the other is <blend_name>.blend, or in this example, simple-ice.blend.

Example blends: Download and unpack the tarball in the live-sdk/blends directory. (subject to change and inconsistency with the howto.)
simple-ice:    (IceWM with a few extra apps)   
jessie-oblx:   (Openbox, custom debs, custom boot menu, uefi bootable)

1. Add a line to the blend map in live-sdk/sdk with the blend name and the location where the blend files can be found. $R is the working directory, live-sdk/. It's also possible to use a URL for the location.

	blend_map=(
		"devuan-live"    "$R/blends/devuan-live/devuan-live.blend"
		"heads"            "$R/../heads.blend"
		"simple-ice"	"$R/blends/simple-ice/simple-ice.blend"
                "jessie-oblx"     "$R/blends/jessie-oblx.blend"
	)

2. Edit config file (live-sdk/blends/simple-ice/config)

Some variables you can use:

image_name
You'll want to give your iso a unique name. The default setting will give you:
devuan_jessie_1.0.0-RC_amd64-live.iso (or -i386-live.iso)

All of these variables except blend_vers are built into the sdk. I added blend_vers for my convenience. It only gets used in the image name here. Whatever you use for an image name will be appended with "-live.iso". You do not need to define the arch here; that will be done when you load the blend at build time.

blend_name="simple-ice"
blend_vers="1.0"

image_name="${blend_name}-${blend_vers}-${arch}"

Use this if you want separate bootstrap tarballs for each blend. (Warning: watch your disk space.)

os="$blend_name"

Add an unprivileged user to the system, change the default shell from dash to bash, and change the root password with the following lines:

username="user"
userpass="user"
default_shell="/bin/bash"
rootcredentials="root:mypassword"

Add some packages.

The package lists exist as arrays in live-sdk. You can add packages to the extra_packages array in the config file as shown in the code box below. Use tabs, not spaces. Note that the syntax here will cause these packages to be added to the extra_packages array if it already exists (i.e. if it's defined elsewhere in the sdk.)

Troubleshooting note: One common reason for a failed build is if one of the listed packages does not exist (or is spelled wrong). It may not be obvious when this happens. Check the logs, but also check your package list.

extra_packages+=(

	grub-pc
	lsof
	bash-completion
	texinfo
	acpi-support-base
	aptitude
	apt-listchanges
	discover
	dnsutils
	doc-debian
	docutils-common
	docutils-doc
	ftp
	gettext
	gnupg2
	laptop-detect
	mlocate
	mutt
	ncurses-term
	nfs-common
	procmail
	reportbug
	telnet
	usbutils
	w3m
	whois
	xorg
	xserver-xorg-video-all
	xterm
	pmount
	spacefm
	lightdm
	icewm
	leafpad
)

Keep dbus?
EDIT: This probably isn't necessary unless you go deeper into the sdk and change the core_packages and base_packages.

The default purge_packages array contains only dbus. Purging dbus will also remove packages needed for many desktops. Disable or replace that purge with:

purge_packages=()

or

purge_packages=(insert your own purge list here)

or to add to the default purge list

purge_packages+=(insert your own purge list here)

Add custom deb packages:

If you want to install deb packages that aren't in the repository, put them in the blend directory and list them in your config file. In this example, we'll add refractasnapshot-base, refractainstaller-base and palemoon web browser. Palemoon and Yad are listed twice because the packages are arch-specific. Comment out the one you don't want in the build. (NOTE: This is not in the simple-ice example tarball, but you could add your own custom debs list and supply the packages. Uncomment the appropriate lines in blend_preinst() in the blend file. See Step 4. Edit the blend file.)

Package lists will be installed in the order they appear. Packages within a list will be installed alphabetically. In this example, refractainstaller-gui and refractasnapshot-gui depend on yad, so yad must be installed first.

# i386
#custom_deb_packages+=(yad_0.27.0-1_i386.deb palemoon_27.2.0~repack-1_i386.deb)

# amd64
custom_deb_packages+=(yad_0.27.0-1_amd64.deb palemoon_27.2.0~repack-1_amd64.deb)

custom_deb_packages+=(
	refractainstaller-base_9.2.1_all.deb
	refractainstaller-gui_9.2.1_all.deb
	refractasnapshot-base_10.0.2_all.deb
	refractasnapshot-gui_10.0.2_all.deb
)

3. Add custom files:

System files (including user files)
Custom config files, icons, images or any other files you want to be present in the live system can be added via the rootfs-overlay. Create a directory inside blends/simple-ice called rootfs-overlay. Files that you add should be placed in their relative positions in the directory tree. So, if you wanted to use a custom sources.list, you'd put your custom file in rootfs-overlay/etc/apt/, and it will be added to the system.

The simple-ice example contains an apt config file to install packages without Recommends, modified xdg files to prevent automatic creation of a bunch of directories in your home. (You know the ones I mean - Documents, Music, Video, etc., all of which I consider spam.) There's also a Devuan replacement for the Debian logo in the IceWM applications button and a couple of config files for IceWM.

blends/simple-ice/rootfs-overlay/
├── etc
│   ├── apt
│   │   └── apt.conf.d
│   │       └── 00norecommends
│   ├── X11
│   │   └── icewm
│   │       ├── focus_mode
│   │       └── theme
│   └── xdg
│       ├── user-dirs.conf
│       └── user-dirs.defaults
└── usr
    └── share
        └── icewm
            └── taskbar
                └── icewm.xpm

For your own blend, you will need to figure out what files you need and where they go.

Isolinux files
If you want custom isolinux boot files, such as a splash image or boot help files, put them in blends/<blend_name>/isolinux-overlay.
The simple-ice example just has a boot splash image.

4. Edit the blend file  (live-sdk/blends/simple-ice/simple-ice.blend)

Start your blend file with the following lines, so that the sdk can find your blend.

BLENDPATH="${BLENDPATH:-$(dirname $0)}"
source $BLENDPATH/config

Add the blend_preinst function. Uncomment the last two lines if you have custom debs to install.

blend_preinst() {
	fn blend_preinst
	req=(strapdir blend)
	ckreq || return 1

	notice "executing $blend_name preinst"

	add-user "$username" "$userpass"
	
#	notice "copying blend-specific debs"
#	cp -fv "$BLENDPATH"/*.deb "$R/extra/custom-packages"
	
}

Add the blend_postinst function. This will copy the rootfs-overlay. If your rootfs-overlay is a git repository, see the heads sdk. This also calls the blend_finalize function, which contains instructions to be run in the chrooted system.

blend_postinst() {
	fn blend_postinst
	req=(strapdir)
	ckreq || return 1

	notice "executing $blend_name postinst"
		
	pushd "$strapdir"
		sudo rsync -avx "$BLENDPATH"/rootfs-overlay/* . || zerr
	popd

	blend_finalize || zerr
}

Add the blend_finalize function to do the following:

    Add user to some groups
    Set the default shell.
    Give user ownership of their files.
    Remove fstab.
    Final cleanup and run updatedb. (I commented out the last autoremove. You might need it.)

blend_finalize() {
	fn blend_finalize
	req=(strapdir)
	ckreq || return 1

	cat <<EOF | sudo tee ${strapdir}/finalize >/dev/null
#!/bin/sh
# finalize
set -x
exec 2>finalize.log

## perms

	for i in cdrom floppy audio dip video plugdev netdev ; do   # lpadmin scanner  # put this in config file?
		gpasswd -a "$username" \${i}
	done
	
	chsh -s "$default_shell" "$username"
	chown -R 1000:1000 /home/"$username"

# remove fstab for iso. This should probably be in iso_prepare_strap
rm -f /etc/fstab

## cleanup

#apt-get --yes --force-yes autoremove
apt-get clean
updatedb
EOF
	chroot-script finalize || zerr
}

5. Make it so!

To build a 64-bit version of the example, from the live-sdk directory, run:

zsh -f
source sdk
load devuan amd64 simple-ice
build_iso_dist

If all goes well, your iso will be in live-sdk/dist/
Exit the zsh shell.

To make the 32-bit version of the same blend, repeat the commands above, but replace amd64 with i386. (Change custom_deb_packages if you have arch-specific packages to install.)

Happy Hacking!

------------------------------------------------------------------------------------------------------------------------------------------------------------------------

EXAMPLE BLEND LAYOUT

simple-ice/
├── config
├── isolinux-overlay
│   └── splash.png
├── rootfs-overlay
│   ├── etc
│   │   ├── apt
│   │   │   └── apt.conf.d
│   │   │       └── 00norecommends
│   │   ├── X11
│   │   │   └── icewm
│   │   │       ├── focus_mode
│   │   │       └── theme
│   │   └── xdg
│   │       ├── user-dirs.conf
│   │       └── user-dirs.defaults
│   └── usr
│       └── share
│           └── icewm
│               └── taskbar
│                   └── icewm.xpm
└── simple-ice.blend

Special instructions for ascii (testing)

Add to the blend config file:

release="ascii"

Right now (March 2017) rsyslog is getting removed at the end of the build and alsa-base does not exist. Workaround is to insert the following line into the debootstrap command at lines 42-44 of zlibs/bootstrap.

--include=busybox,busybox-syslogd --exclude=rsyslog,alsa-base \ 

...and let me know if this changes, so I can keep this doc current. Thanks.