rustycan has a CAN adapter layer that works: a Rust
trait, half a dozen USB and network backends behind it, two desktop tools using
it every day. Then a client asked whether their test tool could drive the same
hardware through it. Their tool is written in Python, and its world is
python-can: can.Bus(...), Notifier,
Logger, a body of scripts that already exist. Porting the backends to Python
was out; so was handing over the proprietary adapter source. What we agreed on
together was the third option: lend the compiled Rust code to their Python
across a C boundary, packaged as a python-can plugin they could pip install.
Doing that properly turned out to be mostly about threads, wheel tags, and one
linker bug.
What you'll learn
- Why a plain C ABI (
cdylib+ctypes) beat a PyO3 extension module for this job — and what that choice costs - How to carry a trait object (
Box<dyn CanAdapter>) that is&mut selfand notSyncacross an FFI boundary without lying about thread safety - Designing a small, versioned ABI: status codes, a 24-byte
#[repr(C)]frame, and where error detail lives when there is no handle to attach it to - How a python-can interface plugin is registered, and what
BusABCexpects of_recv_internalandsend - Why a
ctypespackage ships as apy3-none-<platform>wheel, and how to make setuptools produce one - The macOS 27
dlopenfailure caused by Cargo's default release strip — root cause, fix, and the CI check that keeps it fixed - A release pipeline that proves each wheel works after installation, before it is signed and published
The shape of the problem
The Rust side is a private crate, k-can-adapter, that was carved out of
rustycan so that a second tool (the CANopen bootloader flasher
rustybbd) could share it. Its surface is small:
pub trait CanAdapter {
fn recv(&mut self, timeout: Duration) -> Result<ReceivedFrame, AdapterError>;
fn send(&mut self, frame: &CanFrame) -> Result<(), AdapterError>;
fn name(&self) -> &str;
// optional: firmware_version, serial, echoes_tx …
}
pub fn open_adapter(kind: &AdapterKind, baud: u32, listen_only: bool)
-> Result<Box<dyn CanAdapter>, AdapterError>;
Three properties of that API shaped everything downstream:
&mut selfeverywhere. An adapter is a single-owner object; there is no interior locking, by design.- Not all backends are
Sync. Several wrap vendor handles or USB interfaces that are only valid on one thread. open_adaptermust run on the thread that will use the adapter. Some backends bind to the calling thread at open time.
ℹ️ What this means — if Rust's ownership rules are new:
&mut selfon a method means the caller needs exclusive access to the object for the duration of the call — the compiler guarantees nobody else can even read it meanwhile. That is what makes "no interior locking" safe: there can only be one caller.Syncis a marker the compiler attaches to types that are safe to reference from several threads at once; a type that wraps a vendor handle valid on one thread only is deliberately notSync, and the compiler will refuse to compile code that shares it across threads. These are not conventions a careful programmer follows — they are rules the build enforces, and the FFI layer has to respect them just as any Rust caller would.
The adapters are selected by Cargo feature, one per backend. For the Python
export only two are compiled in — the ones a third party can actually buy and
plug in: Summit (a USB-CAN adapter that relies on the vendor's own driver
library) and Apex (a USB-CAN adapter driven entirely in userspace via
nusb). The proprietary dongle backends and
SocketCAN are deliberately left out of this build.
# k-can-ffi/Cargo.toml
[lib]
name = "kadapter"
crate-type = ["cdylib"]
[dependencies]
k-can-adapter = { git = "…/k-can-adapter.git", tag = "v0.1.0", default-features = false, features = [
"apex",
"summit",
] }
The result is a chain of four repositories with one hard visibility boundary in the middle:
%%{init: {'theme': 'base', 'themeVariables': {
'primaryColor': '#edb059',
'primaryTextColor': '#222222',
'primaryBorderColor': '#c8951f',
'lineColor': '#5a5450',
'secondaryColor': '#ede9e4',
'secondaryTextColor': '#2d2a26',
'tertiaryColor': '#222222',
'tertiaryTextColor': '#edb059',
'background': '#faf8f5',
'mainBkg': '#faf8f5',
'noteBkgColor': '#f2c880',
'noteTextColor': '#222222',
'clusterBkg': '#faf8f5',
'clusterBorder': '#ede9e4',
'titleColor': '#2d2a26'
}}}%%
flowchart LR
subgraph PRIV["private — source never leaves"]
ADP["k-can-adapter\nCanAdapter trait\n+ all backends"]:::priv
FFI["k-can-ffi\ncdylib · C ABI\napex + summit only"]:::priv
end
subgraph PUB["public"]
PLG["python-can-kadapter\nctypes plugin\ncan.Bus(interface='kadapter')"]:::accent
DIST["python-can-kadapter-dist\nwheels + .minisig"]:::pub
end
ADP -->|git tag| FFI
FFI -->|"libkadapter\nbundled at wheel build"| PLG
PLG -->|"py3-none-<plat>\nwheels"| DIST
classDef accent fill:#edb059,color:#222222,stroke:#c8951f
classDef priv fill:#5a5450,color:#faf8f5,stroke:#5a5450
classDef pub fill:#ede9e4,color:#2d2a26,stroke:#c8951f
Four repositories, one boundary. Everything left of the line is private Rust;
the plugin on the right is public, pure Python, and contains no adapter code —
it receives the compiled libkadapter only when a wheel is built.
Why a C ABI and not PyO3
ℹ️ What this means — the vocabulary, if it's new: FFI (foreign function interface) is just "calling code written in one language from another". For that to work both sides must agree on an ABI (application binary interface): how arguments are passed in registers or on the stack, how a struct is laid out in memory, how a function is named in the binary. Nearly every language can speak the C ABI, which is why C is the common currency between them. The compiled Rust code is delivered as a shared library —
libkadapter.dylibon macOS,.soon Linux,.dllon Windows — a file of machine code the operating system can load into an already-running process on request (dlopenon Unix,LoadLibraryon Windows). Python's standard-library modulectypesdoes exactly that load, and then lets you call the library's C functions by name, converting Pythonints andbytesto C types as it goes. No compiler is involved on the Python side at all.
The reflex answer for "Rust in Python" is PyO3 plus
maturin: write #[pyclass], get a native extension
module. It is excellent, and it was the wrong tool here, for three reasons.
The wheel matrix. A CPython extension module links against the interpreter
ABI, so you ship one wheel per Python version per platform — cp39, cp310,
… × macOS/Windows/Linux. The stable ABI (abi3) narrows that, but the
client's machines run whatever Python their distribution ships, and the
plugin had to drop into an existing tool rather than dictate its interpreter.
A ctypes library has no interpreter dependency at all: one wheel per
platform serves every Python 3.
ℹ️ What this means — wheels and their tags: a wheel is the file
pip installactually downloads: a zip of ready-to-copy files with a.whlextension. Its name carries three compatibility tags —python_can_kadapter-0.1.1-py3-none-macosx_11_0_arm64.whlreads as any Python 3 · no interpreter ABI · macOS 11+ on Apple silicon. A compiled extension module instead getscp313-cp313-macosx_11_0_arm64: CPython 3.13 only, because the module links against that interpreter's internal structures and will crash or refuse to import under 3.12. Support Python 3.9 through 3.13 on three operating systems and you are building and testing 5 × 3 = 15 wheels per release — that is the matrix. Actypespackage never touches interpreter internals, so the first tag collapses topy3and the matrix collapses to 3 wheels: one per platform.
The consumer isn't only Python. A C header is a universal currency. The
same libkadapter can be loaded from a LabVIEW harness, a C# test rig, or a
Lua script tomorrow, with no Rust toolchain on the consumer's machine.
The boundary is also an IP boundary. The client needed a dependable binary, not the adapter source; we needed to keep the source private. A shared library with two backends compiled in and a one-page header as the contract satisfies both — neither side has to trust the other's build environment, only the ABI.
ℹ️ What this means — on the Rust side:
crate-type = ["cdylib"]tells Cargo to produce that C-compatible shared library instead of a Rust-onlyrlib. Functions marked#[no_mangle] pub extern "C"are exported under their plain names with the platform's C calling convention (normally Rust "mangles" names into unique hashes and uses its own, unstable convention).#[repr(C)]on a struct gives it the layout a C compiler would choose, so the other side can read it field by field. Rust-specific types —String,Vec, trait objects,Result— have no C equivalent and never cross the boundary; only pointers, integers, andrepr(C)structs do.
The cost is real: you write the type marshalling by hand on both sides, and
nothing checks that _ffi.py and kadapter.h agree except your tests. The
next two sections are about keeping that surface small enough that the tests
can actually cover it.
Designing the ABI: eight functions and a 24-byte frame
The whole public surface fits in one screen of kadapter.h (comments
trimmed):
typedef struct Bus Bus; /* opaque */
typedef enum {
KADAPTER_OK = 0,
KADAPTER_TIMEOUT = 1, /* clean receive timeout — not an error */
KADAPTER_NOT_FOUND = 2,
KADAPTER_IO = 3,
KADAPTER_TX_FULL = 4, /* transmit queue momentarily full; retry */
KADAPTER_PROTOCOL = 5,
KADAPTER_FATAL = 6,
KADAPTER_DISCONNECTED = 7,
KADAPTER_IN_USE = 8,
KADAPTER_BAD_ARG = 9
} kadapter_status;
typedef struct {
uint32_t id;
uint8_t len; /* 0..8 */
uint8_t flags; /* EXTENDED = 1, REMOTE = 2 */
uint8_t channel;
uint8_t is_tx_echo;
uint64_t timestamp_ns; /* host wall-clock, ns since Unix epoch */
uint8_t data[8];
} kadapter_frame;
uint32_t kadapter_abi_version(void);
kadapter_status kadapter_open(const char *channel, uint32_t bitrate,
int listen_only, Bus **out);
void kadapter_close(Bus *bus);
kadapter_status kadapter_send(Bus *bus, const kadapter_frame *frame);
kadapter_status kadapter_recv(Bus *bus, kadapter_frame *out, uint32_t timeout_ms);
const char *kadapter_name(Bus *bus);
const char *kadapter_last_error(Bus *bus); /* NULL → last failed open */
size_t kadapter_list_devices(char *buf, size_t cap);
A few decisions in there are worth defending.
Status codes mirror the Rust error enum one-to-one — NotFound, Io,
TxQueueFull, Protocol, Fatal, Disconnected, InUse — plus three that
only exist at the boundary: OK, BAD_ARG (you passed a null or a nonsense
channel string) and TIMEOUT. Timeout is a status, not an error, because
python-can's receive loop asks "anything in the last 100 ms?" constantly and a
clean "no" must be cheap and unexceptional.
The frame is exactly 24 bytes with no padding. u32 + 4 × u8 = 8 bytes,
then a naturally aligned u64, then [u8; 8]. Both sides assert this: Rust
with #[repr(C)], Python with a one-line test —
assert ctypes.sizeof(KadapterFrame) == 24. If anyone ever adds a field on one
side only, the test suite says so before any frame does.
An ABI version function, checked at load time. kadapter_abi_version()
returns 1; the Python binding compares it against EXPECTED_ABI_VERSION the
first time it loads the library and refuses to continue on mismatch. Cheap
insurance against a stale .dylib next to a new .py.
last_error(NULL) — detail for a failure that has no handle. The first
version returned only a status from kadapter_open. On Linux that produced
IO for an Apex that was present and enumerable but blocked by a missing udev
rule — three letters that hid a permission problem. The fix is a thread-local
slot in the library that stores the detail of the last failed open on the
calling thread:
thread_local! {
static OPEN_ERROR: RefCell<CString> = RefCell::new(CString::default());
}
#[no_mangle]
pub unsafe extern "C" fn kadapter_last_error(bus: *mut Bus) -> *const c_char {
if bus.is_null() {
return OPEN_ERROR.with(|slot| slot.borrow().as_ptr());
}
match (*bus).last_error.lock() {
Ok(slot) => slot.as_ptr(),
Err(_) => std::ptr::null(),
}
}
Once a Bus exists, its own Mutex<CString> holds the last detail for that
bus. Either way the string is owned by the library and valid until the next
call — the caller copies it immediately and never frees it. python-can now
reports NOT_FOUND no Apex device matched serial … or
IO … Permission denied with the actual cause attached.
Channel strings are URLs. apex:// opens the first Apex, apex://<serial>
pins one; summit:// opens the first Summit bus, summit://2 the second. An
unknown scheme is BAD_ARG with a message listing the accepted forms — the
plugin never has to know what the native layer supports.
Threading: one worker per bus
Here is where the three properties from the first section bite. python-can's
idiom is two threads per bus: your script calls bus.send() from the main
thread while a Notifier thread sits in bus.recv(). But the adapter behind
the bus is &mut self, may not be Sync, and had to be opened on the thread
that uses it.
Pretending otherwise — wrapping the adapter in a Mutex and calling recv
from whatever thread arrives — would compile. It would also serialise send
behind a blocking receive and violate the "same thread" rule for the backends
that have one. The honest solution is to give every Bus its own worker
thread that owns the adapter outright and to talk to it over channels:
pub struct Bus {
tx: Sender<TxCmd>, // → worker
rx: Receiver<Result<KadapterFrame, AdapterError>>, // ← worker
worker: Option<JoinHandle<()>>,
name: CString,
last_error: Mutex<CString>,
}
enum TxCmd {
Send(CanFrame, SyncSender<Result<(), AdapterError>>),
Shutdown,
}
fn worker_loop(
mut adapter: Box<dyn CanAdapter>,
tx_rx: Receiver<TxCmd>,
rx_tx: Sender<Result<KadapterFrame, AdapterError>>,
) {
const POLL: Duration = Duration::from_millis(2);
loop {
// Drain every pending transmit first so send latency stays low.
loop {
match tx_rx.try_recv() {
Ok(TxCmd::Send(frame, resp)) => { let _ = resp.send(adapter.send(&frame)); }
Ok(TxCmd::Shutdown) | Err(TryRecvError::Disconnected) => return,
Err(TryRecvError::Empty) => break,
}
}
match adapter.recv(POLL) {
Ok(rf) => { if rx_tx.send(Ok(to_ffi_frame(&rf))).is_err() { return; } }
Err(AdapterError::Timeout) => {}
Err(e) => {
let terminal = matches!(e, AdapterError::Disconnected | AdapterError::Fatal(_));
let _ = rx_tx.send(Err(e));
if terminal { return; }
}
}
}
}
The worker alternates between draining the transmit queue and a 2 ms blocking
receive on the hardware. Each Send carries its own rendezvous channel, so
kadapter_send blocks the caller until the adapter has actually accepted the
frame and returns the adapter's real result — including TX_FULL, which
python-can surfaces as an exception the script can retry on.
Open is a handshake, because the adapter must be created on the worker:
let (ready_tx, ready_rx) = sync_channel::<Result<String, AdapterError>>(0);
let worker = thread::spawn(move || {
let adapter = match open_adapter(&kind, bitrate, listen_only) {
Ok(a) => { let _ = ready_tx.send(Ok(a.name().to_string())); a }
Err(e) => { let _ = ready_tx.send(Err(e)); return; }
};
worker_loop(adapter, tx_rx, rx_tx);
});
match ready_rx.recv() {
Ok(Ok(name)) => { /* box the Bus, hand the raw pointer to the caller */ }
Ok(Err(e)) => { let _ = worker.join(); set_open_error(&e.to_string()); status_of(&e) }
Err(_) => { set_open_error("adapter worker thread died during open"); KadapterStatus::Fatal }
}
kadapter_open doesn't return until the worker reports success or failure,
so the caller gets a synchronous answer and a fully initialised handle — or a
status plus the thread-local error detail. kadapter_close sends Shutdown
and joins the thread; nothing is left running after the Python object is
garbage-collected.
%%{init: {'theme': 'base', 'themeVariables': {
'primaryColor': '#edb059',
'primaryTextColor': '#222222',
'primaryBorderColor': '#c8951f',
'lineColor': '#5a5450',
'secondaryColor': '#ede9e4',
'secondaryTextColor': '#2d2a26',
'tertiaryColor': '#222222',
'tertiaryTextColor': '#edb059',
'background': '#faf8f5',
'mainBkg': '#faf8f5',
'noteBkgColor': '#f2c880',
'noteTextColor': '#222222',
'clusterBkg': '#faf8f5',
'clusterBorder': '#ede9e4',
'titleColor': '#2d2a26'
}}}%%
sequenceDiagram
participant M as Python main thread
participant N as python-can Notifier thread
participant F as libkadapter (C ABI)
participant W as Bus worker thread
participant A as CanAdapter (boxed trait object)
M->>F: kadapter_open("apex://", 500000, 0, &bus)
F->>W: spawn
W->>A: open_adapter(kind, …)
A-->>W: Ok(adapter)
W-->>F: ready(name)
F-->>M: OK, bus*
par send from main
M->>F: kadapter_send(bus, &frame)
F->>W: TxCmd::Send(frame, resp)
W->>A: adapter.send(&frame)
A-->>W: Ok
W-->>F: resp: Ok
F-->>M: OK
and receive from Notifier
N->>F: kadapter_recv(bus, &out, 100)
W->>A: adapter.recv(2 ms)
A-->>W: frame
W-->>F: rx channel
F-->>N: OK, out filled
end
M->>F: kadapter_close(bus)
F->>W: TxCmd::Shutdown
W-->>F: join
Two Python threads, one Rust worker. The adapter is touched by exactly one
thread for its entire life — the one that opened it — while send and recv
are safe to call concurrently from either side because they only touch channel
endpoints.
ℹ️ What this means — for Python developers reading the Rust:
SenderandReceiverare Rust's standard multi-producer, single-consumer queues; async_channel(0)is a zero-capacity rendezvous where the sender blocks until the receiver takes the value.Box<dyn CanAdapter>is a heap-allocated object whose concrete type is decided at runtime — the equivalent of holding an interface reference. Moving it into the spawned closure (move ||) transfers ownership to the worker thread; after that line no other thread can even name it, which is how the compiler enforces the "one thread" rule.
The Python side: a BusABC over ctypes
The plugin is about 300 lines of pure Python in two files. _ffi.py mirrors
the header:
class KadapterFrame(Structure):
"""Mirrors the 24-byte ``kadapter_frame`` C struct."""
_fields_ = [
("id", c_uint32),
("len", c_uint8),
("flags", c_uint8),
("channel", c_uint8),
("is_tx_echo", c_uint8),
("timestamp_ns", c_uint64),
("data", c_uint8 * 8),
]
def _bind(lib: ctypes.CDLL) -> ctypes.CDLL:
lib.kadapter_open.restype = c_int
lib.kadapter_open.argtypes = [c_char_p, c_uint32, c_int, POINTER(c_void_p)]
lib.kadapter_recv.restype = c_int
lib.kadapter_recv.argtypes = [c_void_p, POINTER(KadapterFrame), c_uint32]
# … the other six
return lib
Setting argtypes/restype on every function is not optional hygiene — it is
what makes ctypes convert a Python int to uint32_t instead of the
platform int, and a bytes to const char *. Skip it and a 29-bit CAN ID
will silently truncate on some platforms and not others.
bus.py subclasses can.BusABC and implements the two methods python-can
requires:
class KadapterBus(can.BusABC):
def __init__(self, channel: str, bitrate: int = 500000,
listen_only: bool = False, **kwargs):
self._lib = _ffi.lib() # loads once, checks ABI version
self._handle = c_void_p()
status = self._lib.kadapter_open(channel.encode(), int(bitrate),
1 if listen_only else 0, byref(self._handle))
if status != _ffi.OK:
detail = self._lib.kadapter_last_error(None) or b""
raise can.CanInitializationError(
f"Failed to open kadapter channel {channel!r}: "
f"{_status_name(status)} {detail.decode()}".rstrip())
super().__init__(channel, **kwargs)
def _recv_internal(self, timeout):
frame = KadapterFrame()
timeout_ms = 0xFFFFFFFF if timeout is None else max(0, int(timeout * 1000))
status = self._lib.kadapter_recv(self._handle, byref(frame), timeout_ms)
if status == _ffi.TIMEOUT:
return None, False
if status != _ffi.OK:
raise can.CanOperationError(f"recv failed: {_status_name(status)} {self._last_error()}")
return can.Message(
timestamp=frame.timestamp_ns / 1e9,
arbitration_id=frame.id,
is_extended_id=bool(frame.flags & _ffi.FLAG_EXTENDED),
is_remote_frame=bool(frame.flags & _ffi.FLAG_REMOTE),
dlc=frame.len,
data=bytes(frame.data[: min(frame.len, 8)]),
), False
_recv_internal returns a (message_or_None, already_filtered) tuple;
returning (None, False) on TIMEOUT is exactly the quiet "nothing yet" that
python-can's Notifier loop expects. The second element tells python-can that
the native layer applied no filters, so it should apply any the user set.
One line in pyproject.toml makes it discoverable:
[project.entry-points."can.interface"]
kadapter = "can_kadapter.bus:KadapterBus"
ℹ️ What this means — if you haven't written a python-can backend: python-can resolves
can.Bus(interface="kadapter", …)by looking up thecan.interfaceentry-point group in installed package metadata. Any package that registers a name there becomes a first-class backend — the user's scripts,can.Logger,can viewerand the rest work unchanged. No fork of python-can, no monkey-patching.
From the client's side the whole thing is now:
import can
with can.Bus(interface="kadapter", channel="apex://", bitrate=500000) as bus:
bus.send(can.Message(arbitration_id=0x123, data=b"\x01\x02"))
print(bus.recv(timeout=1.0))Packaging: a py3-none-<platform> wheel
The package has no C extension, so setuptools wants to tag it
py3-none-any — pure Python, runs anywhere. That is false: it bundles a
.dylib, .so or .dll under can_kadapter/lib/, so it is per-platform.
The other default, had we used a compiled extension, would be
cp313-cp313-macosx_11_0_arm64 — per-interpreter, which is needlessly
restrictive for a ctypes package. The correct tag is the one in the middle,
and setuptools has no switch for it. setup.py exists for that single
override:
class bdist_wheel(_bdist_wheel):
def finalize_options(self):
super().finalize_options()
self.root_is_pure = False # "this wheel is platform-specific"
def get_tag(self):
_python, _abi, plat = super().get_tag()
return "py3", "none", plat # …but not interpreter-specific
setup(cmdclass={"bdist_wheel": bdist_wheel})
Everything else — name, version, dependencies, the entry point — lives in
pyproject.toml.
Two more packaging details earned their keep:
- The native library is not committed to the plugin repo.
lib/contains a.gitkeep. The release pipeline clonesk-can-ffiat the tag pinned under[tool.kadapter] ffi-taginpyproject.toml, builds it, and copies the result in just beforepip wheel. A public repo never carries the private binary in its history; the pin makes every wheel reproducible from two tags. - On macOS the platform tag comes from the compiler, not the runner. A
wheel built with the system Python would be tagged for whatever macOS that
Python was built against. The Rust toolchain links with
-mmacosx-version-min=11.0, so the build sets_PYTHON_HOST_PLATFORM=macosx-11.0-arm64and the wheel is honestly taggedpy3-none-macosx_11_0_arm64.
⚠️ Gotcha:
pip wheelruns in whatever directory you invoke it from, and so doespytest. Running the tests from the source tree afterpip install dist/*.whlquietly imports the source package, not the installed wheel — and the source tree has an emptylib/. The release pipeline runspytestfrom/tmpfor exactly this reason.
The dylib that built but would not load
Everything above was done and green on Linux and Windows in a day. On macOS
the library built, the tests imported it… and ctypes.CDLL failed with:
OSError: dlopen(libkadapter.dylib, 0x0006): tried: '…/libkadapter.dylib'
(mis-aligned LINKEDIT string pool)
That is dyld on macOS 27 refusing to map a Mach-O whose LC_SYMTAB.stroff —
the offset of the string table in the __LINKEDIT segment — is not 8-byte
aligned. Older dyld didn't check; the new one does.
ℹ️ What this means — if you've never looked inside a binary: Mach-O is macOS's executable file format (Linux has ELF, Windows has PE). dyld is the dynamic loader — the part of the OS that opens such a file, maps it into memory and resolves its symbols; it is what runs behind
dlopen. A Mach-O is a list of load commands describing where things live;LC_SYMTABis the one that says where the symbol table and its string table (the pool of function names, likekadapter_open) sit inside the__LINKEDITsegment. Stripping a binary removes symbols that are not needed at runtime to make it smaller — and because that means rewriting__LINKEDIT, the stripping tool must recompute those offsets. The whole bug is that one tool recomputed them with the wrong padding, and the newer loader is strict enough to notice.
The usual suspects were all innocent. Switching linkers (-ld_classic),
re-codesigning, changing the deployment target, running strip -x after the
fact — none changed stroff. The actual cause is two defaults meeting:
- Cargo's release profile defaults to
strip = "debuginfo". - To do that, rustc invokes its own bundled
llvm-objcopy, not Apple'sstrip.
That llvm-objcopy rewrites __LINKEDIT and pads the string pool to 4 bytes,
not 8. When the number of indirect symbols is odd, the result is a stroff
that is 4-aligned but not 8-aligned — and a dylib that loads fine on macOS 26
and not at all on 27. The bug is
llvm/llvm-project#203678,
fixed upstream in
llvm/llvm-project#203680,
and not yet in the LLVM that ships with rustc 1.97
(rust-lang/rust#157750).
The fix is to take stripping away from rustc and give it back to Apple:
# k-can-ffi/Cargo.toml
[profile.release]
strip = "none" # rustc's llvm-objcopy mis-aligns __LINKEDIT; strip afterwardscargo build --release
/usr/bin/strip -x target/release/libkadapter.dylib # Apple's strip pads to 8
Same size reduction (993 KB → 706 KB), and it loads. Then make it impossible to
regress silently — the CI job on the macOS runner checks the alignment and
then actually dlopens the artifact from Python:
STROFF=$(otool -l "$LIB" | awk '/stroff/{print $2}')
[ $((STROFF % 8)) -eq 0 ] || { echo "misaligned LINKEDIT string pool"; exit 1; }
/usr/bin/python3 -c "import ctypes; print(ctypes.CDLL('$LIB').kadapter_abi_version())"
A build that "succeeds" and cannot be loaded is worse than a failed build; the load test is the check that matters.
⚠️ Gotcha: this applies to every Rust
cdylibyou ship for macOS, not just this one. Executables launched by the kernel are unaffected — which is why rustycan and rustybbd, built from the very same adapter crate, never showed it.
A second, smaller dyld lesson arrived with Summit. That backend dlopens the
vendor's driver library by bare file name, and dyld resolves bare names only
through the host executable's rpaths and /usr/lib. When the host
executable is a desktop app with its own rpaths, that works. When the host is
python3, it doesn't — the vendor library sits in /usr/local/lib and nobody
is looking there. The fix lives in build.rs: give the cdylib its own
LC_RPATH so the lookup succeeds regardless of who loaded it.
// k-can-ffi/build.rs
if std::env::var("CARGO_CFG_TARGET_OS").as_deref() == Ok("macos") {
println!("cargo:rustc-cdylib-link-arg=-Wl,-rpath,/usr/local/lib");
}
CI greps otool -l for that LC_RPATH too.
Releasing: prove the wheel, then sign it
The release workflow runs on the organisation's own Forgejo runners and is
triggered by pushing a tag v<version> that matches pyproject.toml. A tag
with a suffix — v0.1.0-rc1 — runs the entire pipeline as a dry run and skips
only the final publish, which is how the first run was debugged without
polluting the public release page.
%%{init: {'theme': 'base', 'themeVariables': {
'primaryColor': '#edb059',
'primaryTextColor': '#222222',
'primaryBorderColor': '#c8951f',
'lineColor': '#5a5450',
'secondaryColor': '#ede9e4',
'secondaryTextColor': '#2d2a26',
'tertiaryColor': '#222222',
'tertiaryTextColor': '#edb059',
'background': '#faf8f5',
'mainBkg': '#faf8f5',
'noteBkgColor': '#f2c880',
'noteTextColor': '#222222',
'clusterBkg': '#faf8f5',
'clusterBorder': '#ede9e4',
'titleColor': '#2d2a26'
}}}%%
flowchart TB
TAG["push tag vX.Y.Z"]:::accent --> CR["create-release\ntag ≟ pyproject version\nread [tool.kadapter] ffi-tag"]
CR --> MAC["macos-arm64\nbuild k-can-ffi @ ffi-tag\nApple strip · ad-hoc codesign\nstroff % 8 == 0"]
CR --> WIN["win11\nbuild k-can-ffi @ ffi-tag\nLoadLibrary + 8 symbols"]
CR --> LIN["linux x86_64 (container)\nbuild k-can-ffi @ ffi-tag\nstrip --strip-unneeded"]
MAC --> V1["bundle → pip wheel\ninstall into clean venv\npytest KADAPTER_REQUIRE_NATIVE=1"]
WIN --> V2["bundle → pip wheel\ninstall into clean venv\npytest KADAPTER_REQUIRE_NATIVE=1"]
LIN --> V3["bundle → pip wheel\ninstall into clean venv\npytest KADAPTER_REQUIRE_NATIVE=1"]
V1 & V2 & V3 --> SP["sign-publish\nminisign each wheel\nupload .minisig"]
SP -->|"final tag only"| DIST["python-can-kadapter-dist\npublic release"]:::accent
SP -.->|"-rc tag: stop here"| DRY["dry run complete"]:::muted
classDef accent fill:#edb059,color:#222222,stroke:#c8951f
classDef muted fill:#ede9e4,color:#5a5450,stroke:#ede9e4
Three platform jobs build the native library from a pinned tag, bundle it, build a wheel, and then install that wheel into a clean virtualenv and run the tests against it — before anything is signed. Prerelease tags exercise every step except the public publish.
The step that pays for itself is verify-after-install. Each job creates a
fresh venv, pip installs the wheel it just built plus pytest, changes to a
neutral directory and runs the suite with KADAPTER_REQUIRE_NATIVE=1. That
variable flips the native tests from "skip if no library" to "fail if no
library" — so a wheel whose bundled binary is missing, misnamed, unloadable, or
reports the wrong ABI version fails its own release job, not a user's
pip install. The macOS job would have caught the stroff bug on day one had
it existed then.
Three decisions were made consciously and recorded, so they can be revisited rather than rediscovered:
- macOS arm64 only, no universal2. Every target machine is Apple silicon; a universal binary doubles the size for nobody.
- Ad-hoc code signature only. Files installed by
pipcarry no quarantine attribute, so Gatekeeper never evaluates them; Developer ID signing and notarisation buy nothing on this path. Should a browser-download path ever matter, the README says what to add. - Publish to a release page, not an index. Wheels and their
minisign signatures land on the
public
python-can-kadapter-distreleases, signed with a dedicated key whose public half is in the README. A private PyPI index would addpip install --index-urlconvenience at the cost of another service to run; three wheels per release didn't justify it.
Key takeaways
- A C ABI over a Rust
cdylib, consumed throughctypes, gives you one wheel per platform for every Python 3 and a library any language can load. PyO3 is the better tool when Python is the only consumer and rich Python objects matter. - Don't fake thread safety at the boundary. If the Rust object is
&mut selfand notSync, give it a thread of its own and expose channels; the python-can sender/Notifierpattern maps onto that exactly. - Keep the ABI small and check it from both sides: an ABI version function
read at load time, a
#[repr(C)]struct whose size is asserted in a Python test, and status codes that mirror the Rust error enum. - Error detail needs a home even when the call that failed produced no
handle. A thread-local "last open error" turned
IOintoPermission denied— the difference between a bug report and a udev rule. - A
ctypespackage is apy3-none-<platform>wheel. Overridebdist_wheel.get_tag(); let the compiler's deployment target, not the runner's Python, decide the macOS tag. - On macOS, don't let rustc strip your
cdylib(rustc 1.97 and earlier): setstrip = "none"and use/usr/bin/strip -x. Assertstroff % 8 == 0anddlopenthe artifact in CI. - A release pipeline should install the wheel it built and run the tests against the bundled binary before signing. "It compiled" is not "it loads".
Related reading
- python-can documentation — writing a new interface
- The Rustonomicon — FFI
- PyPA platform compatibility tags
- llvm/llvm-project#203678 — llvm-objcopy mis-aligns the Mach-O string table
- rust-lang/rust#157750 — stripped cdylibs fail to dlopen on macOS 27
- rustycan — the CAN analyser whose adapter layer this exports
- rustybbd — the CANopen bootloader flasher built on the same adapter crate