Fatdog ISO Builder
==================

This is the Fatdog ISO Builder. This package enables you to build 
custom Fatdog ISO from the list of packages that you specified.
The result of this script, when run properly, is an triple-hybrid ISO
that will boot as an ISO, or when `dd`-ed into a USB flash drive, on
BIOS and UEFI systems.

This is the same set of scripts that is used to build the official 
Fatdog64 ISO - so if you supply an identical initrd and identical
package list (see below for details) - this script would create an ISO
that is functionally identical with the official Fatdog64 ISO.

This script has been tested to run only on Fatdog64. It relies on 
certain tools that is known to exist and work on Fatdog64. It may work
on other systems - but if you do that and you have problems, I don't 
want to hear about it.

This tool is a great alternative to remaster. Remaster more or less 
does the same thing; this one builds the ISO from the ground-up.

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



Main usage
----------

Extract the downloaded tarball to a **Linux** filesystem.
Important: you must use **Linux** filesystem. You cannot use this
on FAT32, NTFS, HFS+, or any other non-Unix, non-Linux filesystem.

The master script is called build-iso.sh. This script drives all other
scripts. You can create a file called `build-iso.conf` and put that in
this directory; that file will be sourced and all variables will be
used instead of the ones specified in the script.

A default `build-iso.conf` is supplied with the default values given.
You can change them to suit your needs.

`build-iso.sh` is capable of producing an ISO, and initrd, or standard
Fatdog SFS-es (base sfs, devx sfs, and nls sfs). For the ISO, you can
choose the standard humongous initrd, or small initrd, or "micro" 
initrd.

All the working files will be created in this directory unless you 
specify otherwise (via `build-iso.conf`). Thus make sure that you put
this in a filesystem large enough to contain all the downloaded
packages and the final output. 

It will use `tmp` as temporary directory by default; so you will also
need plenty of space there. How big the space is needed depends on how
many packages you want to build.

Fatdog64 800 requires at least 2.5GB free in /tmp.
Newer version will require more space.

If you have less than 2.5GB in /tmp, you need to specify directory
location for storing temporary files. They are documented
[here](docs/BUILD-COMMANDS.md).


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



Output
------

By default the output will be placed in the `iso` directory.
Inside that directory, there are two scripts - `runiso.sh` and
`runsfs.sh`. Both of these will use qemu-system-x86_64 to run the
ISO (or fd64.sfs) you have created for testing purposes.

Since 813 ISO builder, this script can also produce a bootable disk
image instead of ISO file. Officialy Fatdog does not currently ship
disk image, but it may be in the future.

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



Notes
-----

Six main ingredients are **not** supplied in this packages.

1. There are no actual packages inside. This will be downloaded by the
   build scripts.

2. There is no kernel inside. This will be downloaded by the build 
   scripts.

3. There is no initrd inside. The supplied one is a dummy and must be
   replaced from an existing Fatdog ISO: get a recent ISO, extract out
   its initrd, put it in a folder called `fatdog-initrd` and use that
   folder to replace the one here. Note: use the extracted content,
   and do not re-pack it again.
   
   If you forgot to do this you will be gently reminded when you boot 
   the resulting ISO ☺   
   Make sure you remove `kernel-modules.sfs` and `fd64.sfs` from the 
   extracted initrd to save space as they are not used and will be 
   replaced with by the build process anyway.

4. There is no package list. The supplied package lists are dummy ones.
   They will build a CLI-only system with bash and a few common 
   utilities.
   You can start customising your system from here, or you can get
   a current Fatdog package list and work your way up from there.
   
5. `efiboot.img`, Fatdog's UEFI bootloader is not included, because of
   its size. Grab it from any recent Fatdog ISO distribution, then  
   put it inside `fatdog-iso-root` directory.
   
   If you don't have it, you can still build the ISO but it will be 
   built as standard isohybrid and will only boot on BIOS systems 
   (or UEFI with legacy support enabled).

6. `boot-images.tar.xz`, Fatdog's universal boot loader, is not
   included because of its size. Grab this from any recent Fatdog ISO
   distribution, then put it inside `fatdog-iso-root/usb-boot`.
   You only need this file if you want to build Fatdog image file,
   otherwise it is not needed.

The reasons why these are not included is because they change often.
`efiboot.img` and `boot-images.tar.xz` are not included because of
their size.

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



Additional tools
----------------

There are additional tools you can find in under the /scripts directory.

1. build-kernel.sh
   This is a tool to build a kernel for Fatdog64, if you find the ones
   available publicly is not suitable for you.

   To use it, create a directory on a Linux filesystem with ample space
   (6GB recommended), and copy (or symlink) this file there.

   In that directory, run `sh build-kernel.sh -h`. It will explain to
   you how to use the script. 

2. gui-build-kernel.sh
   A simple GUI wrapper of build-kernel.sh. It is a wrapper, not a
   standalone tool, and hence requires build-kernel.sh, which must be
   available in the same directory as build-kernel.sh.

   The benefit of the GUI is that it allows you to pre-define all the
   parameters in advance, so you can leave the build unattended unless
   you choose to.

   Of course, in case there is a build failure, you still have to fix it.
   Since it uses build-kernel, when you encounter build failure you
   can fix it and then continue the build process using build-kernel.sh
   directly. Unlike build-kernel.sh which is stateful, the simple GUI
   wrapper is __simple__ and __stateless__. If you re-run it will re-start
   the entire process instead of picking up where it left.
   
3. micko-get-ucode2.sh
   This is a script, adapted from Micko's original script, to download,
   and package CPU microcode update for use with initrd.

   Just like the build-kernel.sh, there are already microcode update
   package made available for public, but if you want the latest and
   the greatest one, you can use to download and package the most recently
   available microcode update.

If you use any of these tools, you may want to edit build-iso.conf to
make sure that the build picks up and uses your custom kernel / microcode
update.

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



Additional documentation
------------------------

[How to use ISO Builder inside Qemu](docs/BUILD-QEMU.md)

[build-iso.sh parameters](docs/BUILD-COMMANDS.md)



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

Copyright (C) 2016 - 2026 - The Fatdog Team.
License: GNU GPL version 2 or later.
Warranty: None. Use it at your own risk.

