René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Provide `os` module for `wasm32-unknown-unknown` target","articleBody":"## Summary\n\nCurrently, RustPython does not provide the `os` module for `wasm32-unknown-unknown`. The module is gated behind the `host_env` feature, and the wasm32 example project disables it (`default-features = false, features = [\"compiler\"]`). However, CPython's Emscripten build provides an `os` module with a reduced function set, and many Python packages do `import os` at the top level. Without the `os` module, even `os.path.join()` (pure Python) fails with `ImportError`.\n\n## Motivation\n\n- Many Python packages unconditionally `import os` at the top level — they currently fail entirely on wasm32-unknown-unknown\n- `os.path` functions (`join`, `dirname`, `basename`, etc.) are pure Python and would work fine if the module existed\n- Constants like `os.sep`, `os.name`, `os.O_RDONLY` are useful even without real I/O\n- Functions like `os.fspath()`, `os.getpid()`, `os.strerror()` can return sensible values\n- CPython's Emscripten build takes this approach — provide the module, let unsupported operations raise `OSError` at runtime\n\n## Problem Analysis\n\nThe `os` module (specifically `_os` in `os.rs`) fails to compile on `wasm32-unknown-unknown` due to several dependencies:\n\n### 1. `crt_fd.rs` depends on `libc`\n- `mod c { pub(super) use libc::*; }` — `libc` exports nothing for `wasm32-unknown-unknown`\n- Functions like `c::open()`, `c::close()`, `c::read()`, `c::write()`, `c::fsync()`, `c::ftruncate()` don't exist\n- Constants like `c::EBADF`, `c::off_t` don't exist\n- Currently gated: `#[cfg(all(feature = \"std\", any(unix, windows, target_os = \"wasi\")))]` in `lib.rs`\n\n### 2. `fileutils.rs` depends on `libc::stat`\n- `pub use libc::stat as StatStruct` on non-windows — no `libc::stat` on wasm32\n- `fstat()` uses `libc::fstat()` — doesn't exist\n- Currently gated: `#[cfg(all(feature = \"std\", any(not(target_arch = \"wasm32\"), target_os = \"wasi\")))]`\n\n### 3. `os.rs` uses `libc` directly\n- `#[pyattr] use libc::{O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY}` — empty on wasm32\n- `libc::EINTR` in read/write retry loops\n- `libc::isatty()` in `isatty()`\n- `libc::strerror()` in `strerror()`\n- `libc::lseek()` in `lseek()`\n- `libc::nl_langinfo()` in `device_encoding()`\n- `libc::stat/lstat/fstat/fstatat` in `stat_inner()`\n\n### 4. `num_cpus` crate — not available for `wasm32-unknown-unknown`\n- Used in `cpu_count()`\n\n### 5. `os_open()` is gated behind `cfg(any(unix, windows, target_os = \"wasi\"))`\n\n## Proposed Solution\n\n**Approach**: Compile-only support — the `os` module compiles and is importable on wasm32-unknown-unknown. Functions that can't work on wasm32 will raise `OSError` at runtime (since `std::fs` returns errors). Constants and path functions work normally.\n\n### Files to Modify\n\n#### `crates/common/src/lib.rs`\nExpand cfg gates to include wasm32-unknown-unknown:\n```rust\n// crt_fd: include wasm32\n#[cfg(all(feature = \"std\", any(unix, windows, target_os = \"wasi\", target_arch = \"wasm32\")))]\npub mod crt_fd;\n\n// fileutils: remove wasm32 exclusion\n#[cfg(feature = \"std\")]\npub mod fileutils;\n```\n\n#### `crates/common/src/crt_fd.rs`\nAdd a wasm32-specific `mod c` block (similar to the existing Windows-specific sections):\n```rust\n#[cfg(all(target_arch = \"wasm32\", not(any(unix, windows, target_os = \"wasi\"))))]\nmod c {\n    pub type off_t = i64;\n    pub type c_int = i32;\n    pub type c_char = i8;\n    pub const EBADF: c_int = 9;\n\n    // Stub functions that always return -1\n    pub unsafe fn open(_: *const c_char, _: c_int, _: c_int) -\u003e c_int { -1 }\n    pub unsafe fn close(_: c_int) -\u003e c_int { -1 }\n    pub unsafe fn read(_: c_int, _: *mut u8, _: usize) -\u003e isize { -1 }\n    pub unsafe fn write(_: c_int, _: *const u8, _: usize) -\u003e isize { -1 }\n    pub unsafe fn fsync(_: c_int) -\u003e c_int { -1 }\n    pub unsafe fn ftruncate(_: c_int, _: off_t) -\u003e c_int { -1 }\n}\n```\n\n`std::os::fd` types (`OwnedFd`, `BorrowedFd`, `RawFd`) are available on wasm32 since Rust 1.84, so the existing `#[cfg(not(windows))]` imports work.\n\n#### `crates/common/src/fileutils.rs`\nAdd wasm32-specific `StatStruct` and `fstat` stub:\n```rust\n#[cfg(not(any(unix, windows, target_os = \"wasi\")))]\npub struct StatStruct { /* minimal fields matching libc::stat layout */ }\n\n#[cfg(not(any(unix, windows, target_os = \"wasi\")))]\npub fn fstat(_: crate::crt_fd::Borrowed\u003c'_\u003e) -\u003e std::io::Result\u003cStatStruct\u003e {\n    Err(std::io::Error::new(std::io::ErrorKind::Unsupported, \"fstat not supported\"))\n}\n```\n\n#### `crates/vm/src/stdlib/os.rs`\n~10 changes needed:\n- **O_\\* constants**: Define manually for wasm32 (`O_RDONLY=0`, `O_WRONLY=1`, `O_RDWR=2`, etc.)\n- **`open`/`os_open`**: Add wasm32 path returning error\n- **`read`/`write`**: Replace `libc::EINTR` with cfg-gated constant\n- **`isatty`**: Return `false` on wasm32\n- **`strerror`**: Basic error-number-to-string mapping\n- **`lseek`**: Return error on wasm32\n- **`stat_inner`**: Use `std::fs::metadata` or return error\n- **`StatResultData::from_stat`**: Handle wasm32 StatStruct fields\n- **`cpu_count`**: Return 1 on wasm32\n- **`device_encoding`**: Return \"UTF-8\" on wasm32\n- **`utime_impl`**: Return \"not supported\" error on wasm32\n\n#### `crates/vm/src/stdlib/posix_compat.rs`\nAdd `environ` for wasm32 (currently only defined for `target_os = \"wasi\"`):\n```rust\n#[cfg(all(target_arch = \"wasm32\", not(target_os = \"wasi\")))]\n#[pyattr]\nfn environ(vm: \u0026VirtualMachine) -\u003e crate::builtins::PyDictRef {\n    vm.ctx.new_dict()  // Empty dict — no env vars on bare wasm32\n}\n```\n\n### Cfg Pattern\n\nThe recurring condition is:\n```rust\n#[cfg(all(target_arch = \"wasm32\", not(any(unix, windows, target_os = \"wasi\"))))]\n```\nThis matches `wasm32-unknown-unknown` specifically (not emscripten, not wasi, not windows).\n\n## Verification Plan\n\n1. `cargo check --target wasm32-unknown-unknown -p rustpython-vm --features \"compiler,host_env\"` — must compile\n2. `cargo test -p rustpython-vm` on host — no regressions\n3. Update `example_projects/wasm32_without_js/` to optionally enable `host_env`\n4. Runtime: build wasm32 binary with `import os; print(os.name)` — should print `\"posix\"` without error\n\n## References\n\n- CPython Emscripten support: https://docs.python.org/3/using/wasm.html\n- `std::os::fd` portable stabilization (Rust 1.84): https://github.com/rust-lang/rust/issues/126198\n- `libc` crate wasm32-unknown-unknown: exports nothing — https://docs.rs/libc/latest/libc/","author":{"url":"https://github.com/youknowone","@type":"Person","name":"youknowone"},"datePublished":"2026-03-05T20:08:46.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/7363/RustPython/issues/7363"}