docs: propose a macOS / Apple Silicon setup FAQ
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 159
- Forks
- 33
- Avg merge
- 7h 43m
- Merged PRs (30d)
- 5
Description
Summary
I recently set up and ran OSS-CRS (crs-libfuzzer) end-to-end on an Apple Silicon
Mac and hit several macOS-specific issues that weren't covered in the existing
docs. After working through them to a successful run (full prepare → build-target
→ run pipeline, producing seeds and POVs), I wrote up an FAQ and would like to
contribute it as documentation.
What the FAQ covers
- Docker Desktop + Rosetta setup for reliably running the amd64 fuzzing images on
Apple Silicon - The three most common errors on Mac and their actual root causes:
oss-crs-deps: pull access denied— really a "prepare and build-target hit
different daemons / local image not present" problem, not a registry issue- Fuzzer dies with
Killed(exit 137) — ASAN/libFuzzer instability under QEMU
emulation; resolved by enabling Rosetta cpusethandling — it's a required schema field (can't be deleted), and how
to set it for a Mac VM
oss-crs setupPhase 2 behavior on macOS (the/etc/docker/daemon.json
cgroup step doesn't apply cleanly) and how to proceed- How to confirm a successful run (seeds / POVs under SUBMIT_DIR)
Questions before I open a PR
- Would you welcome this as documentation? It's grounded in a confirmed working
configuration, not speculation. - Where would you prefer it live — e.g.
docs/faq-macos.md, a section in an
existing doc, or somewhere else? - Should I also link it from the README, or do you have a docs index it should
go into?
Happy to open the PR as soon as you confirm placement. Thanks!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the existing documentation and README to determine the preferred location and linking convention; the proposed path is docs/faq-macos.md. Use the confirmed Docker Desktop, Rosetta, cpuset, setup, and successful-run details from the issue. Done when the FAQ explains the listed macOS problems and how to verify seeds and POVs under SUBMIT_DIR.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, macos
- Domain
- devops, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100