boxlite-ai / boxlite-ai/boxlite
C SDK: example_common.h no longer compiles against the post-and-drain callback API; boxlite_options_add_port/add_volume have no coverage
- Dominant language
- Rust
- Stars
- 2.3k
- Forks
- 179
- Avg merge
- 23h 25m
- Merged PRs (30d)
- 121
Description
**Labels:** `bug`, `documentation` (examples are docs)
**Body:**
## Summary
Two related problems in the C SDK surface:
1. **`examples/c/example_common.h` (and therefore every example that includes it) does not compile against the current `boxlite.h`.** The C SDK moved box creation / exec / lifecycle to a post-and-drain **callback** API, but `example_common.h` was never updated — it still calls the old direct out-param signatures.
2. **`boxlite_options_add_port` and `boxlite_options_add_volume` have no example or test coverage** despite `add_port` having a recent breaking signature change (host-first args, `uint16_t`, `BoxlitePortProtocol` enum, nullable `host_ip`, returns `BoxliteErrorCode`).
## Repro (1) — examples don't compile
```bash
git clone https://github.com/boxlite-ai/boxlite && cd boxlite
gcc -fsyntax-only -I examples/c -I sdks/c/include examples/c/01_lifecycle.c
```
```
example_common.h:46:27: error: too few arguments to function 'boxlite_create_box'
BoxliteErrorCode code = boxlite_create_box(runtime, opts, &box, &error);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
boxlite.h: note: expected 'CBoxCreateBoxCb' but argument is of type 'CBoxHandle **'
example_common.h:71:7: error: implicit declaration of function 'boxlite_execute'
boxlite_execute(box, &cmd, callback, user_data, &execution, error);
```
Root cause: `boxlite_create_box` now takes `(runtime, opts, CBoxCreateBoxCb cb, void* user_data, err)`, exec is now `boxlite_box_exec(...)`, and the result/exit code are delivered via callbacks. The old `boxlite_execute` no longer exists.
## Repro (2) — zero coverage of the port/volume option API
```bash
grep -rn "boxlite_options_add_port\|boxlite_options_add_volume" examples/c sdks/c/tests
# (no output)
```
## Proposal
1. Port `example_common.h` to the callback API (`boxlite_create_box` + `boxlite_box_exec`/`on_stdout`/`on_stderr`/`execution_wait`), preserving the existing `create_alpine_box_or_exit` / `execute_and_wait` helper signatures so current examples keep working.
2. Add `examples/c/06_port_forwarding.c` — exercises `boxlite_options_add_port` + `boxlite_options_add_volume` end-to-end.
3. Add `sdks/c/tests/test_options_port.c` — VM-free FFI test (CTest label `ffi`) pinning the documented `Ok` / `InvalidArgument` contract of `boxlite_options_add_port`.
4. Fix the wrong clone URL in `sdks/c/README.md`.
PR incoming. (A separate issue tracks the remaining examples that call lifecycle functions directly — they need the same callback migration.)
Contributor guide
Research direction
Start by running the gcc syntax check for examples/c/01_lifecycle.c and read examples/c/example_common.h alongside sdks/c/include/boxlite.h. Trace the callback entry points named in the issue while preserving the existing helper signatures, then add the proposed port-forwarding example and sdks/c/tests/test_options_port.c. Done means the examples compile, port and volume APIs have coverage, and the clone URL in sdks/c/README.md is corrected.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c
- Domain
- api, documentation, testing
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100