3. Command line options

USAGE:
mkg [1]
mkg [[switch=argument]...] filename.iso [2]
mkg [[switch=argument]...] [3]
mkg help[=md] [4]

Usage [1] and [2] create a bootable ISO output file with a current
Gentoo distribution.
For [1], implicit ISO output name is gentoo.iso
Usage [3] creates a VirtualBox VDI dynamic disk and a virtual machine
with name Gentoo.
Usage [4] prints this help, in markdown form if argument 'md' is
specified.
Warning: you should have at least 55 GB of free disk space in the
current directory or in vmpath if specified.

Arguments with white space (like cflags="-O2 -march=...") should be
written in list form with commas and no spaces, enclosed within single
quotes: cflags=\'[-O2,-march=...]\'
The same holds for paths with white space.

As of March, 2021, part of the build is performed
by Github Actions automatically. An ISO file of CloneZilla
supplemented with VirtualBox guest additions will be downloaded
from the resulting automated Github release. To disable this behavior
you can add use_clonezilla_workflow=false to command line, or build the
custom ISO file beforehand using the companion project
clonezilla_with_virtualbox. In this case, add:
custom_clonezilla=your_build.iso
to command line.
Within containers, use_clonezilla_workflow, build_virtualbox
and test_emerge are not (yet) supported and will fail.
A similar procedure also applies to the minimal Gentoo install ISO.
MKG scripts and the stage3 archive are added within its squashfs filesystem
by the Github Actions workflow of the MKG Github site.
An ISO file labelled downloaded.iso is automatically released
by the workflow. It will be downloaded from the MKG Github release section.
This preprocessed ISO has build parameter presets. It builds the full desktop.
In particular, the following command line options will be ignored:
bios, cflags, clonezilla_install, debug_mode, elist, emirrors,
kernel_config, mem, minimal, minimal_size, nonroot_user, passwd,
processor, rootpasswd, stage3_tag, vm_keymap, vm_language.
You can however use ncpus with values 1 to 6 included.
Memory will be automatically allocated depending on ncpus value.
To disable this behavior you can add use_mkg_workflow=false
to command line. You will need to do so if you do not use OS build presets.

GUI mode and background runs

To run in the background, either add gui=false & to your command line
or, if you want to keep a VirtualBox GUI and not run in headless mode,
first launch in the foreground then use bg %n (where n is the
corresponding shell job shown in the output of the jobs command).

Options:

Boolean values are either true or false. For example, to build
a minimal distribution, add to command line:
minimal=true
or simply: minimal as true can be omitted (unlike false).

Examples

$ ./mkg pdfpage
$ ./mkg debug_mode verbose from_vm vm=Gentoo gentoo_small.iso \
ext_device=sdc device_installer blank burn cleanup=false
# ./mkg download_arch=false download=false download_clonezilla=false \
custom_clonezilla=clonezilla_cached.iso use_mkg_workflow=false nonroot_user=phil
# nohup ./mkg plot plot_color=red plot_period=10 plot_pause=7 \
compact minimal minimal_size=false use_mkg_workflow=false gui=false elist=myebuilds \
email=my.name@gmail.com email_passwd='mypasswd' &
# nohup ./mkg gui=false from_device=sdc gentoo_backup.iso &
# ./mkg dockerize minimal use_mkg_workflow=false ncpus=5 mem=10000 gentoo.iso

Type Conventions:
b: true/false Boolean
o: on/off Boolean
n: Integer
f: Filepath
d: Directory path
e: Email address
s: String
u: URL

When a field depends on another, a colon separates the type and
the name of the dependency. dep is a reserved word for dummy defaults of dependencies i.e.
optional strings that may remain unspecified.
Some options are incompatible, e.g. test_only and use_mkg_workflow

Option	Description	Default value	Type
debug_mode	Do not clean up mkg custom logs at root of gentoo system files before VM shutdown. Boolean.	[ false ]	b
verbose	Increase verbosity	[ false ]	b
bios	Type of bootloader: BIOS or EFI (default)	[ false ]	b
blank	Blank rewritable optical disk before burning installation image.	[ false ]	b
build_virtualbox	Download code source and automatically build virtualbox and tools. Yields VirtualBox and vbox-img executables under main directory and subdirectory virtualbox with the build, including documentation.	[ false ]	b
burn	Burn to optical disc. Boolean.	[ false ]	b
cdrecord	cdrecord full path. Automatically determined if left unspecified.	[ which cdrecord ]	f:burn
cflags	GCC CFLAGS options for ebuilds	[ '[-march=native,-O2]' ]	s
check_vbox_version	Check that VirtualBox version within a container is the same as in the host platform	[ ]	s
cleanup	Clean up archives, temporary images and virtual machine after successful completion. Boolean.	[ true ]	b
clonezilla_install	Use the CloneZilla live CD instead of the official Gentoo minimal install CD. May be more robust for headless install, owing to a VB bug requiring artificial keyboard input (see doc).	[ false ]	b
cloning_method	Method used by hot_install ext_device=... to intall Gentoo to disk. One of: 'guestfish' (default) or 'qemu'	[ guestfish ]	s:ext_device
compact	Compact virtual disk after VM building. Caution: this may impede hot_install and ext_device.	[ false ]	b
cpuexecutioncap	Maximum percentage of CPU per core (0 to 100)	[ 100 ]	n
CRAN_REPOS	CRAN repository URL for downloading extra R packages	[ https://cloud.r-project.org ]	s
create_squashfs	(Re)create the squashfs filesystem. Boolean.	[ true ]	b
custom_clonezilla	Use this previously created custom CloneZilla ISO with added VirtualBox and guest additions.	[ dep ]	s
cut_iso	Cut ISO files created for Gentoo installers into 2GB chunks. Entails sums=true.	[ false ]	b
device_installer	Create Gentoo clone installer on external device. ext_device value must be specified.	[ ]
disable_checksum	Disable checksum verification after downloads. Boolean.	[ false ]	b
disconnect	Unmount guest virtual disk from host.	[ true ]	b
dockerize	Use a pre-built Docker image to run MKG into. Incompatible with e.g. 'gui', 'hot_install', 'plot', 'test_emerge'	[ false ]	b
docker_image_path	URL to ../'workflow_tag2'/mygentoo-'workflow_tag2'.tar.xz	[ path5 ]	s:workflow_tag2
download	Download install ISO image from Gentoo mirror. Boolean.	[ true ]	b
download_arch	Download and install stage3 archive to virtual disk. Booelan.	[ true ]	b
download_clonezilla	Refresh CloneZilla ISO download. An ISO file must have been downloaded to create the recovery image of the Gentoo platform once the virtual machine has ended its job. Boolean	[ true ]	b
download_clonezilla_path	Download the following CloneZilla ISO	[ path1 ]	u
download_only	Only download the Gentoo minimal install ISO and stage3 archive of the day, then exit.	[ false ]	b
efi_size	Size of EFI partition in MiB.	[ 512 ]	n
elist	File containing a list of Gentoo ebuilds to add to the VM on top of stage3. Note: if the default value is not used, adjust the names of the 'elist'.accept_keywords and 'elist'.use files	[ ebuilds.list ]	f
email	Email address to send a warning to upon build completion. Note: you will have to accept so-called insecure software with some providers. It is not insecure if you are using your private PC throughout.	[ ]	e
email_passwd	Email password	[ ]	s:email
emirrors	Mirror sites for downloading ebuilds	[ path2 ]	u
exitcode	Print virtual machine final exit code (0 on success)	[ false ]	b
ext_device	Create Gentoo OS on external device. Argument is either a device label (e.g. sdb, hdb), or a mountpoint directory (if mounted), or a few consecutive letters of the model name (e.g. 'Hitachi HDS5C3020BLE630', 'PNY CS900 960GB' or 'WDC WD30'), if there is just one such. Requires either device_installer or hot_install on commandline.	[ dep ]	s
force	Forcefully creates machine even if others with same same exist. Stops and restarts VBox daemons. Not advised if other VMs are running.	[ false ]	b
from_device	Do not Generate Gentoo but use the external device on which Gentoo was previously installed. Boolean.	[ false ]	b:ext_device
from_iso	Do not generate Gentoo but use the bootable ISO given on commandline.	[ false ]	b
from_vm	Do not generate Gentoo but use the VM. Boolean.	[ false ]	b
full_cleanup	Remove virtual disk, archives and ISO files on clean-up	[ false ]	b
github_release_path	URL to Github Release of clonezilla_with_virtualbox.iso	[ path3 ]	s
github_release_path2	URL to Github Release of preprocessed_gentoo_install.iso	[ path4 ]	s
gui	Binary: true corresponds to VBoxManage startvm ... --type=gui, false to --type=headless	[ true ]	b
help	This help	[ ]
hot_install	Intall to Gentoo attached device (like /dev/sdb) possibly mounted (like /media/USER/567EAF). To be used with ext_device=...	[ false ]	b:ext_device
htmlpage	Create HTML help page	[ false ]	b
hwvirtex	Activate HWVIRTEX: on/off	[ on ]	o
interactive	Allow interaction with user. This may cause deadlock if process is detached from the console (nohup or other methods)	[ true ]	b
ioapic	IOAPIC parameter: on or off	[ on ]	o
kernel_config	Use a custom kernel config file	[ .config ]	f
livecd	Path to the live CD that will start the VM	[ gentoo.iso ]	f
logging	Activate logging	[ true ]	b
manpage	Create manpage mkg.1	[ false ]	b
mem	VM RAM memory in MiB	[ 8000 ]	n
minimal	Remove libreoffice and data science tools from default list of installed software. Boolean.	[ false ]	b
minimal_size	Remove kernel sources to minimize packaging. Not advised for personal use but OK for deployment and distribution.	[ true ]	b
mirror	Mirror site for downloading of stage3 tarball	[ path2 ]	u
ncpus	Number of VM CPUs. By default the third of available threads. You should not configure virtual machines to use more CPU cores than are available physically. This includes real cores, with no hyperthreads.	[ count ]	n
no_run	Thwart VM generation, only perform other operations (if valid).	[ false ]	b
nonroot_user	Non-root user	[ fab ]	s
pae	Activate PAE: on/off	[ on ]	o
paravirtprovider	Virtualization interface: kvm for GNU/Linux, may be tweaked (see VirtualBox documentation)	[ kvm ]	s
passwd	User password	[ _user2021_ ]	s
pdfpage	Create PDF help page	[ false ]	b
plot	Plot VDI disk size using GNUPlot	[ false ]	b
plot_color	Plot line color between simple quotes (e.g: 'cyan','red' etc.)	[ 'cyan' ]	s
plot_pause	Number of seconds of plot display per minute of processing. Maximum 50.	[ 5 ]	n
plot_period	Number of minutes elapsed between two successive plots	[ 10 ]	n
plot_position	Plot position of on monitor screen (top-left angle) in pixels e.g '0,0' or '500,500'	[ '0,0' ]	s
plot_span	Number of minutes of virtual disk processing to be plotted, back in time	[ 1200 ]	n
postpone_qemu	If using share_root='r' or 'w', do not run the virtual machine but use the VDI disk corresponding to vm=... Otherwise start 15 minutes later.	[ false ]	b
processor	Processor type	[ amd64 ]	s
pull	Invoke 'git pull' in mkg local repository on startup.	[ false ]	b
quiet_mode	Silence output except for the most severe errors.	[ false ]	b
rootpasswd	Root password	[ _dev2021_ ]	s
rtcuseutc	Use UTC as time reference: on/off	[ on ]	o
scsi_address	In case of several optical disc burners, specify the SCSI address as x,y,z	[ ]	s
shared_dir	Host mount point for guest virtual disk filesystem	[ /vdi ]	s
share_root	Mount guest virtual disk to host folder shared_folder. Argument is 'w' to enable write I/O or read-mode 'r'. May raise security issues, see Wiki.	[ dep ]	s:shared_dir
size	Dynamic disc size	[ 55000 ]	n
smtp_url	SMTP URL of email provider for end-of-job warning. Default: gmail SMTP	[ smtps://smtp.gmail.com:465 ]	u
stage3	Path to stage3 archive	[ stage3.tar.xz ]	f
stage3_tag	Type of stage3 package [openrc, systemd, hardened-openrc]. Experimental.	[ openrc ]	s
sums	Output b2sum and sha512sum of ISO output (only) in file SUMS_[name of ISO output]	[ false ]	b
swap_size	Size of swap partition in MiB.	[ 1024 ]	n
test_emerge	Test whether emerge will be able to install packages in the VM before starting it.	[ false ]	b
test_only	Only test if portage will be able to install packages. Do not create a virtual machine.	[ false ]	b
timezone	Set timezone. See /usr/share/zoneinfo for formats.	[ US/Eastern ]	s
usbehci	Activate USB2 driver: on/off	[ off ]	o
usbxhci	Activate USB3 driver: on/off. Note: if on, needs extension pack.	[ off ]	o
use_bsdtar	Use 'bsdtar' (from libarchive) to extract CloneZilla ISO files if creating an ISO installer.	[ true ]	b
use_clonezilla_workflow	Use Github Actions workflow to add virtualbox guest additions to CloneZilla ISO.	[ true ]	b
use_mkg_workflow	Use Github Actions workflow to preprocess minimal Gentoo ISO by adding MKG scripts inside the squashfs filesystem.	[ true ]	b
use_qemu	Use qemu instead of guestfish for installing Gentoo to block device with hot_install	[ false ]	b
vbox_version	Virtualbox version	[ 6.1.20 ]	s
vbox_version_full	Virtualbox full version	[ 6.1.20 ]	s
vbpath	Path to VirtualBox directory	[ /usr/bin ]	d
vm	Virtual Machine name. Unless 'force=true' is used, a time stamp will be appended to avoid registry issues with prior VMs of the same name.	[ Gentoo ]	vm
vm_keymap	Add support for non-US English keymaps. Use values in /usr/share/keymaps, e.g. fr, de, us.	[ us ]	s
vm_language	Add support for non-US English language as a default. Use standard abbreviations. Must be at least 5 characters: e.g. fr_FR, de_DE, fr_FR.utf8	[ en_US.utf8 ]	s
vmpath	Path to VM base directory	[ $PWD ]	d
vtxvpid	Activate VTXVPID: on/off	[ on ]	o
workflow_tag	Tag version (vX.Y) of the release of file clonezilla_with_virtualbox.iso by Github Actions	[ v2.0 ]	s
workflow_tag2	Tag version (vX.Y) of the release of file preprocessed_gentoo_install.iso by Github Actions (MKG site)	[ release-master or release-gnome ]	s

path1 https://sourceforge.net/projects/clonezilla/files/clonezilla_live_alternative_testing/20210505-hirsute/clonezilla-live-20210505-hirsute-amd64.iso/download
path2: http://gentoo.mirrors.ovh.net/gentoo-distfiles/
path3: https://github.com/fabnicol/clonezilla_with_virtualbox
path4: https://github.com/fabnicol/mkg/releases/download
count: nproc --all / 3