ingramj.net

How I Think About THAC0

Sat, 20 Oct 2018 16:44:42 -0500

THAC0 stands for “To Hit Armor Class 0,” and it’s one of the two ways we used back in the day to figure out if an attack succeeded or not. (The other way was looking it up in a table.) The AD&D 2nd Edition Player’s Handbook says that “Using THAC0 speeds the play of combat greatly,” just before giving this description of how it works:

The first step in making an attack roll is to find the number needed to hit the target. Subtract the Armor Class of the target from the attacker’s THAC0. (Remember that if the Armor Class is a negative number, you add it to the attacker’s THACO.) The character has to roll the resulting number, or higher, on 1d20 to hit the target. […] THAC0 is modified by weapon bonuses, Strength bonuses, and the like […] Figure Strength and weapon modifiers, subtract the total from the base THAC0, and record this modified THACO with each weapon on the character sheet. Subtract the target’s Armor Class from this modified THAC0 when determining the hit roll.

I omitted some worked examples from that quote, but that is the official description of how attack rolls worked in 2nd edition. If you find it confusing, you aren’t alone. Starting with the 3rd edition in 2000 (that’s right: D&D 3e is old enough to vote!), when they essentially made attack rolls the core mechanic, Wizards of the Coast also switched things around so that instead of using the defender’s armor class to calculate the target number, the armor class is the target number. Roll a d20, apply any bonuses and penalties, and if you get a number greater than the target’s armor class, it’s a hit. A higher AC means you’re harder to hit. It ends up working out the same as the old system, but it’s simpler in theory, if not in practice.

Here’s the thing: I actually like descending armor class, and think THAC0 is a great idea. It’s just really poorly explained. Instead of adding and subtracting things from THAC0 to get a target number, as in the official description, I just add everything to the attack roll instead, including the defender’s armor class. In some ways this is like the third edition method, which also has modifiers on the attack roll, but instead of the target number changing depending on what you’re swinging at, the target number is always your THAC0. The defender’s armor class becomes just another modifier on the attack roll.

If you think about it that way, then descending armor class makes a lot more sense. Instead of using a human in normal clothing’s 9 AC as the baseline, use an armor class of 0 as the baseline. Anything with less armor than that is easier to hit, granting a bonus on the attack roll. Attacking an unarmored target is very easy – you get a whopping +9 on your roll! Going in the other direction, a negative armor class mean you’re very difficult to hit – anyone taking a swing at you will get a penalty on their attack roll.

The way this ends up working for the GM at the table is pretty simple. Make a note of all the PC’s armor classes and THACOs, just as you would for all your monsters’ stat blocks. Whenever a PC attacks a monster, they’ll roll a d20 and add all the modifiers they know about from strength, enchanted weapons, etc. Then you add the monster’s armor class to that roll and compare it to the attacker’s THAC0 to decide if it’s a hit. When a monster attacks a PC, do the same thing: add the PC’s armor class to the roll, along with any other modifiers, and compare it to the monster’s THAC0. Done.

Example time. Let’s say you have a level 1 fighter (THAC0 19, AC 5) attacking an orc (THAC0 18, AC 6). The player rolls a 12, and adds their +1 strength bonus for a total of 13. You add the orc’s 6 AC to that and get 19. That’s the figher’s THACO, so it’s a hit, but just barely! The orc takes a swing at the fighter, and rolls a 9. You add the fighter’s 5 AC to get a 14, which is less than the orc’s THAC0. It’s a miss! As long as you have the THAC0 and AC for everyone involved, running combat with descending armor class is easy.

This is the way I’ve been using descending armor class and THAC0 for years, and it works well for me. Delta, from Delta’s D&D Hotspot takes the “armor class is a modifier on the attack roll” idea a bit further. Instead of having a THAC0 that changes as characters level up, he came up with the Target 20 system, where the target number is always 20, and the attacker’s level joins the defender’s armor class as just another attack roll modifier.

Swords and Wizardry One Shot

Thu, 05 Jul 2018 17:20:00 -0500

A couple of summers ago, I ran a West Marches-style campaign for several of my coworkers called “Riverkeep”, using the Swords & Wizardry Complete rules. There’s a lot of prep work for that sort of campaign, even if you fill in most of the map with pre-existing modules as I did. On top of that, each session had between 8 and 12 players, which is a lot of fun, but also exhausting to run. As a result, the campaign only lasted a few months before going on indefinite hiatus, due to DM fatigue. (Note: I don’t blame the players at all. They were and are wonderful people.) A couple of weeks ago the subject came up in conversation again, and I offered to do a one shot session, unconnected to the previous campaign, for 3 to 6 players. I ended up getting four takers: a couple of campaign veterans who were already familiar with Swords & Wizardry; one guy who had played a bit of 4th and 5th Edition D&D and Dungeon World, but not any older rules; and one guy who had never played a table top RPG before, and whom I’d promised wouldn’t need to read any rules beforehand. We decided to play a single session of about four hours, and in order to make the most of our time, I’d bring several pregenerated characters for them to choose from.

Setting up

Since I didn’t have much time / didn’t want to do too much prep work, I looked around for a pre-existing module suitable for four characters of around level three, and came across Tomb of the Mummy Priest at the Basic Fantasy RPG site, which has some fantastic resources, even if you’re using a different set of old-school RPG rules. The only conversion I needed to do was from BFRPG’s ascending AC values to S&W’s descending system. That being done, I created a set of six characters for the four players to choose from, so that they’d each have at least three options. I made them a mix of classes, but avoided multiclass demihumans in order to keep things simple. I ended up with two human clerics, a human fighter, a dwarf fighter, a halfling thief, and a human magic-user. After rolling their attributes and making a few adjustments, I gave each 5,500 XP and added their prime requisite bonuses. That gave the clerics and the thief enough experience for level four, and the fighters and the magic-user enough for level three. Then I picked out equipment and spells, and was ready to start filling out character sheets.

I tried to find some existing form-fillable sheets, but couldn’t find any that I liked, and I also didn’t want to fill six sheets out by hand. Instead, I ended up creating the sheets using Keynote, which has surprisingly decent page-layout features. The six characters fit on three sheets of letter-sized paper, and then I used a fourth sheet for the magic-user’s spellbook and scroll. I also printed them out smaller sized with four characters to a page so I could keep track of them behind my DM’s screen (a binder and a manila folder with some tables taped to the inside).

A couple of the characters. (Click for PDF)

The session

One of the players offered to host the game at his house, so on game day I headed over, binder, character sheets, dice, rule books¹, and 17" x 22" pad of grid paper² in tow. Once everyone had arrived, the players chose their characters and gave them names, and the spell casters picked their spells. I didn’t share the module name (Tomb of the Mummy Priest) with the players, but strongly hinted that they’d want at least one cleric, and I sort of expected them to also take either two fighters, or another cleric and a fighter, and either the thief or the magic-user. Instead, the party consisted of:

Jora Orcsbane the Human Fighter, played by one of the campaign veterans who likes to keep it simple.
Zur III the Human Cleric, played by the other veteran, and named after his two previous characters: Zur the Enchanter (a Ranger), and Zur’s Brother (also a Ranger).
Xanders the Human Magic-User, played by the guy who’d only played newer editions before, and named after Colonel Sanders because of the 11 secret herbs and spices (spell components) I’d placed in his equipment list.
Sticky Fingers the Halfling Thief, played by the new guy.

I was a little worried about the two newer players playing relatively low-HP specialists, but at least the magic-user had access to some decent spells, and the thief had bonuses from high dexterity and constitution and an additional +1 to hit with missiles. Not too shabby.

Then we got started. There’s some lengthy session notes containing spoilers ahead, so if you’d like to, you can skip to the end.

Spoilers

I gave the players a bit of background on their characters’ situation: They’d recently been hired to escort a trade caravan on a route that took it through the small village of Mudar, on the edge of a great desert. However, after a misunderstanding between the characters and the caravan leader (something about some coins and items that had gone missing), they’d been left in Mudar while the caravan continued on without them. After overcoming the villages initial distrust ~~by blowing all their cash in the village taverns~~ with their generosity and good natures, the players learned a couple of things about the area: (1) there’s supposedly an old abandoned temple of a long-dead water deity hidden in a canyon, full of treasure, and just a few hours ride out in the desert; and (2) several villagers have gone missing in the night recently, and no one knows what’s happened to them.

Since we didn’t have a whole lot of time, we didn’t play out any of the town scenes, the journey to the canyon, or finding the tomb. I just placed the party at the entrance, and mentioned that they’d only found it because of all of the footprints leading in and out. A full session report would make this already lengthy post even longer, so here are some of the highlights:

Entrance and main hall.

The thief entered first, staying close to the walls and trying to be quiet. That’s how he noticed how all the footprints went around a section of floor about 10’ down the passageway (area 1 on the map). The party investigated a bit, thinking it might have been a trigger for some sort of arrow trap, but moved on before figuring out it was a pit trap, with a recently reanimated corpse inside

The searched the entire main hall (area 2), and a little bit down each passageway before I rolled a 1 and the seven bandits arrived from the western passage. The party won the surprise roll, and quickly set up an ambush. The combat lasted only a couple of rounds, before they took the last surviving bandit hostage and got some exposition out of him.

Storage and burial chambers.

Buoyed by this early success, the party made it’s way down the western passageway, through the now-abandoned sleeping quarters (area 3) and oil storage room (area 4). As they entered area 6, three mummified crocodiles emerged from their sarcophagi and attacked. This was a tougher fight than the one with the bandits, and the party had a tough time with their attack rolls, but eventually Zur managed to turn back the crocodiles, who retreated to the far side of their chamber. Xanders and Sticky Fingers improvised a trap in the entryway using a large jar of oil and a torch, reasoning that the crocodiles weren’t intelligent, and would likely knock over the jar and set themselves on fire if they tried coming after the party again.

Still feeling pretty confident at this point, they entered the burial chamber (area 7), where the module’s boss monster laid in wait. As they drew near the sarcophagus to get a better look at its hieroglyphics, Kutan Tahkmet, the titular Mummy Priest whose tomb the party were robbing, burst out and started attacking Jora. The module actually boosted the mummy’s stats from what the BFRPG manual lists, giving it darkness, cause fear, hold person, and resist fire spells. I just went with the base mummy stats from the Swords & Wizardry manual instead, figuring that would be challenge enough.

It turns out I was right, because after a few rounds of combat, the characters hadn’t managed to do very much damage to Kutan, but he’d reduced Jora to 0 hit points (unconscious, but stable) and given him a bad case of mummy rot to boot. After Zur’s cure light wounds spell failed to heal Jora, they started making escape plans. Xanders cast a web spell at the mummy, while Zur and Sticky Fingers pulled the comatose fighter to safety. They decided to head back to town to get some help for Jora, which ended up costing them the only treasure they’d found so far: a 600gp set of ruby earrings.

Down the eastern passageway.

When the party returned to the tomb after a couple of days, they found that the bodies of the bandits they had killed had been dragged from the main hall, down the eastern passageway. Scouting ahead, Sticky Fingers saw that the trail turned to the south, into area 8, where he noticed movement in the dark pool from the balcony above. Assuming it was more crocodiles (it wasn’t), and not seeing any obvious treasure, he decided to check to the north instead. In that direction, he saw a lit chamber with a bearded man at an altar, preparing to sacrifice a villager, and surrounded by robed figures.

Since they had the element of surprise, Xanders cast a sleep spell into the ritual chamber from the intersection just north of the pool room, which worked on seven of the twelve robed figures, and then the rest of the party rushed in to battle the remaining acolytes and their leader, Aram. After just a few rounds of combat, Aram was down to just 3 hit points and all of his followers had been slain. He surrendered to the player characters, who bound him with a rope, and were just about to start searching the room when Kutan Tahkmet made his entrance though the secret passage between areas 7 and 9.

The second battle with the mummy priest went only slightly better than the first, Jora and Zur were both afflicted with mummy rot, but still standing. Meanwhile, Xanders and Sticky Fingers tried to figure out a way to knock down one of the large oil lanterns that hung from the ceiling on top of the rampaging mummy, and they were all wondering just how many hit points it could possibly have. (It was 25.) Aram started shouting at the PCs, trying to get them to untie him so he could join the melee with his battleaxe +1, which they eventually agreed to do.

After a few more rounds, they managed to destroy Kutan, and the players all gave a sigh of relief. Aram immediately tried to run away down the secret passage to the burial chamber, Xanders hit him with a sleep spell before he could get very far. They searched the room and found all the treasure that had been stashed in the corners, and then discovered the five other prisoners still chained up in area 10. After a bit of discussion about what to do with Aram, they decided to turn him over to the captives, who dragged the bandit-turned-cultist down to the pool in area 8 and threw him in. The bodies he had been disposing of in the pool had returned to life, and tore Aram to pieces as the party gathered up all the treasure they could carry and made their exit.

Conclusion

I hadn’t run Tomb of the Mummy Priest before, and even though it’s a relatively small, uncomplicated module, I was surprised that we made it all the way through in about four hours. The Egyptian-themed setting was a nice change of pace from the vaguely Medieval European default fantasy setting. If this adventure were part of a campaign instead of a one shot, then I’d be tempted to use Stygia from Robert Howard’s Conan stories as the historical background for the tomb.

The players all had fun, and they also did very well, including the new guy, who by picking the thief had ended up with what is probably the the most challenging class to play from original D&D his first time out. I always make monster attack and damage rolls in the open, and I got a kick out of watching their reactions, and also how quickly their cockiness faded after their first, nearly disastrous run-in with the boss monster. Towards the end of the final, climactic battle, I moved from my seat behind the DM’s screen to get closer to the map that they were gathered around, and cheered along with them when they finally brought down the mummy priest. They’d really earned it.

As mentioned, Swords & Wizardry Complete (with cover art by Erol Otus!), and also my new print copy of Basic Fantasy RPG Core Rules to help me fill in some gaps in the S&W rules. ↩︎
The players do their own mapping in my games, and the “double tabloid”-sized paper gives them plenty of room to make it big enough for everyone to see. This particular pad is from Bienfang, but while the 11" x 17" tabloid size is relatively easy to find, the 17" x 22" isn’t. I got lucky and found it at a local Office Depot, but it doesn’t seem to be listed on their website anymore. ↩︎

A 6502 assembly idiom in Excitebike

Sun, 10 Dec 2017 13:12:42 -0600

Sometimes I like to disassemble ROM dumps for old NES games to figure out how they work. It’s sort of like putting together a puzzle without knowing what the picture will look like beforehand. You start disassembling opcodes at a known entry point (the NES’s 6502-based CPU will jump to the address stored at $FFFC-$FFFD in the ROM cartridge when the machine resets) and follow the control flow through the rest of the ROM. The puzzle isn’t the disassembly itself, which is a purely mechanical process. It’s figuring out what the assembly code is doing, and why it’s doing it. And along the way you can sometimes find interesting bits of code that are unlike what a modern programmer would (or could) write in a high level language. I found one such bit of code in the initialization routines for Excitebike.

This article isn’t about the details of NES programming, but there are a couple of things worth mentioning before getting to the code. First, the NES uses memory-mapped IO, so hardware is controlled by writing to certain memory locations instead of by using special CPU instructions. Second, the NES has a custom chip called the Picture Processing Unit (PPU) that can, among other things, generate a non-maskable interrupt (NMI) at the begining of the vertical blanking interval (or “vblank”). That’s the time between when the last line of the screen is rendered and the first line of the next frame is started, when input can be processed and sprites can be updated.

When the NES starts up, the PPU disables NMIs until bit 7 of address $2000 (the PPUCTRL register) is set. That gives the game’s startup code time to perform whatever initialization it requires - clearing RAM, setting up hardware, etc. Once all that’s done, most games will enable NMIs and enter an infinite loop that gets interrupted once per vblank to let the main game logic run. Sometimes games need to disable NMIs again after that. Excitebike, for example, jumps back into the reset handler after exiting the track editor so it can restart at the main menu.¹ And that brings us to the code fragment that I wanted to talk about:²

disable_nmi:
        lda $10         ; First load the cached value for PPUCTRL,
        and #$7f        ; then clear bit 7 (disable NMI), and continue to...
set_ppuctrl:
        sta $2000       ; First write the value to PPUCTRL register,
        sta $10         ; then cache it in the zero page,
        rts             ; and return to last jsr.

I’ll start with the second routine, set_ppuctrl. This routine simply writes the value in the CPU’s accumulator to the PPUCTRL register, and also caches it in address $10 of the zero page before returning. The value needs to be cached in RAM, because the PPUCTRL register is read-only. If the value wasn’t also stored somewhere else, it would be impossible to update individual bits. And that’s exactly what the disable_nmi routine does. It loads the cached value, clears bit 7 (the one that controls NMIs), and then flows right into the set_ppuctrl routine. That is, the two routines overlap in memory. And why not? Duplicating the code would be a waste, and since you have control over exactly where code exists in memory when programming in assembly, you can arrange things so that you can avoid an extra jmp or jsr instruction.

But you can’t always arrange things so conveniently. There’s another routine in Excitebike’s initialization code that needs to write a value to PPUCTRL, but it can’t just let control fall though to set_ppuctrl, because disable_nmi is in the way:³

some_init_routine:
        ; I've omitted some irrelevant instructions here.
        sta $fc         ; Clear a flag in the 6502's "zero page".
        lda #$10        ; We also want to set PPUCTRL to a fixed value.
        bne set_ppuctrl ; This unconditionally skips over disable_nmi.
disable_nmi:
        ...             ; As before.
set_ppuctrl:
        ...             ; As before.

The 6502 instruction set doesn’t include an unconditional relative branch, so this routine uses a bne instruction that is always followed, because lda with a non-zero argument clears the CPU’s zero flag. So instead of using a regular unconditional jmp (3 bytes, 3 cycles), or a jsr subroutine call (3 bytes, 6 cycles, and a bit of stack space) to get where it needs to go next, this routine gets almost as much benefit from being near set_ppuctrl as disable_nmi does, for just the cost of a single “unconditional” bne (2 bytes, 3 cycles).

That’s also an interesting process. The reset handler checks for a couple of values that it sets at particular addresses in RAM to decide whether or not to clear the memory used by the track editor. That way it can behave differently if it’s jumped to than if there was an actual hardware reset. ↩︎
The labels and comments are my own. I have no idea what the original programmer called these routines, so coming up with good names and comments is part of the disassembly puzzle. ↩︎
I’m not actually sure what else the routine does, or why. This disassembly project is a work in progress. ↩︎

Substrings With Printf

Sun, 29 Oct 2017 10:30:40 -0500

You can specify a precision with printf’s %s conversion to limit how many characters are printed:

const char *greeting = "Hello, World!\n";
printf("%.5s\n", greeting);  // prints "Hello\n"

But what if you don’t know until runtime how many characters you need?

From man 3 printf:

Instead of a decimal digit string one may write “*” or “*m$” (for some decimal integer m) to specify that the precision is given in the next argument, or in the m-th argument, respectively, which must be of type int.

This is awesome for printing substrings. Example:

struct token {
    const char *start;    // start of the token inside a source string
    int length;           // number of characters in the token
};

void print_token(FILE *out, struct token token)
{
    fprintf(out, "<\"%.*s\">", token.length, token.start);
}

The “*m$” syntax comes from a POSIX extension to the C standard that lets you specify which argument to use for each conversion. This is helpful if you want to use the same argument more than once:

void print_token(FILE *out, struct token token)
{
    fprintf(out, "<\"%1$.*2$s\" (%2$d characters)>",
            token.start, token.length);
}

Note that you can’t mix numbered and unnumbered conversions in the same format string, so if you use *m$ for the precision, you also need to use %m$ for the conversion itself.

Building jlox with Gradle

Sat, 14 Oct 2017 05:15:21 -0500

I just started following along with Bob Nystrom’s Crafting Interpreters book a few days ago, and one of the first things I did was set up a Gradle project for the jlox interpreter. It’s a simple Java application with no external dependencies, so the build script is hardly interesting, except for one thing: starting in Chapter 5, there is a GenerateAst “script” needs to be run before compiling, because it generates source files. Turns out, it’s pretty easy to add a code generation task to a Gradle build.

The first step is to create a buildSrc directory, and move GenerateAst.java into it, following the normal conventions for Java projects – that is, put the source file in buildSrc/src/main/java/com/craftinginterpreters/tool/. Now you can use the GenerateAst class from your build.gradle file, but its interface isn’t really suited for being used programmatically. It has a standard main method that treats the first argument as a path to the output directory, and it passes that path as a String to the defineAst method, like so:

public static void main(String[] args) throws IOException {
  if (args.length != 1) {
    System.err.println("Usage: generate_ast <output directory>");
    System.exit(1);
  }
  String outputDir = args[0];
  defineAst(outputDir, "Expr", Arrays.asList(
  // snip ...
}

private static void defineAst(
    String outputDir, String baseName, List<String> types)
    throws IOException {
  String path = outputDir + "/" + baseName + ".java";
  PrintWriter writer = new PrintWriter(path, "UTF-8");
  // snip ...
}

Since we’ll be using GenerateAst from a Gradle script instead of from the command line, we can just pass in a File object for the output directory, instead of using path strings. Then we can use File’s constructors and methods to create the subdirectories and files that we need.

// this replaces main(String[] args)
public static void run(File outputDir) throws IOException {
  File packageDir = new File(outputDir, "com/craftinginterpreters/lox");
  packageDir.mkdirs();

  defineAst(packageDir, "Expr", Arrays.asList(
  // snip ...
}

private static void defineAst(File outputDir, String baseName,
    List<String> types) throws IOException {
  File outputFile = new File(outputDir, baseName + ".java");
  PrintWriter writer = new PrintWriter(outputFile, "UTF-8");
  // snip ...
}

Now we need to call GenerateAst.run from our build.gradle, and pass it an appropriate output directory. The project’s build directory is a good place for generated files, so we’ll use a subdirectory under that.

def generatedSrcDir = new File(buildDir, "generated/src/main/java/");

task generateAst {
  doLast {
    GenerateAst.run(generatedSrcDir);
  }
}

Running the generateAst task will create Expr.java under the build/generated/src/main/java/ directory, so now we just need to add that directory to the main source set, and run the new task before compiling.

compileJava.dependsOn(generateAst)

sourceSets {
  main {
    java {
      srcDirs += generatedSrcDir
    }
  }
}

And that’s it. Now the code generator will run for every build. If you’re using an IDE, then you’ll also want to run the generateAst task manually after making changes to GenerateAst.java, so the changes to the generated classes will be visible.

A new home on the web

Sun, 10 Sep 2017 17:28:29 -0500

I’ve been a member of SDF Public Access UNIX System for around fifteen years, at the ARPA level for most of that time. They provide a great service, and have hosted various incarnations of my homepage since I first signed up. The most recent was started in November of 2014 as a blog about programming, built with Jekyll and only lasting for a couple of posts (which I have copied over to this site). Then life got busier, and my blog fell by the wayside.

Since 2014, I’ve helped build a new product, went through a corporate acquisiton, started running (and stopped, and started again), bought a house, ran an old-school D&D-ish campaign (now on hiatus¹), learned how to ski (sort of), quit Facebook,² had my tenth wedding anniverary, rode in a hot air balloon, saw Iron Maiden live, played a lot of video games (most recently, Breath of the Wild), and grew and shaved off three beards. But I didn’t do much programming for fun, so I didn’t have a whole lot to write about for a site I’d named “A Programmer’s Homepage”.

Now it seems like a good time to start writing again, with a more general scope. Even though I still like SDF, and have no intention of cancelling my account there,³ I decided a couple of weeks ago that it was finally time to register my own domain, and find a host that provides easier deployments and some more bells and whistles. So I registered ingramj.net (and its .com counterpart) and looked at a few hosting and authoring options before settling on Netlify and Hugo. If you’re a developer, using them is dead simple. Put your site in a repo on one of the big Git hosting sites (I went with GitLab, but they also support GitHub and Bitbucket), and with a surprisingly small amount of configuration, you can deploy changes just by pushing to your master branch. It’s like GitHub pages, but with a lot more features, like one-click SSL certificates for custom domains, form handling, and preview deploys.

Now that I have a new home on the web, I have a few ideas that I’d like to write about. We’ll see how it goes.

I learned that if you offer to run an RPG campaign at a software company, you’ll get a lot of takers. The largest session had a dozen players, two of whom were remote. It was fun, but crazy. ↩︎
I was never going to top “When it comes to eating a lot of tacos, the trick is to get as many down as you can really quickly, before the self-loathing kicks in,” so it was time to move on. Also, it was really bumming me out. ↩︎
I want to get a new t-shirt, since my old one wore out years ago. ↩︎

Unit tests for C, in two macros

Sat, 29 Nov 2014 00:00:00 +0000

No, not the same two macros as MinUnit. These macros have a few more features, and thus require a bit more from the runtime. Together, the two macros are used to define test functions that run code in a new process, and that have consistent return values to indicate whether the test succeeded, failed, or had an error. All of the code in this post is available on GitHub, under the terms of the MIT License. What follows is a description of the code and how it works.

The first macro is called BEGIN_TEST, and it is used to begin a new test definition:

#define BEGIN_TEST(name)                        \
    static int test_##name(void)                \
    {                                           \
        pid_t pid = fork();                     \
        if (pid < 0) {                          \
            return -1;                          \
        }                                       \
        if (pid == 0) {                         \
            int failed = 0;

It starts by defining a new function, whose name is created using the ## token pasting operator. The function is declared static, which isn’t really necessary, but it fits in well with how I write tests: a single “public” function that calls a set of related static test functions and aggregates their results.

The test function forks a new process, so that if the test code segfaults, it won’t take the whole test harness down, and the remaining tests can be run. Forking also allows us to test functions that should cause the process to exit. If the fork fails, then -1 is returned. This is the “error” return value, used to indicate that something has gone wrong while running the test.

The rest of the macro is the start of the child process code, which is where the test code itself lives. The failed variable is a flag, which is provided for convenience. It works with the END_TEST macro:

#define END_TEST(expected)                                      \
            exit(failed ? !expected : expected);                \
        } else {                                                \
            int status;                                         \
            waitpid(pid, &status, 0);                           \
            if (WIFEXITED(status)) {                            \
                return WEXITSTATUS(status) == expected ? 0 : 1; \
            }                                                   \
            return -1;                                          \
        }                                                       \
    }

The expected argument is expected exit status of the child process after a successful run. By making this a parameter, things like the popular “exit with an error status if malloc returns NULL” pattern become testable. However, the most common case is for the exit status to depend on the value of the failed variable, so that’s what the call to exit does. If failed is still 0 by the time the exit line is reached, then the expected exit status is used. Otherwise, !expected (the “unexpected” exit status) is used instead.

The else block is run in the parent process, and it calls waitpid on the child process’s PID, catching the exit status in a variable. If the child process exits normally, then its exit status is compared to the expected value. If they match, then the test function returns 0, which is the “success” value; otherwise, it returns 1, which is the “failed” value. If the child process did not exit normally because was killed by a signal, then -1 (the “error” value) is returned.

The two macros are intended to be used with a block of code in between, which defines a new scope for local variables:

BEGIN_TEST(contrived_example) {
  int a = 1;
  int b = 2;

  if (min(a, b) == b) {
     failed = 1;
  }

} END_TEST(EXIT_SUCCESS)

The preprocessor expands this to something like the following:¹

static int test_contrived_example(void)
{
    pid_t pid = fork();
    if (pid < 0) {
        return -1;
    }
    if (pid == 0) {
        int failed = 0;
        {
            int a = 1;
            int b = 2;

            if (min(a, b) == b) {
                failed = 1;
            }
        }
        exit(failed ? !EXIT_SUCCESS : EXIT_SUCCESS);
    } else {
        int status;
        waitpid(pid, &status, 0);
        if (WIFEXITED(status)) {
            return WEXITSTATUS(status) == EXIT_SUCCESS ? 0 : 1;
        }                      
        return -1;
    }
}

Enhancements

Okay, so I lied a bit in the title. These two macros are sufficient for creating a set of test functions, and once those are created, it’s pretty easy to test their return values in some automated fashion. But by themselves, they make for a pretty bare-bones testing framework.

One easy enhancement is to define some macros for working with the failed variable inside the test blocks. I like FAIL_IF, which sets failed to 1 if some condition holds, and FAIL_UNLESS, which sets it to 1 if the condition t hold:

#define FAIL_IF(cond)     failed = (cond) ? 1 : failed;
#define FAIL_UNLESS(cond) failed = (cond) ? failed : 1;

BEGIN_TEST(total_failure) {
    FAIL_IF(2 == 2);
    FAIL_UNLESS(3 == 4);
} END_TEST(EXIT_SUCCESS)

These new macros are useful for writing tests, but what about running them and gathering results? I use a struct and a macro for this.²

typedef struct {
    int passed;  /* the number of passed tests */
    int failed;  /* the number of failed tests */
    int errors;  /* the number of errors       */
} tests_summary;

#define RUN_TEST(name, summary)                 \
    do {                                        \
        int ret;                                \
        printf("%s: ", #name);                  \
        fflush(stdout);                         \
        ret = test_##name();                    \
        if (ret == 0) {                         \
            printf("passed\n");                 \
            (summary).passed++;                 \
        } else if (ret == 1) {                  \
            printf("failed\n");                 \
            (summary).failed++;                 \
        } else {                                \
            printf("failed due to an error\n"); \
            (summary).errors++;                 \
        }                                       \
    } while (0)

The tests_summary struct just holds counts for the number of passed and failed tests, and the number of errors that have occurred. The RUN_TEST macro takes a test name and a summary struct, runs the named test, and increments the appropriate field in the summary struct based on the s return value. Along the way, it prints some status information. Using these, one can easily run a suite of related tests and gather the aggregate results for reporting:

void run_test_suite(void)
{
    tests_summary summary = { 0, 0, 0 };

    RUN_TEST(contrived_example, summary);
    RUN_TEST(total_failure, summary);

    if (summary.failed + summary.error > 0) {
        printf("Oh no! Some tests failed!\n");
    }
}

I’ve left macros from the standard library unexpanded, and cleaned up the indentation. ↩︎
Unlike the other macros in this post, RUN_TEST could be replaced with an inline function. The (very slight) advantage of using a macro is that we can get the test function from just the name, instead of having to pass a string and a function pointer separately. One could write a macro that calls the inline function with the appropriate arguments, but I’m not sure that really buys you much… ↩︎

A Makefile template for simple C projects

Sun, 09 Nov 2014 00:00:00 +0000

Large programming projects may require elaborate build systems, but for a simple project consisting of a single executable target and handful of C source files, a single Makefile is often all that is necessary. If you use GNU Make and a C compiler capable of emitting dependency rules (both GCC and Clang can do this, and no doubt others can as well), then a single generic Makefile template can be used for multiple projects by changing only a few variable definitions.¹ Over time I’ve developed such a template, which I present here with the hope that others will find it useful.

At the top of the template are variables with project-specific values. These are typically the only lines that need to be modified when starting a new project. The PROG variable holds the name of the executable target to be built, and SRCS holds the list of source files needed to build it. Header files are not listed here, because they are handled automatically. If an external library is needed, then the CFLAGS and LDFLAGS variables can be modified as well.

PROG := program
SRCS := main.c util.c

CC      := cc
CFLAGS  := -Wall -Wextra -Werror
LDFLAGS :=

In order to build the executable target, all the source files need to be compiled into object files, which are then linked together. The list of object files can be created from the list of source files by using a substitution reference. Keeping the list of object files in a variable makes it easy to write the rule for the executable target, and also the rule for cleaning up generated files. Another substitution reference is used to create a list of “.d” files in the DEPS variable. These files are created by the compiler (with the -MMD flag) alongside each object file, and contain dependency information in the form of Makefile rules. The dependencies include the C source file, along with any header files that it includes. By getting this information directly from the compiler, we’re spared from having to manually list dependencies for each file in the project. This is the key to keeping the Makefile as generic as possible.

OBJS   = $(SRCS:.c=.o)
DEPS   = $(SRCS:.c=.d)

.PHONY: all
all: $(PROG)

$(PROG): $(OBJS)
	$(CC) $(LDFLAGS) -o $@ $^

%.o: %.c
	$(CC) $(CFLAGS) -MMD -c $< -o $@

-include $(DEPS)

The -include $(DEPS) line includes the dependency files that were generated as a side effect of the %.o: %.c rule used to compile the object files. The first time the project is built, there won’t be any dependency files to include, but that’s okay because every source file will have to be compiled anyway. On subsequent runs, the dependency information will be used to determine which object files are out of date. And even better, when the object files are rebuilt, their dependency files will also be updated for the next run.

The final section of the Makefile has targets for cleaning up all the generated files. The clean target removes object and dependency files. The cleaner target depends on clean and also removes the executable file.

.PHONY: clean cleaner
clean:
	rm -f $(OBJS) $(DEPS)

cleaner: clean
	rm -rf $(PROG)

Below is the complete Makefile template, which I have placed in the public domain. Feel free to modify and use it for your own projects.

PROG := program
SRCS := main.c util.c

CC      := cc
CFLAGS  := -Wall -Wextra -Werror
LDFLAGS :=

OBJS   = $(SRCS:.c=.o)
DEPS   = $(SRCS:.c=.d)

.PHONY: all
all: $(PROG)

$(PROG): $(OBJS)
	$(CC) $(LDFLAGS) -o $@ $^

%.o: %.c
	$(CC) $(CFLAGS) -MMD -c $< -o $@

-include $(DEPS)

.PHONY: clean cleaner
clean:
	rm -f $(OBJS) $(DEPS)

cleaner: clean
	rm -rf $(PROG)

If you’re using BSD Make, things are even easier: you just have to define some variables and include bsd.prog.make. The whole Makefile can be just 3 or 4 lines. ↩︎