[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-3581":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":33,"readmeContent":34,"aiSummary":35,"trendingCount":16,"starSnapshotCount":16,"syncStatus":14,"lastSyncTime":36,"discoverSource":37},3581,"elfuse","sysprog21\u002Felfuse","sysprog21","Run Arm64\u002Fx86-64 Linux ELF binaries on macOS Apple Silicon","",null,"C",153,12,2,10,0,17,19,58,51,78.64,"Apache License 2.0",false,"main",[26,27,28,29,30,31,32],"arm64","darwin-kernel","hypervisor-framework","linux-compatibility","linux-syscall","macos","virtualization","2026-06-12 04:00:18","# elfuse\n\n`elfuse` runs aarch64-linux ELF binaries on macOS Apple Silicon through\nApple's Hypervisor.framework. It is a process-scoped Linux user-space runtime:\nguest code executes on the CPU inside a lightweight VM, while Linux syscalls\nare intercepted and translated to macOS behavior in host-side handlers.\n\nThis is not a container engine and not a general-purpose Linux kernel. It is a\nfocused compatibility layer for running Linux user-space workloads directly from\nthe macOS shell, with support for static binaries, dynamic loaders via\n`--sysroot`, guest threads, process management, signals, `\u002Fproc` emulation, and\nguest debugging through a built-in GDB RSP stub.\n\n## Highlights\n\n- Native Apple Silicon execution through Hypervisor.framework\n- Static and dynamically linked `aarch64-linux` ELF binaries\n- Linux-style processes, threads, signals, timers, futexes, and polling\n- Synthetic `\u002Fproc` and selected `\u002Fdev` emulation for user-space probes\n- Built-in GDB Remote Serial Protocol stub usable from `gdb` or `lldb`\n- Self-contained test matrix that cross-checks elfuse against QEMU\n\n## Requirements\n\n- macOS on Apple Silicon\n- macOS 13 or newer\n- Xcode Command Line Tools, `clang`, `codesign`, and GNU `make`\n- GNU `objcopy` from Homebrew `binutils`, or `llvm-objcopy`\n- Hypervisor entitlement: `com.apple.security.hypervisor`\n\nFor guest test binaries, the project also expects an AArch64 Linux cross\ntoolchain. The default paths in `mk\u002Ftoolchain.mk` target the toolchain layout\nused by the repository test harness, but `CROSS_COMPILE` and\n`BAREMETAL_CROSS` are overridable.\n\nTo run `make check`, install the Homebrew AArch64 embedded toolchain first:\n\n```sh\nbrew install --cask gcc-aarch64-embedded\n```\n\n## Quick Start\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002Fsysprog21\u002Felfuse\ncd elfuse\nmake elfuse\nmake test-busybox\nbuild\u002Felfuse build\u002Fbusybox\n```\nReplace `build\u002Fbusybox` with Arm64\u002FLinux executable files.\n\nFor dynamically linked guests:\n\n```sh\nbuild\u002Felfuse --sysroot \u002Fpath\u002Fto\u002Fsysroot .\u002Fpath\u002Fto\u002Fprogram\n```\n\nFor early debugging:\n\n```sh\nbuild\u002Felfuse --gdb 1234 --gdb-stop-on-entry .\u002Fpath\u002Fto\u002Fprogram\n```\n\nThe build signs `build\u002Felfuse` before use. Override the signing identity with\n`SIGN_IDENTITY=\"Developer ID ...\"` when needed.\n\n## Documentation\n\n- [docs\u002Fusage.md](docs\u002Fusage.md): command-line options, dynamic linking via\n  `--sysroot`, and attaching `gdb` \u002F `lldb` to the built-in stub.\n- [docs\u002Ftesting.md](docs\u002Ftesting.md): build prerequisites, the `make check`\n  flow, the QEMU cross-check matrix, and fixture handling.\n- [docs\u002Finternals.md](docs\u002Finternals.md): canonical technical reference --\n  HVF constraints, EL1 shim and HVC protocol, page-table splitting, syscall\n  translation tables, threads\u002Ffutex, fork\u002Fclone IPC, signals, ptrace, and\n  the GDB stub.\n\n## Build And Validation\n\nMost common targets:\n\n```sh\nmake elfuse        # build and codesign build\u002Felfuse\nmake check         # quick unit suite + BusyBox applet smoke\nmake test-gdbstub  # debugger integration\nmake test-matrix   # cross-check elfuse against QEMU on the same corpus\nmake lint          # clang-tidy\n```\n\n`make check` is the recommended pre-commit gate. `make test-matrix` is the\nrecommended gate for changes touching procfs, dynamic linking, networking,\nor process semantics. See [docs\u002Ftesting.md](docs\u002Ftesting.md) for the full\ntarget list, fixture flow, and validation-by-change-type guidance.\n\n## Scope And Limitations\n\n`elfuse` targets pragmatic Linux user-space compatibility. Supported areas\ninclude ELF and dynamic-loader bootstrap, sysroot-aware path translation,\nLinux-style FD semantics, `fork` \u002F `clone` \u002F `execve` \u002F `wait*` \u002F ptrace,\nsignals and timers, polling families (`epoll`, `eventfd`, `signalfd`,\n`timerfd`, `inotify`), sockets and netlink, and synthetic `\u002Fproc`, `\u002Fdev`,\nand `\u002Fproc\u002Fnet\u002F*` views sufficient for tools such as BusyBox `ps`, `uptime`,\nand `top`.\n\nBoundaries to be aware of:\n\n- The target is Linux user-space ABI compatibility, not kernel\n  virtualization. `\u002Fproc`, `\u002Fdev`, and mount data are compatibility views.\n- HVF allows one VM per host process, so Linux-style `fork` is implemented\n  via `posix_spawn` plus state transfer (a fast CoW path is used when\n  available -- see [docs\u002Finternals.md](docs\u002Finternals.md)).\n- `MAP_SHARED` is treated as `MAP_PRIVATE`; this matches single-process\n  guest semantics and unblocks tools that expect file-backed mappings.\n- Unsupported syscalls return Linux-style errors rather than silently\n  succeeding.\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE).\n\nCopyright 2026 elfuse contributors  \nCopyright 2025 Moritz Angermann, zw3rk pte. ltd.\n","elfuse 是一个能够在 macOS Apple Silicon 上运行 Arm64\u002FLinux ELF 二进制文件的工具。它通过 Apple 的 Hypervisor.framework 实现了轻量级虚拟机环境，使得 Linux 用户空间程序可以直接在 macOS 上执行，同时拦截并转换 Linux 系统调用以适应 macOS 行为。该工具支持静态和动态链接的 aarch64-linux ELF 二进制文件、Linux 进程与线程管理、信号处理、\u002Fproc 文件系统模拟以及通过内置 GDB RSP stub 进行调试等功能。适用于需要在 macOS 上直接运行或测试基于 Arm64 架构的 Linux 应用程序的开发者。","2026-06-11 02:54:47","CREATED_QUERY"]