TempleOS Demystified: Understanding the “Divine” Operating System and Avoiding Common Pitfalls

How many operating systems have you seen that were written by a single person? That kind of feat was really only common in the early days of modern computing. TempleOS’s creator, Terry Davis—an extraordinarily bold figure—wasn’t afraid to go back to basics to deliver something truly remarkable. Let’s install TempleOS and get familiar with the fundamentals of this genuinely one-of-a-kind operating system.

One of TempleOS’s most striking features is evident as early as the boot process.

As you can see, the first thing TempleOS loads is the compiler. It immediately compiles the entire user-space of the OS from source code written in HolyC (“Holy C”).

In Parallels, the boot process stalls at those lines, but VMware and VirtualBox don’t have this issue. We went with the latter (VirtualBox) and, per the developer’s recommendation, set a 64-bit CPU architecture and 512 MB of RAM.

First Look at TempleOS

It’s hard to convey the sense of grace that comes over you when you first boot up TempleOS. And this modest screenshot certainly doesn’t do it justice. Two cursors blink on the screen, and each window’s title bar has a scrolling marquee. It feels like a full-on celebration.

As you can see, the screen is split in two, and if that brings Norton Commander to mind, don’t jump to conclusions. This is a fully fledged window manager—you can drag windows with the mouse, change their order, resize them, and more.

First, close the hint pop-up, click on the left side of the screen, and press y to confirm installing the system image to the virtual machine’s disk. You can also run directly from the Live CD, but then you won’t be able to save files.

Once the installation is complete, shut down the VM, detach the Live CD image, and—fingers crossed—power it back on. TempleOS is now installed on drive C:.

As you can see, everything runs very fast despite the on-the-fly compilation. That’s because TempleOS leaves out a lot of the stuff that bogs down modern systems. Specifically, there are no drivers for most devices, no networking support, and no memory protection. Who exactly is memory supposed to be protected from if you’re the only one at the keyboard? All programs run in kernel mode—it’s efficient and, most of the time, it doesn’t cause any problems.

To quickly appreciate the full power and elegance of TempleOS, click the Menu button that flashes at the top of any window.

As you can see, TempleOS can render not just text, but graphics, animation, and even 3D models. Just look at those spinning tanks and the little human figures on the icons. Take a good look. A little longer. Now tell me—can your OS render 3D as an app icon? Thought so. It can’t!

Before you, dazzled by TempleOS’s visual beauty, dive into its apps and games, let me draw your attention to its inner elegance. That gorgeous menu you see is just a regular TempleOS document located in the Home folder, named PersonalMenu.DD.Z. You can edit it or create your own!

Try pressing Ctrl+T to view its text representation.

The .DD extension indicates the file is a DolDoc document. It’s a hypertext markup format, somewhere between RTF and HTML. Text wrapped in dollar signs ($…$) contains short tags and their parameters. This lets you embed images, macros, links to other documents, help pages, verses from Scripture, text or executable files, 3D models, or even audio. DolDoc also supports interactive elements like buttons, checkboxes, and tree views.

Here’s another fun fact. The second extension (Z) indicates the file is archived. When you open such files, TempleOS automatically decompresses the data and recompresses it on save.

Games

We’ll come back to the DolDoc format a bit later; for now, a quick break for some games. Terry Davis, being an honest and modest guy, split them ahead of time into two groups: Fun Games and Unfun Games. Compare that to any Linux distro, where no one warns you that out of twenty games the only thing worth playing is Pingus—and, if you’re being generous, Tux Racer.

Unfortunately, Davis’s foresight doesn’t help, and even the games in the Fun section will only appeal to the least demanding players.

First, we fired up the Varoom race, but couldn’t successfully complete a single lap.

Next we checked out the KeepAway basketball simulator, where headless characters slowly amble after the ball. Occasionally you can pick it up and pass it to a teammate, but it’s not exactly fun.

We weren’t impressed with the ToTheFront strategy either: just a green screen with blinking, cryptic symbols. Trying to decipher their meaning—or the rules of the game—felt like a waste of time.

The game Wenceslas has an ambiguous storyline: the protagonist wanders around setting trees on fire near a snowbound house so the peasants can warm themselves. We couldn’t figure out whether there’s anything else to do.

Among the unfinished games (Code Scraps), we found an intriguing prototype of a roguelike RPG called DunGen. The hero roams a randomly generated dungeon and encounters enemies. The enemies don’t react to him at all.

ZoneOut is a game about swarms of pink tanks in the desert. Shoot them and they turn blue and start bouncing. If one of them runs into you, the game slows to a crawl.

So, games clearly aren’t TempleOS’s strong suit. Still, we appreciated the warning that greeted us before launching the pink tanks game: “I didn’t copy the original, and this game is deliberately lousy. I wrote it purely for demonstration purposes. Write games, don’t play them.” Mystery solved!

HolyC and the Command Line

Let’s heed some sound advice and see how to program in TempleOS. But first, you’ll need to learn the basics of its command line. You can’t just wing it: if you instinctively type dir or ls, you’ll be greeted with ominous error messages.

The thing is, this isn’t a command shell—it’s the HolyC interpreter (more precisely, a JIT compiler). In other words, you’re meant to enter single-line C programs, which are compiled and executed immediately.

To list a directory’s contents, run

In HolyC, you can omit parentheses for functions called without arguments. But if you want to display the contents of a specific directory, pass its path as a parameter. The same applies to the Cd command (change directory):

However, it’s much easier to navigate directories by simply clicking the folder names. Console output—like everything you see in TempleOS—is a DolDoc document, so file and folder names are just hyperlinks!

Here’s a brain teaser: how do you run a program from the command line? C doesn’t have functions like eval that you find in dynamic languages. But it does have the #include directive, which lets you insert one C file into another. That’s exactly what we’ll use:

Instead of #include, the contents of the .HC (HolyC) file will be inlined, compiled, and executed on the spot. Pretty neat! By the way, you don’t have to type #include every time—just right-click the file name and choose Include from the context menu.

To view a file’s contents, click its name with the left mouse button. Pick any .HC file and you’ll see the programs aren’t precompiled. You can view and edit the source code at any time.

At first glance, HolyC looks like C++, but a closer look reveals some differences. For example, there’s no main() function; instead, code runs sequentially, like in BASIC or JavaScript. That’s why anything you type at the command line executes immediately.

You might also notice that Davis freely uses Greek letters in his code. That’s possible because TempleOS is advanced enough to support 8-bit extended ASCII.

If that’s not enough to impress you, open any game file and behold the unthinkable: the sprites are embedded right in the code!

Hover over a sprite and press Ctrl+R to bring up the edit menu. TempleOS doesn’t have a dedicated graphics editor, but you don’t really need one—you can just switch tools as needed and draw whatever you like.

As you’ve probably guessed, HolyC source code is just DolDoc documents, like everything else you see in TempleOS. That’s why you can embed images in them directly.

Editing DolDoc

Well, it’s time to unravel the mysteries of DolDoc and create your own document. It couldn’t be easier—just use the Ed command:

A new document will open in the editor right away—feel free to jot down any bright ideas. If nothing worthwhile comes to mind, open the Insert menu and try one of the built-in “oracles.” The GodWord command inserts a pseudo-random (that is, divinely selected) word from the Bible; GodBiblePassage inserts a random passage of Scripture; and GodSong and GodDoodle are for generating and inserting pseudo-random melodies and images.

Before you spend the rest of the day digging through whatever the “oracle” spits out, let me show you another handy menu option — Insert → TextWidgets. There are plenty of neat items here, but the most useful is the hyperlink. To reference another document, choose Link, then pick the link type in the next menu. You can link to a predefined anchor, a substring, a specific line number, and so on.

For example, let’s create a link to the Doc2.DD file.

Press Esc to confirm, and you’ll see the link added to the text.

Now, if you press Ctrl+T, you’ll see what the link looks like in its text representation.

Here it is, on the last line:

The $ characters delimit the tag, LK is the link shortcode, after a comma comes the link text in quotes, and the A parameter specifies the file path and the line number within it. As you can see, nothing complicated.

Now let’s see how to insert an image into the text. Choose Insert → GraphicResource → Make Sprite and, for example, PolyLine. Note that wherever you draw the image, that’s exactly where it will be inserted into the text. Convenient and straightforward!

Right‑click to finish the outline. If you’re done with the image, press Esc to return to editing the document (and don’t worry about the blinking—the outline is flashing because the text cursor is on its reference number). If you need to add something else, right‑click again to return to the shape selection menu. When the image is ready, choose Exit Sprite at the bottom.

By the way, you can draw not just flat shapes but 3D ones too! In the sprite editing menu there’s a Create or Edit 3D Mesh option that takes you into a 3D editor. Even the author admits that 3D modeling is a pain in the ass, but with a little divine help we still managed to crank out a decent red triangle.

Honestly, we can say the DolDoc editor is the best part of TempleOS. It turns the system into a remarkably creative tool that helps you create and praise the Lord.

By the way, Davis himself likes to draw comics in this editor about Moses talking with God. For example, Moses says, “Harps are too heavy,” and God replies, “We need to reinforce the clouds.”

Final thoughts

So, we’ve introduced you to the basics of TempleOS. This modest overview barely scratches the surface of the features and quirks of this remarkable system, but if you’re up for the challenge, dive into the manuals—you’ll find a treasure trove of knowledge you never imagined.

We would have included links to the relevant help pages, but since you’re not reading this inside TempleOS, you won’t be able to follow them. No worries — you can find the system help links in any terminal window or in the home menu.

For example, the list of built-in commands for file operations is extremely useful.

We also recommend reading the FAQ and other introductory sections. There you’ll find useful tips like: “If you modify files in the Home directory, don’t forget to reboot. It’s good practice to have two TempleOS partitions on the disk in case you make a syntax error in one of the startup files and the system can’t boot. Just boot from the second partition and mount the first with the Mount() function.”

For best productivity, learn the keyboard shortcuts and other time-savers. For example, the Space bar selects menu items, and a double right-click almost always means “Back.”

Bottom line: learn, experiment, and be grateful you can choose the operating system that best fits your taste and judgment!