---
title: Executable Format
description: Binary format specification for Thru executable programs
source_url:
  html: https://thru.org/docs/spec/vm/executable-format/
  md: https://thru.org/docs/spec/vm/executable-format.md
---

# Executable Format

Thru executable programs follow a specific binary format that includes a header, program bytecode, and trailer.

## Program Structure

A Thru executable consists of three main components:

| Component | Size | Description |
| - | - | - |
| Header | 8 bytes | Version and metadata |
| Program | Variable | Executable bytecode |
| Trailer | 8 bytes | Zero terminator |

## Header Format

The header is exactly **8 bytes** long and contains version information.

### Header Layout

| Offset | Size | Field | Description |
| - | - | - | - |
| 0 | 1 | Version | Program format version (0x01) |
| 1-7 | 7 | Reserved | Reserved for future use |

### Version Field

Currently, only version `0x01` is supported.

```hex
01 00 00 00 00 00 00 00
^^ Version (0x01)
   ^^^^^^^^^^^^^^^ Reserved (7 bytes, typically zero)
```

## Program Bytecode

The program bytecode section contains the executable instructions:

- Starts immediately after the 8-byte header
- Variable length depending on the program size
- Contains the actual program instructions
- Minimum size is 0 bytes (empty programs are valid)

## Trailer Format

The trailer is exactly **8 bytes** long and serves as a terminator.

### Trailer Layout

| Offset | Size | Field | Description |
| - | - | - | - |
| -8 | 8 | Terminator | Must be zero (0x0000000000000000) |

The last 8 bytes of the executable must be set to zero.

```hex
00 00 00 00 00 00 00 00
^^^^^^^^^^^^^^^^^^^^^^^ All bytes must be zero
```

## Size Constraints

- **Total minimum size**: 16 bytes (8-byte header + 8-byte trailer)
- **Header size**: Exactly 8 bytes
- **Trailer size**: Exactly 8 bytes
- **Program size**: Variable (minimum 0 bytes)

## Complete Example

Here’s a minimal valid Thru executable:

```hex
01 00 00 00 00 00 00 00   // Header: version 0x01 + 7 reserved bytes
95 00 00 00 00 00 00 00   // Program: 8 bytes of instructions
00 00 00 00 00 00 00 00   // Trailer: 8 zero bytes
```

In this example:

- Total size: 24 bytes
- Header size: 8 bytes
- Program size: 8 bytes
- Trailer size: 8 bytes

> **Note:**
>
> The executable format provides extensibility through the version field for future format changes while maintaining a simple structure for current programs.