# Fatdog64 ISO Builder

## Introduction

Fatdog64 ISO Builder is a tool to build a customised Fatdog ISO.

There are three ways to make a custom Fatdog ISO.

1. Use Fatdog remaster - take a (modified) snapshot of the running copy of Fatdog, and build an ISO out of it.
2. Take Fatdog's base.sfs, extract it (unsquash it) to a folder, then add/remove packages from that folder, and re-build/re-create the base.sfs. Optionally, use a software like ISO Master to copy the modified base.sfs back to the Fatdog ISO.
3. Use this tool.

What does this tool do? Given a file containing a list of packages, this tool will build Fatdog ISO (and everything else in between that is required to do it). Whatever comes in the ISO is whatever you specify.

Customisation is done by choosing the packages you want to include. But you are not limited to official packages, you can of course create your own packages, which can potentially replace and/or modified base Fatdog files with your own.

You don't have to start with an empty package list either. The Fatdog Team publishes the list of the packages included in the official ISO for every release, so you can use those lists are your starting point.

The ISO Builder is the same tool as used by the Fatdog Team to build the official Fatdog ISO release. Originally release in 2016, at the launch of Fatdog64 702, it has been updated for every single official release onwards. It is not included in the Fatdog ISO, but you can get it from here.

If you are familiar with Puppy Linux and Woof / Woof-CE, the Fatdog64 ISO Builder is Fatdog's version of Woof.

PS: There is another similar builder for FatdogArm, released in 2014. It does not make an ISO, it makes an image file suitable for booting on ARM.

## How to use

Note: The Fatdog64 ISO Builder is an advanced tool for advanced users. If you are not comfortable with command line scripting, then this tool is not for you. Please use other tools to customise Fatdog.

Basic ingredients:

1. The Fatdog64 ISO Builder from the link given above.
2. fatdog-initrd, get it from the latest Fatdog64 official ISO.
3. efiboot.img, get it from the latest Fatdog64 official ISO.
4. The package list for the Fatdog version you're trying to build, downloadable from the same location as the ISO builder.

Item 2-4 is optional.

- If you forgot to get 2) - you will be gently reminded at boot.
- If you forgot to get 3) - your ISO will not boot on UEFI systems
- If you forget to get 4) - it will use built-in pkglist which builds command-line only minimal ISO.

For further information, you can look at the README.md included in the ISO builder itself, a copy of which is shown below. Note that this copy of README dates back from Fatdog 710 days. Newer version of Fatdogs are bigger and will require more space to build.

    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.

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

    Notes
    -----

    Five 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, or from
       [here](http://distro.ibiblio.org/fatdog/other/efiboot.img); 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).

    The reasons why these are not included is because they change often.
    `efiboot.img` is not included because of its size.

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

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

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

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

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

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

## Tutorial: How to build Fatdog inside Qemu

Note that this copy of README dates back from Fatdog 710 days. References to the ISO builder dates and package list were based on that version. You are encouraged to use the latest version of the builder, as well as the latest package list instead.

Please do remember that newer version of Fatdogs are bigger and will require more space to build. The RAM requirement, however, probably don't differ very much.

This tutorial is based on what I wrote in the forum post here.

    Building Fatdog inside QEMU
    ===========================

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

    Introduction
    ------------

    Inside this script you will find directory `qemu`. It contains two
    scripts, `runiso.sh` and `runsfs.sh`.  These are simple wrapper scripts
    to launch and run Fatdog ISO or SFS under qemu.

    Just put fatdog.iso or fd64.sfs under `iso` directory and launch the script,
    e.g. `./iso/runiso.sh`. It will launch a 1GB qemu instance.

    For this to work, you need to have qemu installed. Qemu comes in `devx.sfs`,
    so if you use `devx.sfs` then it's already installed for you.

    You can adjust the memory by adding MEM=xxxx env variable before launching
    the script, e.g. `MEM=2048 ./runiso.sh` to launch a qemu instance with
    2GB RAM.

    ___________________________________

    Virtual Disk in Qemu
    --------------------

    You can also create a file called `disk.ext3` inside `iso` and this
    will be mounted as a virtual disk, which you can then use for savefile
    or savedir or whatever have you. With `runiso.sh` this virtual disk
    will show in as "sda", with `runsfs.sh` it will show up as "sdd".

    To make a 1GB virtual disk:

    dd if=/dev/zero of=iso/disk.ext3 bs=1G count=0 seek=1
    mkfs.ext3 iso/disk.ext3

    ___________________________________

    Building Fatdog inside QEMU - the Steps
    ---------------------------------------

    If you system is able to run a 2GB qemu instance, and you can create
    4GB virtual disk, it is possible to build Fatdog64 using this instance.

    1. Get a working Fatdog ISO, name it fatdog.iso and put it under `iso`.
    Create 4GB virtual disk.

    2. Launch qemu to run Fatdog ISO with 2GB RAM, like this: `MEM=2048 ./iso/runsfs.sh`

    Once you have desktop running inside qemu, follow these steps (all of these
    are done inside the qemu instance, not on the host).

    3. I launched seamonkey and downloaded ISO builder dated 2016.2 from ibiblio.

    4. I downloaded package list for 710, also from ibiblio.

    5. I mounted the 4GB virtual disk (in my qemu, it showed up as "sda") using Rox -
       so the mount point is /mnt/sda

    6. I right-click the iso builder tarball and choose extract. I did the same to the
       package list tarball.

    7. I moved extracted contents of the pkglist tarball (`sfs*list` files) to replace
       those files in the extracted iso builder folder. 6 & 7 is done using Rox.

    8. I mounted the virtual CDROM drive that contains the Fatdog64 710 ISO. In my qemu
       this is "sr0" so it is mounted under /mnt/sr0.

    9. From /mnt/sr0 folder, I dragged and dropped (=copying) efiboot.img to
       "fatdog-iso-root" inside the extracted iso builder folder.

    10. Using rox, I navigated to the "fatdog-initrd" folder inside the extracted
        iso builder folder.

    11. I deleted everything under that folder (init, and "bin" folder) - still using Rox

    12. I launched terminal in that folder, by typing back-quote.

    13. In the terminal, I typed "cpio -i < /mnt/sr0/initrd" to extract the initrd from
        the Fatdog64 710. I can see that folder was populated with stuff extracted from
        initrd.

    14. I deleted "fd64.sfs" and "kernel-modules.sfs" using Rox.

    15. Now on the terminal I opened in step 12, I typed "cd .." to move up to the root
        folder of the iso builder.

    16. I typed "geany build-iso.conf" and edited the file. I added:

    BASE_ROOTFS_DIR=/mnt/sda/build
    WORKDIR=/mnt/sda/build-iso

    to the end of the file. And I saved the file, and quit geany.

    17. Then in the terminal I typed "mkdir -p /mnt/sda/build". Remember, "/mnt/sda" is
        where my virtual disk is mounted.

    18. Then I typed "./build-iso.sh iso".

    19. It will start downloading files. When all files have been downloaded, it will start
        instaling them. When installation is done, it will build fd64.sfs. When the basesfs
        is done, it will build the ISO in the "iso" folder.

    Note: Go for coffee. Downloading from ibiblio is slow. Doing mksquashfs with XZ
    compression is also slow. All these can be configured later using build-iso.conf
    (downloading from elsewhere, and changing the compression to use gzip/bzip2/lzo/lz4
    etc) once you've got the basic steps right and working.

    20. When it is done, shutdown qemu.

    21. Loop-mount the virtual disk by clicking it in Rox.

    22. I copied over the created fatdog.iso to my physical disk - just the usual Rox
        drag and drop.

    23. Then I unmounted the virtual disk (clicking it again)

    24. I tested booting the resulting fatdog.iso using qemu again
        (qemu-system-x86 -enable-kvm -m 1024 -cdrom fatdog.iso).

    25. It works.

    Note: all done with pristine Fatdog64 710 boot, no savefile needed, no devx needed,
    in a machine with 2GB RAM and 4GB free space (Linux filesystem).

    Tip: If you need to build again with a new `pkgtlist` file, you can keep folders
    `pkgcache` and `kernel` in the fatdog-iso-builder folder to avoid downloading their
    contents again. Everything else should start from scratch according tho the steps
    above.

    Tip2: BASE_ROOTFS_DIR and WORKDIR cannot be located anywhere inside /root/Downloads.

## Final Notes

Please don't expect too much support on this. It's targeted at people who know what they are doing, although everyone is welcome to try. You are encouraged to look into the scripts to figure out how it works, and please feel free to edit it to suit your own needs.