Skip to main content
This guide will walk you through assembling and running the example shell program included with the toolkit.

​
Your first program

The toolkit includes main.4004, a demonstration program that implements a basic interactive shell. Let’s build and run it.
1

Assemble the program

Use the assembler to convert the .4004 source file into an executable binary:
zig-out/bin/4004-assembler 4004-asm/main.4004 4004-asm/main.4004out
The assembler takes two arguments: the input assembly file and the output executable file path.
If assembly succeeds, you’ll have a new file 4004-asm/main.4004out containing the compiled program.
2

Run the emulator

Launch the emulator with your compiled program:
zig-out/bin/4004-emulator 4004-asm/main.4004out
The emulator loads the executable into program memory and begins execution.
3

Interact with the shell

You should see a $ prompt. The shell is now waiting for your input.Try the echo command:
$ echo hello world
hello world
$
Use the Backspace/Delete key to edit your input. Press Enter to execute a command.
4

Exit the emulator

Press Ctrl+C to stop the emulator and return to your terminal.

​
All in one command

You can also run all three steps in sequence: 
zig build && \
zig-out/bin/4004-assembler 4004-asm/main.4004 4004-asm/main.4004out && \
zig-out/bin/4004-emulator 4004-asm/main.4004out
This command:
  1. Builds the toolkit (if needed)
  2. Assembles the example program
  3. Runs it in the emulator

​
Assembler usage

The assembler follows this syntax: 
4004-assembler <input.4004> <output_binary>
Arguments:
  • <input.4004> - Path to your Intel 4004 assembly source file
  • <output_binary> - Path where the assembled executable will be written

​
Emulator usage

The emulator follows this syntax: 
4004-emulator <executable>
Arguments:
  • <executable> - Path to a compiled 4004 program (output from the assembler)

​
Understanding main.4004

The example program demonstrates several features of the Intel 4004:

Memory allocation

Implements a MALLOC function that allocates memory from a heap

Stack operations

Custom stack implementation using data RAM with push/pop operations

I/O handling

Reads from virtual keyboard and writes to virtual monitor via ROM ports

Command parsing

Parses command-line arguments and recognizes the echo command
The program’s calling convention uses registers 0-7 for arguments and return values, preserves registers 10-13 across function calls, and uses registers 14-15 as the stack counter.

​
What’s happening under the hood

When you run the emulator:
  1. The 4004 CPU starts at address 0 in program memory
  2. The program initializes the stack counter and memory allocator
  3. It prints the $ prompt to the monitor
  4. The keyboard polling loop waits for your input
  5. When you press Enter, it parses your command and executes it
  6. The cycle repeats
The emulator runs multiple threads to handle CPU execution, keyboard input, and monitor output simultaneously.

​
Next steps

Now that you’ve run your first program, explore:
  • Study the 4004-asm/main.4004 source to learn the assembly syntax
  • Read about the assembler’s convenience features
  • Learn the Intel 4004 instruction set
  • Write your own 4004 programs

Build docs developers (and LLMs) love

Get started for freeTalk to us