# Building the Mackerel Toolchain(s)

Mackerel code and the Linux image are compiled with custom toolchains built using crosstool-ng. Three toolchains are provided:

| Toolchain | Tuple | Use |
|-----------|-------|-----|
| Baremetal | `m68k-mackerel-elf` | Bootloader, bare-metal test apps |
| Linux (musl) | `m68k-mackerel-linux-musl` | Linux userspace for MMU targets (Mackerel-30+) |
| uClinux (uClibc-ng) | `m68k-mackerel-uclinux-uclibc` | Linux userspace for NOMMU targets (Mackerel-10, 68000/68010) |

The uClinux toolchain targets processors without an MMU. It uses uClibc-ng with NOMMU mode and produces bFLT binaries via elf2flt.

## Download prebuilt toolchains (recommended)

If you don't want to build the toolchains yourself, prebuilt `tar.xz` archives (GCC 16.1.0, x86-64 Linux host) are attached to the [`toolchains-2026-06-06` release](https://github.com/crmaykish/mackerel-68k/releases/tag/toolchains-2026-06-06). Extract them to `~/x-tools`:

```
mkdir -p ~/x-tools
sha256sum -c SHA256SUMS    # verify the downloads
tar -C ~/x-tools -xf m68k-mackerel-elf-gcc16.1.0-x86_64-linux.tar.xz
tar -C ~/x-tools -xf m68k-mackerel-linux-musl-gcc16.1.0-x86_64-linux.tar.xz
tar -C ~/x-tools -xf m68k-mackerel-uclinux-uclibc-gcc16.1.0-x86_64-linux.tar.xz

# add the one(s) you need to PATH, e.g.:
export PATH="$PATH:$HOME/x-tools/m68k-mackerel-elf/bin"
m68k-mackerel-elf-gcc --version
```

To build them from source instead, follow the rest of this document.

---

1. Run one of the `tools/install_reqs_` scripts based on your Linux distribution.

2. Compile crosstool-ng:

```
git clone https://github.com/crosstool-ng/crosstool-ng.git
cd crosstool-ng
./bootstrap
./configure --prefix=/home/$(whoami)/crosstools
make
make install
```

3. Use crosstool-ng to build a toolchain for Mackerel. The procedure differs
   between the baremetal/Linux toolchains and the uClinux toolchain — see below.

### Baremetal and Linux (musl) toolchains

These build from a defconfig in the normal crosstool-ng way:

```
cd <some_empty_workspace_directory>

# Make sure the newly built crosstool-ng binary is available in the path
export PATH=$PATH:/home/$(whoami)/crosstools/bin

# Copy the defconfig for the toolchain you want to build:
#   tools/mackerel_crosstools_baremetal_defconfig   (baremetal)
#   tools/mackerel_crosstools_linux_defconfig       (Linux / musl)
cp <path_to_this_repo>/tools/<mackerel_defconfig_file> defconfig

# Create a full .config from the defconfig
ct-ng defconfig

# Build the toolchain (5-20 minutes)
ct-ng build
```

### uClinux (uClibc-ng) toolchain

**This toolchain must be built from the full saved `.config`. There is no
uClinux defconfig, and `ct-ng defconfig`/`oldconfig` does NOT work for it.**
Regenerating the config re-defaults `CT_ARCH_USE_MMU=y`, which silently builds a
Linux/MMU toolchain (`m68k-mackerel-linux-uclibc`, ELF) instead of the
uClinux/NOMMU one we need (FLAT). So we copy the known-good full `.config` into
place and call `ct-ng build` directly. This toolchain also needs the uClibc-ng 
config and the local patch tree.

The repo ships:
- `tools/mackerel_crosstools_uclinux.config` - the full crosstool-ng `.config` (MMU off, FLAT, `-msep-data`, local patches enabled). This is the build input; copy it to `.config`.
- `tools/mackerel_uclinux_uclibc.config` — the uClibc-ng configuration
- `tools/patches/` — local patches (`gcc/`, `uClibc-ng/`) applied during the build

```
cd <some_empty_workspace_directory>

# Make sure the newly built crosstool-ng binary is available in the path
export PATH=$PATH:/home/$(whoami)/crosstools/bin

# Copy the full .config (note: NOT a defconfig)
cp <path_to_this_repo>/tools/mackerel_crosstools_uclinux.config .config

# The .config references ${CT_TOP_DIR}/uclibc.config and ${CT_TOP_DIR}/patches
# (paths are kept relative so the build tree is portable/shareable), so the
# uClibc-ng config must be named exactly "uclibc.config" in this directory, and
# the patches tree must sit next to it.
cp <path_to_this_repo>/tools/mackerel_uclinux_uclibc.config uclibc.config
cp -r <path_to_this_repo>/tools/patches .

# Build the toolchain directly from the .config — do NOT run ct-ng defconfig/oldconfig
ct-ng build
```

After the build, confirm the tuple really is `m68k-mackerel-uclinux-uclibc` (NOMMU).
If you ever see `-linux-` instead of `-uclinux-`, the `.config` was regenerated by
`defconfig`/`oldconfig` — start over from the full `.config`.

4. Verify the compiler works:

**Baremetal:**
```
~/x-tools/m68k-mackerel-uclinux-uclibc/bin/m68k-mackerel-uclinux-uclibc-gcc --version
m68k-mackerel-uclinux-uclibc-gcc (crosstool-NG 1.28.0.43_1193ab8) 16.1.0
Copyright (C) 2026 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
```

**Linux (musl):**
```
~/x-tools/m68k-mackerel-linux-musl/bin/m68k-mackerel-linux-musl-gcc --version

m68k-mackerel-linux-musl-gcc (crosstool-NG 1.28.0.43_1193ab8) 16.1.0
Copyright (C) 2026 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
```

**uClinux (uClibc-ng):**
```
~/x-tools/m68k-mackerel-uclinux-uclibc/bin/m68k-mackerel-uclinux-uclibc-gcc --version

m68k-mackerel-uclinux-uclibc-gcc (crosstool-NG 1.28.0.43_1193ab8) 16.1.0
Copyright (C) 2026 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
```

The uClinux toolchain includes `elf2flt` and `flthdr`. To produce a bFLT binary, pass `-Wl,-elf2flt` in your link flags (this is done automatically in the Linux build scripts):

```
m68k-mackerel-uclinux-uclibc-gcc -msep-data -fno-common -Wl,-elf2flt -o foo foo.c
```