Claude Code transcript

Here's a summary of issue #35:

Problem

The README's "Running Programs with the Course Module" section documents commands like:

./occam2go -I kroc/modules/course/libsrc \
           -D TARGET.BITS.PER.WORD=32     \
           -o hello_world.go kroc/modules/course/examples/hello_world.occ

But this fails because hello_world.occ does #INCLUDE "course.module", and there's no course.module file in the example's directory. The file does exist at kroc/modules/course/libsrc/course.module, so -I kroc/modules/course/libsrc should make it findable by the preprocessor.

Let me verify this quickly to see if the include path resolution is actually the issue or if the example file path is wrong.

Both commands work fine. The issue reporter seems to have been trying kroc/modules/course/examples/hello_world.occ — let me check if that specific path also works (it did above). Let me re-read the issue more carefully.

The reporter says they get:

Preprocessor error: line 1: cannot find included file "course.module"

The line 1 is key — examples/course_hello.occ has the #INCLUDE on line 16, and kroc/modules/course/examples/hello_world.occ has it on line 1. So they were trying to transpile hello_world.occ from the KRoC examples. Let me check if the kroc/ directory might not be present for them.

Now I have the full picture. Here's my analysis of issue #35:

The Issue

The reporter ran the README command and got cannot find included file "course.module". The error says line 1, which matches kroc/modules/course/examples/hello_world.occ (has #INCLUDE on line 1), not examples/course_hello.occ (line 16).

What's Actually Happening

The commands do work when the kroc/ directory is present — I just verified both the README example and the KRoC hello_world.occ transpile successfully with -I kroc/modules/course/libsrc.

The most likely cause is that the reporter didn't run ./scripts/clone-kroc.sh first. The kroc/ directory is not checked into the repo (not in .gitignore either, but it's a separate git clone). Without it, there's no course.module file to find.

Possible Fixes

1. Documentation clarity — The README does show ./scripts/clone-kroc.sh as step 1, but the section title "Running Programs with the Course Module" might lead people to skip straight to the transpile command. Making the dependency on the clone step more prominent would help.

2. Better error message — The preprocessor could suggest checking include paths or running the clone script when a .module file isn't found.

3. Add kroc/ to .gitignore — Since it's a cloned external repo, it should probably be in .gitignore for cleanliness (it currently isn't).

Would you like me to work on any of these fixes?

There's a response from @dboreham. They point out that course.module isn't actually in the upstream KRoC repo at that path — you can see it's not listed at https://github.com/concurrency/kroc/tree/master/modules/course/libsrc. They're suggesting the file may be present locally because it was generated at some point.

They're likely right. The gen-module subcommand generates .module files from SConscript files, and there is a SConscript in that directory. Let me verify.

Confirmed — course.module is not tracked in the KRoC git repo. It's an untracked local file that must have been generated previously (likely via gen-module). @dboreham is correct.

The README's instructions are missing a step: after cloning KRoC, you need to run gen-module to create the course.module file. Want me to add a follow-up comment on the issue acknowledging this?

The CLAUDE.md section assumes course.module already exists, which is fine — it's developer-facing context. The README fix is the important one.

That looks good. The fix adds step 3 (gen-module) to the README instructions and renumbers the subsequent steps. This is the missing step the issue reporter identified — course.module isn't in the upstream KRoC repo and needs to be generated from the SConscript before transpiling examples that include it.

Want me to commit this and open a PR?