From 5ce605da6c3ef2a999f2f214026e02c75edb55ea Mon Sep 17 00:00:00 2001 From: Lyndon Date: Tue, 11 Aug 2026 10:33:27 +0800 Subject: [PATCH 1/4] docs: add developer guide for building and testing CKB contracts --- AGENTS.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b1b4578 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,115 @@ +# CKB C Standard Library — Developer Guide + +This is a C runtime library for on-chain scripts (smart contracts) on CKB. It provides a partial implementation of the standard C runtime. + +Clang is the recommended compiler, version 19 or later. + +It should include a Makefile under project root. specify variable `CC` and `LD`. + +The `ckb-c-stdlib` should be referenced as a git submodule at the location `deps/ckb-c-stdlib` with the URL https://github.com/nervosnetwork/ckb-c-stdlib.git. + +The following compilation options(CFLAGS) should be used: + +--target=riscv64 -march=rv64imc_zba_zbb_zbc_zbs +-O3 +-fdata-sections -ffunction-sections +-fno-builtin-printf -fno-builtin-memcmp +-nostdlib + + +Users can add their own options. It is not necessary to add the `-g` option. Don't use `-fPIE`. + + +The following linker options(LDFLAGS) should be used: + +`-static --gc-sections` + + +When clang is used as the linker driver (the single compilation unit method below), linker-only flags must be passed with a `-Wl,` prefix, e.g. `-Wl,--gc-sections`. A bare `--gc-sections` is rejected by clang with `error: unknown argument`. + +Keep the final binary small; debug information is not needed. Warn users if the final binary size exceeds 400K. + +Every project should have a reproducible build. Use [this script](https://github.com/nervosnetwork/ckb-script-templates/blob/main/workspace/scripts/reproducible_build_docker). Put it here: `script/reproducible_build_docker`. + +The final binary output directory is `./build`. Place source files under `./c` unless users explicitly request other locations. Create the `build` directory if it is missing. + +Add the macro `CKB_PRINTF_DECLARATION_ONLY` when any of the `printf` or `sprintf` family of functions is used. Don't forget to include `ckb_syscalls.h`, since printf use `ckb_debug` syscall. + +To actually enable `printf`/`ckb_printf` (instead of them being compiled as empty stubs that silently return 0), the macro `CKB_C_STDLIB_PRINTF` must also be defined, e.g. `-DCKB_C_STDLIB_PRINTF`. + +The `malloc` and `free` functions are not implemented, so they should not be used. If users provide their own, follow the instructions for using them. + +## Compilation Method +By default, ckb-c-stdlib uses a single big header file strategy, suitable for a single C compilation unit. A minimal `c/main.c` that prints `hello, world`: + +```c +#include "ckb_syscalls.h" +#include + +int main(void) { + printf("hello, world\n"); + return 0; +} +``` + +A complete Makefile: +``` +CC := clang +LD := ld.lld + +CFLAGS := --target=riscv64 -march=rv64imc_zba_zbb_zbc_zbs -O3 \ + -fdata-sections -ffunction-sections \ + -fno-builtin-printf -fno-builtin-memcmp \ + -nostdlib \ + -DCKB_C_STDLIB_PRINTF -DCKB_PRINTF_DECLARATION_ONLY \ + -Ideps/ckb-c-stdlib -Ideps/ckb-c-stdlib/libc +LDFLAGS := -static -Wl,--gc-sections + +CHECKSUM_FILE ?= checksums.txt + +default: build + +build: build/main + +build/main: c/main.c + mkdir -p build + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $< + +checksum: build + shasum -a 256 build/* > $(CHECKSUM_FILE) + +clean: + rm -rf build + +.PHONY: default build checksum clean +``` +Notes: +- The `build`, `checksum` and `clean` targets are required by `./scripts/reproducible_build_docker`, which runs `make build` for verification and `make clean checksum CHECKSUM_FILE=checksums.txt` for `--update`. +- The include paths: `ckb_syscalls.h` lives in `deps/ckb-c-stdlib`, while `stdio.h`/`entry.h` live in `deps/ckb-c-stdlib/libc`. + + +It also supports multiple compilation units with the following settings. When compiling C files, add the macro `CKB_DECLARATION_ONLY`. Compile `libc/src/impl.c` without this macro. Finally, link all objects (including impl.o) together with `ld`: +``` +$(LD) $(LDFLAGS) -o $@ $^ +``` + +## Tests +It should compile the target project successfully on a local machine. Warn users if clang is not +used or the version does not meet the requirement. + +It should be built with a reproducible build when docker is available. Verify as follows: +- Docker check (if available): run the locked build via `./scripts/reproducible_build_docker` and confirm `build/*` matches `checksums.txt`. +- Keep a `checksums.txt` in the repo; regenerate it with `reproducible_build_docker --update` + whenever the binary intentionally changes, and fail the test if it doesn't match. + +If Docker is not available, warn users and skip the reproducible build step. + +Note that the locally installed clang may produce a binary that is not byte-identical to the +locked docker build. This is expected: only the docker build is required to match `checksums.txt`, the +local build only needs to compile successfully. + +## CKB Syscalls +When using CKB syscalls, refer to the following documents for usage instructions: +- https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0009-vm-syscalls/0009-vm-syscalls.md +- https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0034-vm-syscalls-2/0034-vm-syscalls-2.md +- https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md From 8cdd1ac36cf86ebca58174bea4bbc1e17286e1f9 Mon Sep 17 00:00:00 2001 From: Lyndon Date: Tue, 11 Aug 2026 11:45:36 +0800 Subject: [PATCH 2/4] docs: add agent guide for project scaffolding --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b1b4578..0cc188f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,8 @@ # CKB C Standard Library — Developer Guide - This is a C runtime library for on-chain scripts (smart contracts) on CKB. It provides a partial implementation of the standard C runtime. +This guide is for AI agents to scaffold a new project from scratch. It is also helpful when projects are not correctly configured. + Clang is the recommended compiler, version 19 or later. It should include a Makefile under project root. specify variable `CC` and `LD`. From ccdabc312a2451a4214f41b5e93950048c7ec22d Mon Sep 17 00:00:00 2001 From: Lyndon Date: Tue, 11 Aug 2026 13:16:06 +0800 Subject: [PATCH 3/4] docs: move agent guide to scaffold.md and update README link --- README.md | 7 +++++++ AGENTS.md => scaffold.md | 0 2 files changed, 7 insertions(+) rename AGENTS.md => scaffold.md (100%) diff --git a/README.md b/README.md index c8b2e59..d5749ae 100644 --- a/README.md +++ b/README.md @@ -7,3 +7,10 @@ In the development of CKB scripts, we discovered many use-cases and patterns tha * A shimmed libc, notice the libc here is tailored for CKB's special needs, implementing everything in POSIX's standard is never a goal. If you do have special requirements, using a more complete libc is always a better choice Notice while this repo would focus on C code, it is not limited to scripts written in C. A Rust script might use FFI to leverage the C code here, a higher level language can also use certain glues to use the code here. + +## Build with this library +Use an AI agent with the following instructions: +``` +Write a "hello, world" project by following the instructions in: +https://github.com/nervosnetwork/ckb-c-stdlib/blob/master/scaffold.md +``` diff --git a/AGENTS.md b/scaffold.md similarity index 100% rename from AGENTS.md rename to scaffold.md From 7aa36efbeafc12f4287affad72e61832681dcbac Mon Sep 17 00:00:00 2001 From: Lyndon Date: Wed, 12 Aug 2026 09:10:16 +0800 Subject: [PATCH 4/4] chore: rename --- README.md | 2 +- scaffold.md => guide.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename scaffold.md => guide.md (100%) diff --git a/README.md b/README.md index d5749ae..cc8fbb7 100644 --- a/README.md +++ b/README.md @@ -12,5 +12,5 @@ Notice while this repo would focus on C code, it is not limited to scripts writt Use an AI agent with the following instructions: ``` Write a "hello, world" project by following the instructions in: -https://github.com/nervosnetwork/ckb-c-stdlib/blob/master/scaffold.md +https://github.com/nervosnetwork/ckb-c-stdlib/blob/master/guide.md ``` diff --git a/scaffold.md b/guide.md similarity index 100% rename from scaffold.md rename to guide.md