reorg: Fill in the src/new structure

tgross35 · tgross35 · commit 966725a56e01 · 2025-11-03T04:27:43.000-06:00
Ensure each library we provide bindings for has a home module in order to make it easier to fill things in. Where possible, I included a link to the source tree. There is also a new module `common` that contains definitions intended to be shared across multiple libraries. (backport <#4771>) (cherry picked from commit b295e78)
diff --git a/src/new/aix/mod.rs b/src/new/aix/mod.rs
@@ -0,0 +1,4 @@
+//! IBM AIX libc.
+//!
+//! * Headers are not public
+//! * Manual pages: <https://www.ibm.com/docs/en/aix> (under "Technical reference" for that version)
diff --git a/src/new/common/bsd.rs b/src/new/common/bsd.rs
@@ -0,0 +1 @@
+//! Interfaces common across the BSD family.
diff --git a/src/new/common/freebsd_like.rs b/src/new/common/freebsd_like.rs
@@ -0,0 +1 @@
+//! Interfaces common in FreeBSD-derived operating systems. This includes FreeBSD and DragonFlyBSD.
diff --git a/src/new/common/linux_like/mod.rs b/src/new/common/linux_like/mod.rs
@@ -0,0 +1 @@
+//! API that primarily comes from Linux but is also used other platforms (e.g. Android).
diff --git a/src/new/common/mod.rs b/src/new/common/mod.rs
@@ -0,0 +1,38 @@
+//! Interfaces that are common across multiple platforms
+//!
+//! We make these available everywhere but each platform must opt in to reexporting.
+//!
+//! There shouldn't be any repeated definitions or complex configuration in this module. On
+//! platforms that don't use common APIs it is fine to use `#[cfg(not(...))]`, but if a platform
+//! needs a custom definition then it should be defined in the platform-specific module.
+//!
+//! The goal is that platforms need to opt in to the definitions here, so that worst case we have
+//! an unused warning on untested platforms (rather than exposing incorrect API).
+
+#[cfg(any(
+    target_vendor = "apple",
+    target_os = "dragonfly",
+    target_os = "freebsd",
+    target_os = "netbsd",
+    target_os = "openbsd",
+))]
+mod bsd;
+
+#[cfg(any(
+    target_os = "android",
+    target_os = "emscripten",
+    target_os = "l4re",
+    target_os = "linux",
+))]
+mod linux_like;
+
+#[cfg(any(target_os = "dragonfly", target_os = "freebsd"))]
+mod freebsd_like;
+
+#[cfg(any(target_os = "netbsd", target_os = "openbsd"))]
+mod netbsd_like;
+
+#[cfg(any(target_os = "illumos", target_os = "solaris"))]
+mod solarish;
+
+mod posix;
diff --git a/src/new/common/netbsd_like.rs b/src/new/common/netbsd_like.rs
@@ -0,0 +1 @@
+//! Interfaces common in NetBSD-derived operating systems. This includes NetBSD and OpenBSD.
diff --git a/src/new/common/posix/mod.rs b/src/new/common/posix/mod.rs
@@ -0,0 +1 @@
+//! POSIX APIs that are used by a number of platforms
diff --git a/src/new/common/solarish.rs b/src/new/common/solarish.rs
@@ -0,0 +1 @@
+//! Interfaces common in solaris-derived operating systems. This includes Solaris and Illumos.
diff --git a/src/new/cygwin/mod.rs b/src/new/cygwin/mod.rs
@@ -0,0 +1,3 @@
+//! Cygwin libc.
+//!
+//! * Headers: <https://github.com/cygwin/cygwin/tree/main/winsup/cygwin/include>
diff --git a/src/new/dragonfly/mod.rs b/src/new/dragonfly/mod.rs
@@ -0,0 +1,4 @@
+//! DragonFly BSD libc.
+//!
+//! * Headers: <https://github.com/DragonFlyBSD/DragonFlyBSD>
+//! * Manual pages: <https://leaf.dragonflybsd.org/cgi/web-man>
diff --git a/src/new/emscripten/mod.rs b/src/new/emscripten/mod.rs
@@ -0,0 +1,3 @@
+//! Emscripten libc.
+//!
+//! * Headers: <https://github.com/emscripten-core/emscripten/tree/main/system/lib/libc>
diff --git a/src/new/espidf/mod.rs b/src/new/espidf/mod.rs
@@ -0,0 +1,2 @@
+//! Expressif libc.
+// FIXME(espidf): link to headers needed.
diff --git a/src/new/freebsd/mod.rs b/src/new/freebsd/mod.rs
@@ -0,0 +1,4 @@
+//! FreeBSD libc.
+//!
+//! * Headers: <https://github.com/freebsd/freebsd-src/blob/main/sys/riscv/include/ucontext.h>
+//! * Symbol map: <https://github.com/freebsd/freebsd-src/blob/main/lib/libc/gen/Symbol.map>
diff --git a/src/new/fuchsia/mod.rs b/src/new/fuchsia/mod.rs
@@ -0,0 +1,2 @@
+//! Fuschia libc.
+// FIXME(fuchsia): link to headers needed.
diff --git a/src/new/glibc/mod.rs b/src/new/glibc/mod.rs
@@ -0,0 +1,4 @@
+//! GNU libc.
+//!
+//! * Headers: <https://sourceware.org/git/?p=glibc.git> (official)
+//! * Headers: <https://github.com/bminor/glibc> (mirror)
diff --git a/src/new/haiku/mod.rs b/src/new/haiku/mod.rs
@@ -0,0 +1,2 @@
+//! Haiku OS libc.
+// FIXME(haiku): link to headers needed.
diff --git a/src/new/hermit_abi/mod.rs b/src/new/hermit_abi/mod.rs
@@ -0,0 +1,3 @@
+//! Hermit kernel libc.
+//!
+//! * Headers: <https://github.com/hermit-os/hermit-rs/tree/main/hermit-abi>
diff --git a/src/new/horizon/mod.rs b/src/new/horizon/mod.rs
@@ -0,0 +1,2 @@
+//! Switch libc.
+// FIXME(horizon): link to headers or manpages needed.
diff --git a/src/new/hurd/mod.rs b/src/new/hurd/mod.rs
@@ -0,0 +1,2 @@
+//! GNU Hurd libc.
+// FIXME(hurd): link to headers needed.
diff --git a/src/new/illumos/mod.rs b/src/new/illumos/mod.rs
@@ -0,0 +1,2 @@
+//! Illumos libc.
+// FIXME(illumos): link to headers needed.
diff --git a/src/new/l4re/mod.rs b/src/new/l4re/mod.rs
@@ -0,0 +1,3 @@
+//! L4re.
+//!
+//! * Headers: <https://github.com/kernkonzept/l4re-core/tree/master/libc/uclibc-ng>
diff --git a/src/new/mod.rs b/src/new/mod.rs
@@ -14,11 +14,36 @@
 //!
 //! All modules are only crate-public since we don't reexport this structure.
 
-// Libraries available on each platform
+mod common;
+
+/* The `pub(crate) use ...` statements are commented while the modules are empty */
+
+// Platform libraries and combined platform+libc
+//
+// Not supported or not needed:
+// * amdhsa
+// * cuda
+// * lynxos178
+// * managarm
+// * motor
+// * none
+// * psp
+// * psx
+// * uefi
+// * unknown
+// * vexos
+// * zkvm
+//
+// Combined to target_vendor = "apple"
+// * ios
+// * macos
+// * tvos
+// * visionos
+// * watchos
 cfg_if! {
-    if #[cfg(target_os = "linux")] {
-        mod linux_uapi;
-        pub(crate) use linux_uapi::*;
+    if #[cfg(target_os = "aix")] {
+        mod aix;
+        // pub(crate) use aix::*;
     } else if #[cfg(target_os = "android")] {
         mod bionic_libc;
         pub(crate) use bionic_libc::*;
@@ -27,6 +52,113 @@ cfg_if! {
         mod apple_xnu;
         pub(crate) use apple_libc::*;
         pub(crate) use apple_xnu::*;
+    } else if #[cfg(target_os = "cygwin")] {
+        mod cygwin;
+        // pub(crate) use cygwin::*;
+    } else if #[cfg(target_os = "dragonfly")] {
+        mod dragonfly;
+        // pub(crate) use dragonfly::*;
+    } else if #[cfg(target_os = "emscripten")] {
+        mod emscripten;
+        // pub(crate) use emscripten::*;
+    } else if #[cfg(target_os = "espidf")] {
+        mod espidf;
+        // pub(crate) use espidf::*;
+    } else if #[cfg(target_os = "freebsd")] {
+        mod freebsd;
+        // pub(crate) use freebsd::*;
+    } else if #[cfg(target_os = "fuchsia")] {
+        mod fuchsia;
+        // pub(crate) use fuchsia::*;
+    } else if #[cfg(target_os = "haiku")] {
+        mod haiku;
+        // pub(crate) use haiku::*;
+    } else if #[cfg(target_os = "hermit")] {
+        mod hermit_abi;
+        // pub(crate) use hermit_abi::*;
+    } else if #[cfg(target_os = "horizon")] {
+        mod horizon;
+        // pub(crate) use horizon::*;
+    } else if #[cfg(target_os = "hurd")] {
+        mod hurd;
+        // pub(crate) use hurd::*;
+    } else if #[cfg(target_os = "illumos")] {
+        mod illumos;
+        // pub(crate) use illumos::*;
+    } else if #[cfg(target_os = "l4re")] {
+        mod l4re;
+        // pub(crate) use l4re::*;
+    } else if #[cfg(target_os = "linux")] {
+        mod linux_uapi;
+        pub(crate) use linux_uapi::*;
+    } else if #[cfg(target_os = "netbsd")] {
+        mod netbsd;
+        // pub(crate) use netbsd::*;
+    } else if #[cfg(target_os = "nto")] {
+        mod nto;
+        // pub(crate) use nto::*;
+    } else if #[cfg(target_os = "nuttx")] {
+        mod nuttx;
+        // pub(crate) use nuttx::*;
+    } else if #[cfg(target_os = "openbsd")] {
+        mod openbsd;
+        // pub(crate) use openbsd::*;
+    } else if #[cfg(target_os = "redox")] {
+        mod redox;
+        // pub(crate) use redox::*;
+    } else if #[cfg(target_os = "rtems")] {
+        mod rtems;
+        // pub(crate) use rtems::*;
+    } else if #[cfg(target_os = "solaris")] {
+        mod solaris;
+        // pub(crate) use solaris::*;
+    } else if #[cfg(target_os = "solid_asp3")] {
+        mod solid;
+        // pub(crate) use solid::*;
+    } else if #[cfg(target_os = "teeos")] {
+        mod teeos;
+        // pub(crate) use teeos::*;
+    } else if #[cfg(target_os = "trusty")] {
+        mod trusty;
+        // pub(crate) use trusty::*;
+    } else if #[cfg(target_os = "vita")] {
+        mod vita;
+        // pub(crate) use vita::*;
+    } else if #[cfg(target_os = "vxworks")] {
+        mod vxworks;
+        // pub(crate) use vxworks::*;
+    } else if #[cfg(target_os = "wasi")] {
+        mod wasi;
+        // pub(crate) use wasi::*;
+    } else if #[cfg(target_os = "windows")] {
+        mod ucrt;
+        // pub(crate) use ucrt::*;
+    } else if #[cfg(target_os = "xous")] {
+        mod xous;
+        // pub(crate) use xous::*;
+    }
+}
+
+// Multi-platform libc
+cfg_if! {
+    if #[cfg(target_env = "gnu")] {
+        mod glibc;
+        // pub(crate) use glibc::*;
+    } else if #[cfg(target_env = "musl")] {
+        mod musl;
+        // pub(crate) use musl::*;
+    } else if #[cfg(target_env = "newlib")] {
+        mod newlib;
+        // pub(crate) use newlib::*;
+    } else if #[cfg(target_env = "relibc")] {
+        mod relibc;
+        // pub(crate) use relibc::*;
+    } else if #[cfg(target_env = "sgx")] {
+        mod sgx;
+        // pub(crate) use sgx::*;
+    } else if #[cfg(target_env = "uclibc")] {
+        mod uclibc;
+        // pub(crate) use uclibc::*;
     }
 }
 
diff --git a/src/new/musl/mod.rs b/src/new/musl/mod.rs
@@ -0,0 +1,4 @@
+//! Musl libc.
+//!
+//! * Headers: <https://git.musl-libc.org/cgit/musl> (official)
+//! * Headers: <https://github.com/kraj/musl> (mirror)
diff --git a/src/new/netbsd/mod.rs b/src/new/netbsd/mod.rs
@@ -0,0 +1,3 @@
+//! NetBSD libc.
+//!
+//! * Manual pages: <https://man.netbsd.org/>
diff --git a/src/new/newlib/mod.rs b/src/new/newlib/mod.rs
@@ -0,0 +1,2 @@
+//! Newlib libc.
+// FIXME(newlib): link to headers needed.
diff --git a/src/new/nto/mod.rs b/src/new/nto/mod.rs
@@ -0,0 +1,2 @@
+//! QNX Neutrino libc.
+// FIXME(nto): link to manpages needed.
diff --git a/src/new/nuttx/mod.rs b/src/new/nuttx/mod.rs
@@ -0,0 +1,2 @@
+//! RTEMS libc.
+// FIXME(nuttx): link to headers needed.
diff --git a/src/new/openbsd/mod.rs b/src/new/openbsd/mod.rs
@@ -0,0 +1,4 @@
+//! OpenBSD libc.
+//!
+//! * Headers: <https://github.com/openbsd/src>
+//! * Manual pages: <https://man.openbsd.org/>
diff --git a/src/new/redox/mod.rs b/src/new/redox/mod.rs
@@ -0,0 +1,3 @@
+//! Redox libc.
+//!
+//! * Headers: <https://gitlab.redox-os.org/redox-os/relibc>
diff --git a/src/new/relibc/mod.rs b/src/new/relibc/mod.rs
@@ -0,0 +1,3 @@
+//! Redox OS libc.
+//!
+//! * Headers: <https://gitlab.redox-os.org/redox-os/relibc>
diff --git a/src/new/rtems/mod.rs b/src/new/rtems/mod.rs
@@ -0,0 +1,2 @@
+//! RTEMS libc.
+// FIXME(rtems): link to headers needed.
diff --git a/src/new/sgx/mod.rs b/src/new/sgx/mod.rs
@@ -0,0 +1 @@
+
diff --git a/src/new/solaris/mod.rs b/src/new/solaris/mod.rs
@@ -0,0 +1,3 @@
+//! Solaris libc.
+//!
+//! * Manual pages: <https://docs.oracle.com/cd/E36784_01/> (under "Reference Manuals")
diff --git a/src/new/solid/mod.rs b/src/new/solid/mod.rs
@@ -0,0 +1,2 @@
+//! Kyoto Microcomputer SOLID.
+// FIXME(solid): link to headers needed.
diff --git a/src/new/teeos/mod.rs b/src/new/teeos/mod.rs
@@ -0,0 +1,2 @@
+//! Per the target docs, TEEOS uses part of musl as its libc.
+// FIXME(teeos): link to headers needed.
diff --git a/src/new/trusty/mod.rs b/src/new/trusty/mod.rs
@@ -0,0 +1,2 @@
+//! Trusty libc.
+// FIXME(trusty): link to headers needed.
diff --git a/src/new/uclibc/mod.rs b/src/new/uclibc/mod.rs
@@ -0,0 +1,4 @@
+//! uClibc.
+//!
+//! * About: <https://uclibc.org/>
+//! * Headers: <https://github.com/kraj/uClibc> (mirror)
diff --git a/src/new/ucrt/mod.rs b/src/new/ucrt/mod.rs
@@ -0,0 +1,4 @@
+//! Windows Universal C Runtime.
+//!
+//! * Manual pages: <https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/crt-alphabetical-function-reference?view=msvc-170>
+//! * UCRT information: <https://learn.microsoft.com/en-us/cpp/c-runtime-library/compatibility?view=msvc-170>
diff --git a/src/new/vita/mod.rs b/src/new/vita/mod.rs
@@ -0,0 +1,2 @@
+//! VITASDK system library.
+// FIXME(vita): link to headers or manpages needed.
diff --git a/src/new/vxworks/mod.rs b/src/new/vxworks/mod.rs
@@ -0,0 +1,2 @@
+//! VxWorks libc.
+// FIXME(vxworks): link to headers needed.
diff --git a/src/new/wasi/mod.rs b/src/new/wasi/mod.rs
@@ -0,0 +1,3 @@
+//! WASI libc.
+//!
+//! * Headers: <https://github.com/WebAssembly/wasi-libc>
diff --git a/src/new/xous/mod.rs b/src/new/xous/mod.rs
@@ -0,0 +1,2 @@
+//! Xous libc.
+// FIXME(xous): link to headers needed.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+//! Interfaces common across the BSD family.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+//! Interfaces common in FreeBSD-derived operating systems. This includes FreeBSD and DragonFlyBSD.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+//! API that primarily comes from Linux but is also used other platforms (e.g. Android).`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+//! Interfaces common in NetBSD-derived operating systems. This includes NetBSD and OpenBSD.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+//! POSIX APIs that are used by a number of platforms`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+//! Interfaces common in solaris-derived operating systems. This includes Solaris and Illumos.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+//! Cygwin libc.`
	`2`	`+//!`
	`3`	`+//! * Headers: <https://github.com/cygwin/cygwin/tree/main/winsup/cygwin/include>`