Jon Staab
79 lines
3.0 KiB
Markdown
79 lines
3.0 KiB
Markdown
This is a monorepo aimed at developers building nostr applications in rust. All crates are prefixed by the namespace `coracle`.
|
|
|
|
It has the following crates:
|
|
|
|
- `coracle-lib` - Struct definitions, stateless utilities related to nostr.
|
|
- `coracle-net` - Networking utilities for working with relays
|
|
- `coracle-signer` - Signer client/server utilities
|
|
- `coracle-domain` - Domain-specific nostr types: profiles, follows, reactions, zaps, etc.
|
|
- `coracle-content` - Text parsing and rendering utilities
|
|
- `coracle-storage` - Storage adapters for different platforms
|
|
|
|
All code is written in a [literate programming](https://en.wikipedia.org/wiki/Literate_programming) style and compiled to both html documentation and rust source code. The goal of this repository is threefold:
|
|
|
|
- To create a complete resource for learning how to work with the nostr protocol for humans
|
|
- To create a production-ready nostr utility library for inclusion in rust, KMP, and web projects.
|
|
- To experiment with using literate programming to serve both as a library and context file for LLMs.
|
|
|
|
## Prerequisites
|
|
|
|
- [Rust](https://rustup.rs/)
|
|
- [just](https://github.com/casey/just)
|
|
- [mdbook](https://rust-lang.github.io/mdBook/) (`cargo install mdbook`)
|
|
|
|
## How it works
|
|
|
|
The source of truth is the `book/` directory, which contains markdown files written in a literate programming style. Code blocks annotated with a file path are extracted ("tangled") into Rust source files by the `coracle-tangle` tool.
|
|
|
|
For example, a code block like this in a markdown file:
|
|
|
|
```text
|
|
```rust {file=coracle-lib/src/event.rs}
|
|
pub struct Event { ... }
|
|
```
|
|
```
|
|
|
|
will be extracted to `coracle-lib/src/event.rs`. Multiple blocks targeting the same file are concatenated in document order, so you can introduce a struct in one section and add methods to it later in the narrative.
|
|
|
|
Code blocks without a `{file=...}` annotation are illustrative only and are not tangled.
|
|
|
|
The `src/` directories of the library crates are generated artifacts and should not be edited directly. Edit the markdown in `book/` instead.
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
# Tangle: extract code from markdown into .rs files
|
|
just tangle
|
|
|
|
# Build: tangle + compile all library crates
|
|
just build
|
|
|
|
# Check: tangle + type-check without full compilation
|
|
just check
|
|
|
|
# Weave: tangle + generate the HTML book (output in target/book/)
|
|
just weave
|
|
|
|
# Clean: remove all generated source and book output
|
|
just clean
|
|
|
|
# All: build + weave
|
|
just all
|
|
```
|
|
|
|
## Project structure
|
|
|
|
```
|
|
book/ # Literate source (the single source of truth)
|
|
book.toml # mdBook configuration
|
|
SUMMARY.md # Table of contents
|
|
01-introduction.md
|
|
02-events.md # etc.
|
|
coracle-tangle/ # The tangle/weave tool (Rust binary)
|
|
coracle-lib/ # Core nostr types and utilities (generated src/)
|
|
coracle-net/ # Relay networking (generated src/)
|
|
coracle-signer/ # Signing abstractions (generated src/)
|
|
coracle-content/ # Content parsing (generated src/)
|
|
coracle-storage/ # Storage adapters (generated src/)
|
|
```
|