skills.rest
po4yka
po4ykaCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

rust-native-linking

Diagnose and configure native C and C++ library linking for Rust build scripts and sys crates.

2|1|Updated Aug 19, 2026
Search Tags:#rust#FFI#cross-compilation#bindgen#linker errors#build.rs#native linking
One-click install
npx skills add https://github.com/po4yka/rust-skills --skill rust-native-linking-po4yka
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: rust-native-linking
Source: https://github.com/po4yka/rust-skills/tree/main/skills/rust-native-linking
Command: npx skills add https://github.com/po4yka/rust-skills --skill rust-native-linking-po4yka

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Native link and load failures in Rust projects are hard to diagnose because cargo check never links, and errors like LNK2019, undefined references, or missing DLLs surface only at build or runtime. This Skill provides triage tables, inspection commands, and build.rs rules to build, discover, bind, link, and package native C/C++ libraries correctly across host and cross targets. ## Core Features & Use Cases - Failure triage tables: Maps symptoms like cannot find -lfoo, undefined reference, LNK2019, library not loaded, and DLL not found to the failing layer, first evidence to collect, and the fix. - Artifact inspection commands: Provides platform-specific verification with readelf, nm, otool, lipo, and dumpbin to prove architecture, dependency tables, and exported symbols on the exact shipped file. - *build.rs and -sys crate guidance: Covers structured cargo::rustc-link-lib instructions in dependency order, single links ownership, deterministic change detection, host/target separation, and helper selection among cc, pkg-config, vcpkg, cmake, bindgen, and cbindgen. - Use Case: A cross-compiled build links fine with rust-lld on x86_64 Linux but fails with GNU ld on aarch64. Use the Skill's --warn-backrefs CI lane to expose the archive order defect and emit consumers before providers. ## Quick Start Ask the agent to diagnose why your Rust build fails with an undefined reference or missing DLL when linking a native library, and to fix the build.rs link instructions.

Frequently Asked Questions about rust-native-linking

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix undefined reference or LNK2019 errors when linking a native library in Rust?▼

Undefined reference errors mean a symbol or ordering problem. Identify the undefined name, find its provider's symbol table with nm or dumpbin, then add the real provider library, correct mangling, or emit the consumer before the provider in build.rs link instructions.

How do I link a C library from a Rust build.rs script?▼

Emit structured instructions from build.rs: cargo::rustc-link-search=native=<path> followed by cargo::rustc-link-lib=static=foo or dylib=foo. Put discovery and link instructions in one foo-sys crate that declares links = "foo", and use helpers like cc, pkg-config, vcpkg, or cmake instead of raw linker flags.

Why does my Rust build link with rust-lld but fail with GNU ld?▼

rust-lld tolerates backward archive references that GNU ld rejects, and x86_64 Linux uses rust-lld by default since Rust 1.90. Expose the defect with a CI lane using RUSTFLAGS="-C link-arg=-Wl,--warn-backrefs -D linker-messages" and emit each consumer archive before its provider.

Why does my Rust program run with cargo run but fail when packaged?▼

Cargo extends the loader environment with link-search paths for cargo run and cargo test, which hides missing runtime libraries. Run the installed artifact outside Cargo, and add a package-relative run path like $ORIGIN/../lib on Linux or @rpath on macOS, or ship the required DLLs on Windows.

Should I use bindgen or cbindgen for Rust FFI bindings?▼

Use bindgen to generate Rust declarations from C or C++ headers, and cbindgen to generate a C header from a Rust ABI. Prefer checked-in bindgen output with a CI regeneration diff gate; never run cbindgen in build.rs to modify package source.

Why does cargo check pass but the build still fail at link time?▼

cargo check does not link, so a green check proves nothing about link inputs, loader paths, or exported symbols. Build the exact target and crate type that ships, inspect the artifact's dependency table and symbols, and run the packaged artifact outside Cargo.

Related Skills

Explore More Software Engineering Skills→
golemcloudgolemcloud
1.5k

moonbit-c-binding

Write MoonBit bindings to C libraries using native FFI declarations and stubs.

Official
Advanced
preedeppreedep

release-publish

Automate synchronized release publishing of kham crates to crates.io, npm, and PyPI.

Community
Advanced
maxenkomaxenko
1

rust-ci-green

Audits Rust projects and fixes formatting/clippy issues for cargo fmt --check and cargo clippy passes.

Community
Advanced
awfixers-stuffawfixers-stuff

rust-ffi

Generate Rust-C FFI bindings with bindgen and cbindgen.

Official
Advanced