Skip to content

Have attendees build and run bm before porting it - #95

Merged
memark merged 3 commits into
mainfrom
docs/take-bm-for-a-spin
Nov 10, 2026
Merged

memark merged 3 commits into
mainfrom
docs/take-bm-for-a-spin

Conversation

@memark

@memark memark commented Nov 10, 2026

Copy link
Copy Markdown
Member

Supersedes #84, which GitHub closed after an accidental force-push.

Closes #45.

Most of #45 was already fixed by 93b1454 and 7bd7b35, whose closes #37, #40, #45 only applied the keyword to #37. State on main:

  • Every section in 03_intermediate has an exercise now.
  • Valgrind note for Apple Silicon is in 02_allocators.md.
  • wr check is gone.
  • The 2.2 C harness no longer exists (the exercise became a counting allocator in 947067e).
  • The bm source tree lists internal.h.
  • The signature-only snippets and doSomething are gone.

The one item left was "bm itself is never run", with the fixtures unreferenced. This PR adds a "Take bm for a spin" section at the top of 01_rewrite_a_module.md:

  • cd exercises/_bm && make && ./bm
  • add two bookmarks, then find and list
  • BM_DB=fixtures/sample.bm with find and list
  • BM_DB=fixtures/corrupt.bm ./bm list, which shows the storage error path (bm: fixtures/corrupt.bm:4: duplicate, then cannot open ...: corrupt database, exit 1). This relies on fix(_bm): make corrupt.bm reach the storage error path #86, so main is merged into this branch.
  • A warning that add, del and tag rewrite the database they point at, so they shouldn't be run on the fixtures. I checked: tag on sample.bm modifies the file, while find and list leave the fixtures byte-identical (bm_close only saves when the database is dirty).

It also gitignores exercises/_bm/bookmarks.bm and bookmarks.bm.tmp, which the walkthrough creates. make clean already removes both.

Every command in the section was run verbatim on a copy of exercises/_bm.

Chapter 3 introduces `bm` as the codebase attendees will port, but
nothing asked them to build or run it, and the fixtures under
exercises/_bm/fixtures/ were not referenced anywhere.

Add a short walkthrough at the top of "How to rewrite a module": build
with `make`, add and find a few bookmarks, then point `BM_DB` at
fixtures/sample.bm. Warn against write commands on the fixtures, since
they rewrite the database in place. Ignore the local bookmarks.bm the
walkthrough creates.

Closes #45
Since #86, loading fixtures/corrupt.bm stops at a duplicate URL on line
4 and bm reports a corrupt database. Add it to the walkthrough so
attendees see the storage error path, not only a clean load of
sample.bm, before porting.
@memark
memark merged commit 46bc212 into main Nov 10, 2026
8 checks passed
@memark
memark deleted the docs/take-bm-for-a-spin branch November 10, 2026 12:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Chapter 2: polish items and two missing exercises

1 participant