153 lines
3.2 KiB
Markdown
153 lines
3.2 KiB
Markdown
# c-md
|
|
|
|
A transpiler for literate programming in C (and other compiled languages).
|
|
|
|
Write documentation and code in a single Markdown file. The transpiler extracts
|
|
the code for compilation while keeping your source readable and
|
|
well-documented.
|
|
|
|
## Concept
|
|
|
|
Inspired by Donald Knuth's literate programming, c-md lets you write files like
|
|
`main.c.md` that combine Markdown documentation with code blocks. The
|
|
transpiler extracts the code into pure `.c` files ready for compilation.
|
|
|
|
## File Format
|
|
|
|
Source files use the pattern `<name>.<ext>.md`:
|
|
|
|
```
|
|
main.c.md -> main.c
|
|
utils.h.md -> utils.h
|
|
```
|
|
|
|
### Example: main.c.md
|
|
|
|
```markdown
|
|
# Main Entry Point
|
|
|
|
This file contains the program entry point.
|
|
It initializes the system and starts the main loop.
|
|
|
|
## Dependencies
|
|
|
|
- stdlib.h for memory allocation
|
|
- stdio.h for I/O operations
|
|
|
|
## Implementation
|
|
|
|
'''c
|
|
#include <stdlib.h>
|
|
#include <stdio.h>
|
|
|
|
int main(void)
|
|
{
|
|
printf("Hello, World\n");
|
|
return 0;
|
|
}
|
|
'''
|
|
```
|
|
|
|
(Note: Use standard triple backticks ` ``` ` in actual files)
|
|
|
|
## Usage
|
|
|
|
### Options
|
|
|
|
```
|
|
-h, --help Show help message
|
|
-e, --ext <ext> Extension to extract (c, h, py, etc.)
|
|
-i, --input <file> Input file (default: stdin)
|
|
-o, --output <file> Output file (default: stdout)
|
|
-m, --map <file> Generate line mapping file
|
|
```
|
|
|
|
### Pipe Mode (stdin/stdout)
|
|
|
|
```bash
|
|
# Basic transpilation
|
|
cat main.c.md | c-md -e c > main.c
|
|
|
|
# With line mapping
|
|
cat main.c.md | c-md -e c -m build/maps/main.map > main.c
|
|
```
|
|
|
|
### File Mode
|
|
|
|
```bash
|
|
# Basic transpilation
|
|
c-md -i main.c.md -o build/main.c
|
|
|
|
# With line mapping
|
|
c-md -i main.c.md -o build/main.c -m build/maps/main.map
|
|
|
|
# Extension auto-inferred from filename
|
|
c-md -i main.c.md -o build/main.c
|
|
```
|
|
|
|
### Makefile Integration
|
|
|
|
```makefile
|
|
BUILD_DIR = build
|
|
SRC_DIR = src
|
|
|
|
$(BUILD_DIR)/%.c: $(SRC_DIR)/%.c.md
|
|
c-md -i $< -o $@ -m $(BUILD_DIR)/maps/$*.map
|
|
```
|
|
|
|
## Code Block Filtering
|
|
|
|
The transpiler extracts only code blocks matching the specified extension.
|
|
|
|
For file `main.c.md` with `-e c`:
|
|
- ` ```c ` blocks are extracted
|
|
- ` ```python ` blocks are ignored
|
|
- ` ``` ` blocks (no language) are ignored
|
|
|
|
Multiple matching code blocks are concatenated with a blank line separator.
|
|
|
|
## Building
|
|
|
|
c-md is self-hosted
|
|
([dogfooding](https://en.wikipedia.org/wiki/Self-hosting_(compilers))). The
|
|
source code is written in `.c.md` format and requires c-md itself to build.
|
|
|
|
### First Build (Bootstrap)
|
|
|
|
After cloning or after `make fclean`, run the bootstrap script:
|
|
|
|
```bash
|
|
./bootstrap.sh
|
|
make
|
|
```
|
|
|
|
The bootstrap script builds c-md by traversing major version tags,
|
|
starting from v1.0.0 (plain C sources) up to the current version.
|
|
|
|
### Regular Build
|
|
|
|
Once c-md is available:
|
|
|
|
```bash
|
|
make # build from .c.md sources
|
|
make clean # remove build artifacts
|
|
make fclean # remove everything including binary
|
|
make re # rebuild from scratch
|
|
```
|
|
|
|
## Line Mapping
|
|
|
|
The transpiler generates `.map` files that track the correspondence between
|
|
source lines (`.c.md`) and output lines (`.c`). This enables:
|
|
|
|
- Accurate error reporting back to original files
|
|
- IDE/LSP integration (WIP)
|
|
- Debugging with correct source locations
|
|
|
|
## Status
|
|
|
|
**v2.0.0** - Initial stable release self-hosted.
|
|
|
|
## License
|
|
|
|
[GPL3](LICENSE)
|