fix: add docs.rs stub ASIO bindings (#1075)

* Generate minimal ASIO bindings when DOCS_RS is set so docs.rs can
build without the ASIO SDK or MSVC toolchain.

* Add package.metadata.docs.rs default-target and empty targets to
asio-sys/Cargo.toml.

* Provide a c_long alias on non-Windows platforms to match Windows i32.

Author: roderickvd

asio-sys/CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+- Fixed docs.rs documentation build by generating stub bindings when building for docs.rs
+
 ## [0.2.3] - 2025-12-12
 
 ### Added

asio-sys/Cargo.toml

@@ -20,3 +20,7 @@ parse_cfg = "4.1"
 [dependencies]
 num-derive = "0.4"
 num-traits = "0.2"
+
+[package.metadata.docs.rs]
+default-target = "x86_64-pc-windows-msvc"
+targets = []

asio-sys/asio_stub_bindings.rs

@@ -0,0 +1,198 @@
+// Stub bindings for docs.rs
+// These are minimal type and function definitions to allow documentation generation
+// without requiring the actual ASIO SDK.
+
+use std::os::raw::{c_char, c_double, c_void};
+
+// On Windows (the only platform where ASIO actually runs), c_long is i32.
+// On non-Windows platforms (for docs.rs and local testing), redefine c_long as i32 to match.
+#[cfg(target_os = "windows")]
+use std::os::raw::c_long;
+#[cfg(not(target_os = "windows"))]
+type c_long = i32;
+
+pub type ASIOBool = c_long;
+pub type ASIOError = c_long;
+pub type ASIOSampleRate = c_double;
+
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct ASIOSamples {
+    pub hi: u32,
+    pub lo: u32,
+}
+
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct ASIOTimeStamp {
+    pub hi: u32,
+    pub lo: u32,
+}
+
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct ASIODriverInfo {
+    pub asioVersion: c_long,
+    pub driverVersion: c_long,
+    pub name: [c_char; 32],
+    pub errorMessage: [c_char; 124],
+    pub sysRef: *mut c_void,
+}
+
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct ASIOChannelInfo {
+    pub channel: c_long,
+    pub isInput: ASIOBool,
+    pub isActive: ASIOBool,
+    pub channelGroup: c_long,
+    pub type_: c_long,
+    pub name: [c_char; 32],
+}
+
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct ASIOBufferInfo {
+    pub isInput: ASIOBool,
+    pub channelNum: c_long,
+    pub buffers: [*mut c_void; 2],
+}
+
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct ASIOCallbacks {
+    pub bufferSwitch: *const c_void,
+    pub sampleRateDidChange: *const c_void,
+    pub asioMessage: *const c_void,
+    pub bufferSwitchTimeInfo: *const c_void,
+}
+
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct AsioTimeInfo {
+    pub speed: c_double,
+    pub systemTime: ASIOTimeStamp,
+    pub samplePosition: ASIOSamples,
+    pub sampleRate: ASIOSampleRate,
+    pub flags: c_long,
+    pub reserved: [c_char; 12],
+}
+
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct ASIOTimeCode {
+    pub speed: c_double,
+    pub timeCodeSamples: ASIOSamples,
+    pub flags: c_long,
+    pub future: [c_char; 64],
+}
+
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct ASIOTime {
+    pub reserved: [c_long; 4],
+    pub timeInfo: AsioTimeInfo,
+    pub timeCode: ASIOTimeCode,
+}
+
+#[repr(transparent)]
+#[derive(Debug, Copy, Clone)]
+pub struct AsioTimeInfoFlags(pub u32);
+
+impl AsioTimeInfoFlags {
+    pub const kSystemTimeValid: Self = Self(1);
+    pub const kSamplePositionValid: Self = Self(1 << 1);
+}
+
+impl std::ops::BitOr for AsioTimeInfoFlags {
+    type Output = Self;
+    fn bitor(self, rhs: Self) -> Self {
+        Self(self.0 | rhs.0)
+    }
+}
+
+#[repr(transparent)]
+#[derive(Debug, Copy, Clone)]
+pub struct ASIOTimeCodeFlags(pub u32);
+
+// Stub functions (will never be called on docs.rs)
+#[no_mangle]
+pub unsafe extern "C" fn ASIOInit(_info: *mut ASIODriverInfo) -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIOExit() -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIOStart() -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIOStop() -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIOGetChannels(_ins: *mut c_long, _outs: *mut c_long) -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIOGetChannelInfo(_info: *mut ASIOChannelInfo) -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIOCreateBuffers(
+    _infos: *mut ASIOBufferInfo,
+    _num: c_long,
+    _size: c_long,
+    _callbacks: *mut ASIOCallbacks,
+) -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIODisposeBuffers() -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIOGetBufferSize(
+    _min: *mut c_long,
+    _max: *mut c_long,
+    _pref: *mut c_long,
+    _gran: *mut c_long,
+) -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIOGetSamplePosition(
+    _pos: *mut ASIOSamples,
+    _stamp: *mut ASIOTimeStamp,
+) -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn ASIOOutputReady() -> ASIOError {
+    0
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn get_driver_names(_names: *mut *mut c_char, _max: c_long) -> c_long {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn load_asio_driver(_name: *mut c_char) -> bool {
+    false
+}
+#[no_mangle]
+pub unsafe extern "C" fn remove_current_driver() {}
+#[no_mangle]
+pub unsafe extern "C" fn get_sample_rate(_rate: *mut c_double) -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn set_sample_rate(_rate: c_double) -> ASIOError {
+    0
+}
+#[no_mangle]
+pub unsafe extern "C" fn can_sample_rate(_rate: c_double) -> ASIOError {
+    0
+}

asio-sys/build.rs

@@ -41,6 +41,14 @@ fn is_msvc() -> bool {
 }
 
 fn main() {
+    // When building on docs.rs, skip the actual build and generate stub bindings
+    if std::env::var("DOCS_RS").is_ok() {
+        println!("cargo:warning=Building for docs.rs - generating stub bindings");
+        let out_dir = PathBuf::from(env::var("OUT_DIR").expect("bad path"));
+        create_stub_bindings(&out_dir);
+        return;
+    }
+
     println!("cargo:rerun-if-env-changed={}", CPAL_ASIO_DIR);
 
     // ASIO SDK directory
@@ -130,6 +138,17 @@ fn create_lib(cpal_asio_dir: &Path) {
         .compile("libasio.a");
 }
 
+/// Creates stub bindings for docs.rs
+///
+/// Since docs.rs builds in a sandboxed environment without network access
+/// and cannot cross-compile Windows MSVC targets with C++ dependencies,
+/// we generate minimal stub bindings that allow documentation to be built.
+fn create_stub_bindings(out_dir: &Path) {
+    let stub_content = include_str!("asio_stub_bindings.rs");
+    let binding_path = out_dir.join("asio_bindings.rs");
+    std::fs::write(&binding_path, stub_content).expect("Failed to write stub bindings");
+}
+
 fn create_bindings(cpal_asio_dir: &PathBuf) {
     let mut asio_header = None;
     let mut asio_sys_header = None;

asio-sys/src/bindings/mod.rs

@@ -6,13 +6,20 @@ use self::errors::{AsioError, AsioErrorWrapper, LoadDriverError};
 use num_traits::FromPrimitive;
 
 use std::ffi::{CStr, CString};
-use std::os::raw::{c_char, c_double, c_long, c_void};
+use std::os::raw::{c_char, c_double, c_void};
 use std::ptr::null_mut;
 use std::sync::{
     atomic::{AtomicBool, Ordering},
     Arc, Mutex, MutexGuard, Weak,
 };
 
+// On Windows (where ASIO actually runs), c_long is i32.
+// On non-Windows platforms (for docs.rs and local testing), redefine c_long as i32 to match.
+#[cfg(target_os = "windows")]
+use std::os::raw::c_long;
+#[cfg(not(target_os = "windows"))]
+type c_long = i32;
+
 // Bindings import
 use self::asio_import as ai;