bdisk/docs/README

######################################################################################################################################
#####                                                       BDisk                                                                #####
#####                                                                                                                            #####
#####    Written by Brent Saner                                                                                                  #####
#####    <bts@square-r00t.net>                                                                                                   #####
#####    Built upon my (Brent's) 'BDisk' ISO-building framework (http://bdisk.square-r00t.net)                                   #####
######################################################################################################################################

!!!!!! WARNING !!!!!!!
I do NOT recommend running this on a machine that is using wireless, as it will download a LOT of data.
If you ignore this warning, be prepared to explain to anyone you share your wifi with why Facebook takes 20 seconds to load,
because they WILL ask.

It should be fine over ethernet, since hardware switches are much faster and efficient than a single duplex wireless radio.

Future versions, once this project has a dumping ground, will fetch highly compressed snapshotted chroot filesystems instead
of dynamically building the entire install chroots (both x86_64 and i686) instead (with the option of building fresh locally,
disabled by default).

Maybe.

Till then, sorry for the inconvenience.
!!!!!!!!!!!!!!!!!!!!!!


## Why Arch? ##
Because it's a largely easy-to-use, well-documented (https://wiki.archlinux.org/) distro. It's no-frills and incredibly
flexible/customizable, and can be made rather slim. It's also very friendly to run as a chroot inside any other distro.

All commands below should be issued in the root working directory of this git repository. (For me, this is
/opt/dev/work/BDisk but this may be entirely different for you, depending on where you cloned the repository to.)

## Features ##
-Builds a hybrid ISO
	A hybrid ISO allows one to simply dd if=/path/to/file.iso of=/dev/<USB STICK> instead of using e.g. UNetBootin while also
	working with traditional optical media.
-Builds a dual-architecture ISO
	BDisk allows you to create both a 32-bit and 64-bit ISO, either separately or part of the same ISO, and customize each
	based on architecture.
-Supports both BIOS and UEFI booting in one ISO
	It can be difficult finding a live distribution that offers full UEFI support, which is frustrating if you're trying to
	install e.g. UEFI-enabled Gentoo, for instance. Not only does this ISO framework build support for both in the same ISO,
	but it also includes some UEFI shells as well.
-Arch install scripts
	This live distro, assuming default packages are kept, should be 100% compatible with the Arch install guide
	(https://wiki.archlinux.org/index.php/installation_guide).
-Allows for non-interactive runs, is git-friendly, logs all output while keeping the runtime output relatively sane, and allows
	the inclusion of arbitrary files in the finished filesystem.
-TFP/HTTP/PXE support
	It will automatically copy over some files to tftpboot/ and http/, greatly saving some time in PXE booting. It also
	supports, by default, booting PXE with HTTP fetching for the squashed filesystems. Say goodbye to NFS. You can even
	automatically rsync over after the build, if you wish, to your webserver (see sub-point)
	-Additionally, it supports iPXE if enabled in the configuration file. Please see examples/HTTP for an example of how to
	lay this out and what sort of directory hierarchy is needed.
-Automatic versioning based on git tags

## Prerequisites ##
-At least ~20Gb disk space free (remember, you need room for not only four chroots (one developing and one staging for i686/x86_64),
but also disk space for working, the finished ISO(s), etc.)

-The following packages installed on the build host:

curl
dosfstools
libisoburn ("libisofs" on CentOS)
lynx
rsync
sed
squashfs-tools
xorriso (in RPMForge repo for CentOS 7)
xz

and maybe a few others. The scripts run with set -e for the most part, so if something's missed, you'll know.
Oh, you will know.

If these packages are missing, they will be automatically installed. Currently, the following distros as host build systems
are supported (assumes most recent release):

Antergos
Arch
CentOS
Debian
Fedora
Gentoo
Mageia
Manjaro
openSUSE
RHEL
SUSE
Ubuntu

## Configuration ##
See extra/build.conf.sample. Copy to <PROJECT ROOT>/build.conf if you wish to modify any of the values, otherwise the defaults
will be used. I recommend enabling I_AM_A_RACECAR if you have the hardware for it, as it can speed things up greatly.
The file should be well-commented.

Also note the following files/paths:

-bin:
	The building/cleaning scripts.
--/build.sh:
	Supports several modes:
	bin/build.sh update		Updates existing chroots (does an apacman -Syyu --devel, copies over fresh files from
					overlays, etc.)
	bin/build.sh chroot		Chroots you into the runtime for any interactive tasks you may wish to run.
	bin/build.sh build		(DEFAULT) Builds the chroots, ISO, etc.
	bin/build.sh all		Same as bin/build.sh build
	bin/build.sh			Same as bin/build.sh build
--/clean.sh:
	Supports several modes:
	bin/clean.sh all		Clears everything out to a near-pristine working state. For convenience, it DOES NOT clear
					out build.conf.
	bin/clean.sh chroot		Clears out only the working spaces, old ISOs, and the chroot directories. Hnady if you want to "start
					fresh" but still want to keep logs from earlier runs.
	bin/clean.sh squash		Clears out only the working spaces and old ISOs. Useful if you're on a slow connection and would
					rather update the chroots instead of downloading filesystem snapshots again.
	bin/clean.sh			Only clears workspaces and old ISOs.
--/mirror.lst.sh:
	Builds a fresh mirror list. Note that it is US based.

-docs:
	Documentation for BDisk.
--/COPYING:
	See LICENSE.
--/README:
	This file.
--/LICENSE:
	The license file.
--/FAQ:
	Several quick questions you might have.
--/TODO:
	Some features, bug fixes, etc. I have planned.
-examples:
	Included recommendation for how to lay things out, etc.
--/HTTP:
	Recommended layout for webserver layout if using iPXE.
-extra:
	Supporting files for the base building system (mirrorlist, etc.).
--/${UXNAME}.png:
L	A 640x480 8-bit RGBA colour PNG which will be used as the background for the bootsplash (if booting via BIOS and not UEFI)
--/bootstrap/apacman-*.tar.xz:
	An AUR-enabled package manager. Necessary for AUR support.
--/build.conf.sample:
	Sample/default config file. If you wish to override any settings, copy to <PROJECT ROOT>/build.conf and make your changes there.
	First run of the script will do this for you automatically.
--/mirrorlist:
	A set of default mirrorlists to be used for the chroots during building and runtime. Feel free to replace with your own
	mirrorlist (current list is speed-optimized for east coast US).
--/packages.32:
	A list of packages to install in the base system (32-bit runtime only).
--/packages.64:
	A list of packages to install in the base system (64-bit runtime only).
--/packages.both:
	A list of packages to install in the base system (these should be installed and are supported on both 64- AND 32-bit)
--/pre-build.d:
	Contains files injected into the system. Both 64-bit and 32-bit environments. Note: be sure to place them in hierarchical order
	(e.g. if you wish to have a file at /usr/foo/bar, you will need to place it in <PROJECT ROOT>/extra/pre-build.d/usr/foo/bar)
        (NOTE: Make sure all the packages you specify are valid package names. A mistyped or nonexistent package name will cause the chroot
        creation to break and everything else will break as a result.)
--/pre-build.d/32:
	Same as above, but only for 32-bit environments.
--/pre-build.d/64:
	You get the picture.
-http:
	Files to be hosted for PXE booting the environment go here. Set this as your root/DocumentRoot in nginx/Apache (or, ideally,
	copy over to a separate webserver). This directory is wiped out during any bin/clean.sh operation.
-lib:
	The "guts" of BDisk.
-logs:
	Here you can find full output of the runs. They are prefixed with run's PID number, and named after the function they occur in.
-overlay:
	These files are applied AFTER the initial setup of the chroots. Same hierarchy rules as extra/pre-build.d.
-src:
	Supporting source code/source code from other projects.
--ipxe/:
	For iPXE support.
--ipxe_local/:
	Various patches and supporting configs to tweak the iPXE build.
-tftpboot:
	Files to be served via TFTP for PXE booting. This directory is wiped out during any bin/clean.sh operation.


You may notice other files come and go; they're mostly there for extra goodies/used to determine other things.

## (Re)Building ##
Building must be done as root, and on a supported distro (see Prerequisites for a list).

# bin/build.sh

Yeah. It's that easy. The finished product is in iso/.


If you want more verbosity, check out the logs/ directory.


## Submitting Patches ##
If you have a fix or feature you'd like added, please follow the same pull request process for the kernel
(https://www.kernel.org/doc/Documentation/SubmittingPatches) and email to bts@square-r00t.net

Alternatively, file a bug at https://bugs.square-r00t.net/index.php?project=2 with a patch attached.