Skip to content

Commit d43116f

Browse files
io extension: collapse user-type readers to fmt; rewrite guides
Tests/Std/Io.UserTypes.c: - _read_Point2D / _read_Bounds / _read_Region rewritten as StrReadFmt mirrors of their writer's format string. The format pipeline handles literal delimiters and recurses into nested user-type arms through IOFMT_USER_CASE_, so each reader collapses to three lines. -99 lines of hand-rolled cursor walking removed. Docs/content/english/guides/*.md: - Every guide carries the standard AI-authored banner. - Six guides rewritten to tutorial shape after a two-pass review: scope-based-allocator-discipline, generic-containers-and-ownership, planned-fallible-apis-and-allocators, building-and-testing, parsing-kv-config-files, working-with-graphs. Roughly 1,500 lines of design rationale, rejected-alternatives prose, embedded changelogs, and "that is deliberate" asides removed. Internals stay in code comments and in allocator-internals.md. 105-test suite green.
1 parent d6290fb commit d43116f

9 files changed

Lines changed: 240 additions & 1607 deletions
Lines changed: 28 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Building and Testing MisraStdC"
33
date: 2026-04-19
4-
description: "A practical local workflow for cloning, building, testing, and debugging the library."
4+
description: "Clone, build, and run the test suite."
55
authors:
66
- siddharth-mishra
77
tags:
@@ -11,84 +11,52 @@ tags:
1111
- ninja
1212
---
1313

14-
MisraStdC uses a conventional Meson plus Ninja workflow. The build story is intentionally boring, which is the right choice for a C library.
14+
> **Note**: This post was drafted by an AI assistant under direction from the author. It is not first-hand writing; the design choices it describes are real, the prose explaining them is generated. Treat the technical content as the design talking, and the framing as a translation layer.
1515
16-
## Requirements
16+
## What you need
1717

18-
You need:
18+
A C11 compiler (GCC, Clang, or MSVC), Meson, and Ninja.
1919

20-
- a C11 compiler
21-
- Meson
22-
- Ninja
23-
24-
The project is meant to work across GCC, Clang, and modern MSVC.
25-
26-
## Standard Build Flow
27-
28-
The normal local flow is:
20+
## Build
2921

3022
```bash
3123
git clone --recursive https://github.com/brightprogrammer/MisraStdC.git
3224
cd MisraStdC
33-
34-
meson setup builddir
35-
ninja -C builddir
36-
ninja -C builddir test
25+
meson setup build
26+
ninja -C build
27+
ninja -C build test
3728
```
3829

39-
That gets you a clean local build and runs the test suite in the same build directory.
40-
41-
## Development Build With Sanitizers
30+
## Build with sanitizers
4231

43-
When debugging memory or UB problems, use sanitizers early instead of waiting until the code is already tangled.
32+
When chasing a memory or UB bug, turn on ASan + UBSan from the start:
4433

4534
```bash
46-
meson setup builddir -Db_sanitize=address,undefined -Db_lundef=false
47-
ninja -C builddir
48-
ninja -C builddir test
35+
meson setup build -Db_sanitize=address,undefined -Db_lundef=false
36+
ninja -C build
37+
ninja -C build test
4938
```
5039

51-
This is a good default when changing low-level container code, string code, parsing code, or ownership-related paths.
52-
53-
## What To Expect From Tests
54-
55-
The test suite is not only regression coverage. It also acts as documentation.
56-
57-
The generated API docs cross-reference usages found in `Tests/`, which means good tests do double duty:
58-
59-
- they validate behavior
60-
- they provide concrete call-site examples for the published reference pages
40+
This is the default flavor you want while changing container, string, parser, or ownership code.
6141

62-
That matters especially for public generic APIs such as:
42+
## Running a single test
6343

64-
- `IntCompare`
65-
- `IntAdd`, `IntSub`, `IntMul`, `IntDiv`, `IntPow`
66-
- `FloatFrom`, `FloatCompare`, `FloatAdd`, `FloatMul`, `FloatDiv`
44+
`meson test` accepts test names from `Tests/meson.build`:
6745

68-
If a public API has no test usage, its generated documentation tends to look thinner and less trustworthy.
69-
70-
## A Good Workflow For Local Changes
71-
72-
For most changes, the practical loop is:
73-
74-
1. change one focused area
75-
2. run the smallest relevant test targets first
76-
3. run a broader suite if the change touches shared runtime helpers
77-
4. regenerate docs if public comments or exported APIs changed
78-
79-
That last point matters because the docs are partly generated from the source tree, not maintained as a separate manual.
80-
81-
## Documentation Build Flow
46+
```bash
47+
meson test -C build Vec.Insert
48+
meson test -C build -t 4 Io.Write Io.Read # parallel, multiple
49+
```
8250

83-
The documentation site combines two pieces:
51+
Add `--print-errorlogs` to see the failing test's output without re-running it manually.
8452

85-
- generated API pages from `Scripts/DocuGen.py`
86-
- curated prose content under `Docs/content/english`
53+
## Documentation
8754

88-
So when public APIs move, the correct workflow is not just "fix code and push". It is:
55+
The Hugo site under `Docs/` is rebuilt by CI on every push to `master`; you can serve it locally too:
8956

90-
1. update public comments
91-
2. regenerate docs
92-
3. make sure the generated pages still reflect the intended public surface
57+
```bash
58+
cd Docs
59+
hugo server
60+
```
9361

94-
That keeps the published site aligned with the code instead of drifting into a stale wrapper around the headers.
62+
Public-API reference pages are generated from header comments by `Scripts/DocuGen.py`. If you change a public comment, regenerate the docs before pushing so the site reflects what the headers actually say.

0 commit comments

Comments
 (0)