Technical Docs

How to read the Apollo-11 source code: AGC command module and lunar module program reading guide

Introducing Comanche055 and Luminary099 in the chrislgarry/Apollo-11 repository, explaining how to download and locate the navigation program, understand the AGC assembly file, and use Virtual AGC to continue compilation research.

chrislgarry/Apollo-11 Contains a source code transcription for the Apollo 11 navigation computer. This is not a commemorative code imitation, but the AGC source code digitized from the paper program list kept by the MIT Museum, including Comanche055 used by the command module and Luminary099 used by the lunar module.

When opening the warehouse for the first time, the most confusing part is: Why are there no familiar src, build scripts and application entries? The answer is that this software is from 1969, and its organization, assembly tools, and hardware models all predate modern software engineering practices. This article starts with the table of contents and gives a route that can actually be read.

Quick Answer

Clone the source code first:

1
2

git clone https://github.com/chrislgarry/Apollo-11.git
cd Apollo-11

Then select the directory according to the spacecraft module:

  • Comanche055/: Colossus 2A program for the Command Module;
  • Luminary099/: Luminary 1A program for the Lunar Module.

It is recommended not to read line by line from the beginning. First open README.md and MAIN.agc in each directory, and then view ALARM_AND_ABORT.agc, EXECUTIVE.agc, DISPLAY_INTERFACE_ROUTINES.agc and other modules according to tasks. If you want to compile or simulate running, you should turn to Virtual AGC. The Apollo-11 warehouse itself is mainly responsible for the preservation and proofreading of historical source code.

What is stored in this warehouse?

The Apollo Guidance Computer, or AGC for short, is an important part of the Apollo spacecraft guidance, navigation and control system. Apollo 11’s command module and lunar module had different missions, so two sets of procedures were used:

Table of contents Corresponding program Purpose
Comanche055 Colossus 2A / Comanche revision 055 Command module navigation, attitude control, orbit calculation and reentry tasks
Luminary099 Luminary 1A / LMY99 Lunar module descent, landing, ascent and rendezvous missions

Warehouse instructions record assembly dates as April 1, 1969, and July 14, 1969. The source code is transcribed and organized by relevant personnel of the Virtual AGC community and MIT Museum based on scanned copies of the paper list, and is continuously subject to correction against the original scanned copies.

This means that the main goal of the repository is to faithfully preserve historical material, not to reconstruct programs into modern code. When you see spelling, comment formatting, or unfamiliar module boundaries, it’s not appropriate to “fix” them directly according to today’s coding standards.

Why the source code is split into a large number of .agc files

The original program is a single piece of code that is assembled as a whole. At that time, there was no compilation and linking process common today, and the program modules were closer to stacks of punched cards assembled in sequence. In order to facilitate management of the digital project, the huge source code was split into multiple .agc files, and then the overall order was restored through the inclusion relationship.

Therefore, file splitting here represents natural subroutine boundaries, but is not equivalent to independent compilation units in modern projects. Each directory’s README.md provides a Source Code Index, which corresponds the file to the original print list page number. It should be read as a table of contents and not as a general project description.

AGC’s original YUL and later GAP are no longer available directly from the assembler. yaYUL provided by the Virtual AGC project uses a slightly different input format, and the transcription source code in the warehouse has also been adapted for yaYUL.

1. First read the contract, assembly information and entrance

Starting from the following three files, you can first create an overall picture of the program:

1
2
3

CONTRACT_AND_APPROVALS.agc
ASSEMBLY_AND_OPERATION_INFORMATION.agc
MAIN.agc

CONTRACT_AND_APPROVALS.agc Preserves project identity, contract and approval information. ASSEMBLY_AND_OPERATION_INFORMATION.agc Describes assembly structures and subroutine calls. MAIN.agc incorporates multiple source code fragments into the complete program in sequence.

2. Look at the modules with clear task meanings

Compared with studying the instruction set directly, it is easier to enter the state by first selecting a module whose file name can explain its purpose:

1
2
3
4
5
6

ALARM_AND_ABORT.agc
FRESH_START_AND_RESTART.agc
EXECUTIVE.agc
WAITLIST.agc
DISPLAY_INTERFACE_ROUTINES.agc
PINBALL_GAME_BUTTONS_AND_LIGHTS.agc

Among them, EXECUTIVE.agc and WAITLIST.agc are helpful for understanding task scheduling; PINBALL_GAME_BUTTONS_AND_LIGHTS.agc is related to the display and keyboard interface used by astronauts; the alarm and restart module can see how the system handles abnormal conditions.

3. Finally enter the specific flight stage

The command module directory contains programs such as orbit integration, automatic maneuvering, reentry control, and attitude control. The lunar module catalog is more suitable for starting from tasks such as descent guidance, landing phase, digital autopilot and ascent procedures.

The Pxx in the file name usually corresponds to the program number selected by the astronauts through DSKY. For example, P40-P47.agc, P51-P53.agc and other files can be seen in the warehouse. Rxx is often used for routine numbers. Before reading these files, it is much more effective to understand the corresponding flight stages and operating procedures than to translate the assembly instructions alone.

Quickly locate code locally

There are many warehouse files, and using text search is more convenient than clicking one by one. Runs in Git Bash, Linux or macOS:

1
2
3

find Comanche055 Luminary099 -name "*.agc" | sort
grep -Rni "ALARM" Comanche055 Luminary099
grep -Rni "RESTART" Comanche055 Luminary099

When ripgrep is installed, a faster search method is available:

1
2

rg -n "ALARM|RESTART" Comanche055 Luminary099 -g "*.agc"
rg -n "1201|1202" Luminary099 -g "*.agc"

The second command can be used to find the relevant locations of the famous 1201, 1202 program alarms, but do not conclude the complete triggering logic based on just one string match. The alarm number, generation conditions, task scheduling and display process may be scattered in multiple modules and need to be read in conjunction with the calling relationship.

In PowerShell you can list the source code like this:

1
2

Get-ChildItem -Path Comanche055,Luminary099 -Filter *.agc -Recurse
Select-String -Path Comanche055\*.agc,Luminary099\*.agc -Pattern 'ALARM|RESTART'

.agc How should the file look?

AGC assembly is very different from the x86 or ARM assembly common today. When faced with a line of code, you can identify the following parts in order:

  1. Label: Name the program entry or data location;
  2. Operation code: AGC instruction or interpreter instruction;
  3. Operand: address, constant or symbol;
  4. Notes: Explain algorithms, flight conditions and engineering limitations;
  5. Page number marking: Helps correspond to the original paper list and the scanned copy.

Don’t just think of comments as interesting text. For historical software, comments often serve as requirements descriptions, operating conditions, and design reasons. Read in conjunction with adjacent modules, symbol definitions, and original manifest page numbers to avoid misinterpreting a partial label as a complete function.

How to compile and simulate running

The README of the Apollo-11 repository clearly points the compilation requirements to Virtual AGC. The recommended process is:

  1. Keep the Apollo-11 warehouse as a historical source code and file index;
  2. Read the build instructions for the current platform of Virtual AGC;
  3. Use the yaYUL assembler and AGC simulator;
  4. Select Comanche or Luminary source code according to the target program version;
  5. Compare the assembly results and checksums with the reference information provided by the project.

The platforms, dependencies, and build commands supported by Virtual AGC may change with versions, and the latest documentation in its warehouse should prevail before execution. Do not assume that running the generic make or npm install in the Apollo-11 root directory will result in a flight program image; the presence of modern project files in the root directory does not change the actual toolchain of the historical source code of .agc.

How to verify that a transcription is accurate

This project welcomes contributions, but corrections must be based on original scans. When you find suspicious characters or spellings, it is recommended to follow the following steps:

  1. Find the corresponding original page number in the directory README.md;
  2. Open the Comanche 055 or Luminary 099 scan data linked to the project;
  3. Compare codes, comments, symbols and page number marks;
  4. Read CONTRIBUTING.md;
  5. Submit a Pull Request containing only explicit transcription differences.

Do not batch-format source code to unify case, correct historical spelling, or adopt modern formatting. Historical archival projects strive for traceability above all else, and a seemingly neat mechanical modification can make proofreading more difficult.

FAQ

Was this written by Margaret Hamilton alone?

No. The warehouse’s contracts and approvals list Margaret H. Hamilton as the Colossus Programming Leader, but also record multiple project leaders. Apollo software is built as a team effort, and it is not accurate to attribute the entire warehouse to a single programmer.

Are the codes on GitHub the original files saved by the spacecraft back then?

More precisely, it is a version transcribed and adapted for yaYUL from a scan of the paper inventory maintained at the MIT Museum. The warehouse retains the original program content and page number correspondence, but the carrier and format have been digitally organized.

Why is it divided into two sets of programs: the command module and the lunar module?

The two aircraft have different missions. The command module has to handle orbit, attitude, rendezvous and reentry, while the lunar module has to complete descent, landing, lunar surface takeoff and rendezvous, so each uses an AGC program designed for the mission.

Can these codes be directly used in modern aerospace systems?

This should not be done. This repository is suitable for historical research, computer architecture learning, and simulation experiments, and is not production software proven in modern environments. Modern safety-critical systems require independent requirements, verification, certification and hardware adaptation processes.

Summary

The correct entry point for reading the Apollo 11 source code is not to read hard from the first line to the last line, but to first distinguish Comanche055 and Luminary099, use the directory index to find the task module, and then combine the original page number, AGC instruction set and Virtual AGC tool chain to drill down layer by layer. The repository is both a searchable archive of historical software and a demonstration of how flight control, mission scheduling, alarm recovery and human-computer interaction were organized into complete systems on computers with extremely limited resources.

Project address: chrislgarry/Apollo-11

Simulation and compilation tools: Virtual AGC