# macOS Documentation

This directory contains macOS-specific documentation for the piker project.

## Contents

- **[compatibility-fixes.md](compatibility-fixes.md)** - Comprehensive guide to macOS compatibility issues and their solutions

## Quick Start

If you're experiencing issues running piker on macOS, check the compatibility fixes guide:

```bash
cat docs/macos/compatibility-fixes.md
```

## Key Issues Addressed

1. **Socket Credential Passing** - macOS uses different socket options than Linux
2. **Shared Memory Name Limits** - macOS limits shm names to 31 characters
3. **Cleanup Race Conditions** - Handling concurrent shared memory cleanup
4. **Async Runtime Coordination** - Proper trio/asyncio shutdown on macOS

## Platform Information

- **Tested on**: macOS 15.0+ (Darwin 25.0.0)
- **Python**: 3.13+
- **Architecture**: ARM64 (Apple Silicon) and x86_64 (Intel)

## Related Projects

These fixes may also apply to:
- [tractor](https://github.com/goodboy/tractor) - The actor runtime used by piker
- Other projects using tractor on macOS

## Contributing

Found additional macOS issues? Please:
1. Document the error and its cause
2. Provide a solution with code examples
3. Test on multiple macOS versions
4. Submit a PR updating this documentation