hex2(1)

📦 version 1.5.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 hex2 — the trivially bootstrappable linker 💖

okay so bestie, this is hex2(1), from the User Manuals, and it is literally the trivially bootstrappable linker that is designed to be introspectable by humans. no cap. 🦋

✨ SYNOPSIS ✨

hex2 --architecture ARCHITECTURE --base-address ADDRESS --file FILE
[--output FILE [--non-executable]]

🌸 DESCRIPTION 🌸

hex2 exists so that actual humans — not compilers, not build systems, not some mysterious wizard in the cloud — can write elf files and other binary files by hand, in a format that lets you drop comments in and actually understand what you're looking at. it's giving ✨artisanal binaries✨.

At the very core of it? read 2 hex characters, add them together, output a single byte. that's the whole vibe. 🎀

You can override that and use binary or octal input instead if you want to, using the --octal or --binary option. your input, your rules, periodt.

If no output file is specified, the output gets sent to standard out. and by default the file will be executable — unless you also pass --non-executable. choose your own adventure. 💅

🧚 the ARCHITECTURES (the supported ones, anyway)

  • knight-native
  • knight-posix
  • x86
  • amd64
  • armv7l
  • aarch64

If you fail to specify an architecture, the default of knight-native gets used. 🫶

The base address — like, the address the binary is meant to be loaded into memory at, and therefore the thing your relative and absolute pointers are based on — is passed via --base-address. if you don't provide it, the default value of ZERO is assumed. zero. zilch. nada. iconic honestly.

🏷️ labels, bestie

hex2 also supports labels in the :LABEL format, plus relative and absolute pointers to those labels in 8, 16, 24 or 32 bit sizes. so:

  • !LABEL → 8 bit relative address
  • @LABEL → 16 bit relative address
  • ~LABEL → 24 bit relative address
  • %LABEL → 32 bit relative address
  • $LABEL → 16 bit absolute address
  • &LABEL → 32 bit absolute address

Should you wish to specify the bit and byte encoding of the addresses to match your target, you've got --big-endian and --little-endian. slay. 🌈

🧠 the < and ^ situation (word alignment girlies)

On architectures that require word alignment, the < and ^ characters have a special meaning. specifically:

  • pad to word
  • use word base address calculation rather than standard byte based address calculation

generally seen in the form: ^~LABEL EB for calls in ARM. iykyk. 💜

🎀 EXAMPLES 🎀

Typically, hex2 will be called in scripts used in bootstrapping:

# hex2 -f ELF-armv7l.hex2 -f cc.hex2 --little-endian --architecture armv7l --base-address 0x10000 -o cc

🔥 COMPATIBILITY 🔥

hex2 is compatible with all Turing complete machines — even the ones that try to be Turing complete -1. 😭💀

👑 AUTHORS 👑

  • Jeremiah Orians <Jeremiah@pdp10.guru>
  • Jan (janneke) Nieuwenhuizen <janneke@gnu.org>

Copyright 2016-2019 Jeremiah Orians <Jeremiah@pdp10.guru>

Copyright 2017 Jan Nieuwenhuizen <janneke@gnu.org>

License GPLv3+.

⭐ SEE ALSO ⭐

and that's the whole page, bestie 🩷 this one came out of the Linux manual set, dated JULY 2019, and it's hex2(1) through and through. go hand-write a binary, you absolute main character. 💖✨🎀

📦 where this page comes from