Requirements and compatibility
Build host
Release XLLs target the Microsoft Visual C++ ABI and are expected to be built and linked on Windows with:
- Windows 10 or Windows 11;
- Rust 1.98.1 or a compatible toolchain for this source snapshot;
- the
i686-pc-windows-msvcand/orx86_64-pc-windows-msvcRust targets; - Visual Studio Build Tools with Desktop development with C++;
- Cargo and
cargo-xlfn.
The repository pins the toolchain and both targets in rust-toolchain.toml:
[toolchain]
channel = "1.98.1"
profile = "minimal"
components = ["clippy", "rustfmt"]
targets = ["i686-pc-windows-msvc", "x86_64-pc-windows-msvc"]
Host-side tests that do not link an XLL may run on other operating systems. Packaging and release qualification still require Windows MSVC artifacts and real Excel.
Source-snapshot installation: the workspace is configured with publishable crates, but an official crates.io release may not yet be available. Until it is published, install
cargo-xlfnfrom an audited Git revision or local checkout and replace generatedversion = "0.2"dependencies with the same Git revision or a localpath. The version-based dependency examples in this guide show the intended form for a published release.
Excel bitness
Match the XLL to the Excel process, not to the operating system:
| Excel process | Rust target | Package directory |
|---|---|---|
| 32-bit Excel | i686-pc-windows-msvc | package/win-x86/ |
| 64-bit Excel | x86_64-pc-windows-msvc | package/win-x64/ |
A 64-bit edition of Windows can run 32-bit Excel. In that case, use the x86 XLL.
Excel API level
xlfn uses the Excel 12/XLOPER12 interface. Asynchronous worksheet functions use Excel’s native asynchronous UDF ABI and are intended for Excel versions that provide that ABI; the project documentation uses Excel 2010 or later as the operational baseline for this feature.
Do not convert this implementation target into an unqualified compatibility claim. Qualify each release candidate against the exact Excel channels, bitnesses, and Windows versions that you intend to support.
Rust crate features
The xlfn crate has no default features:
[dependencies]
xlfn = "0.2"
Enable only what the add-in uses:
[dependencies]
xlfn = { version = "0.2", features = ["async"] }
| Feature | Adds |
|---|---|
async | native asynchronous UDF runtime, AsyncContext, cancellation tokens, and calculation-event exports |
handles | formula-owned typed objects, aliases, and scoped handle inputs |
rtd | streaming sources, subscriptions, and RTD configuration |
unstable-cache | lower-level calculation-cache API with an explicitly unstable contract |
unstable-output | lower-level array-output API with an explicitly unstable contract |
handles and rtd are independent public capabilities. Use both async and
handles for asynchronous handle consumers. The refinement and
bench-internals features are for repository verification, not application
development. See the compatibility policy for stability scope.
Project shape
An XLL package must contain exactly one cdylib target and exactly one crate-root type attributed with #[excel_addin]. The generated lifecycle and COM exports are part of that definition. Do not hand-write competing xlAutoOpen, xlAutoClose, xlAutoRemove, xlAutoFree12, DllGetClassObject, or related exports.