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

Open
#1,002 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.