Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
69 lines (50 loc) · 2.47 KB

CONTRIBUTING.md

File metadata and controls

69 lines (50 loc) · 2.47 KB
Raw

Contributing to AppleTrace

Thanks for your interest in improving AppleTrace! This guide covers how to get set up, what we expect from changes, and how to validate them.

Getting Started

git clone https://github.com/everettjf/appletrace.git
cd AppleTrace
python3 -m pip install -r requirements.txt

You will need Xcode 12+ (macOS 10.15+) to build the framework and samples, and a recent Python 3 for the tooling and tests.

Project Layout

  • appletrace/ — core tracing framework (Objective-C/C++ runtime, public headers).
  • appletrace/appletrace/src/objc/hook_objc_msgSend.m — arm64/arm64e objc_msgSend hook.
  • loader/, springboard/ — loader/packaging projects.
  • merge.py, scripts/appletrace_cli.py, go.sh — tooling (merge + open in Perfetto).
  • tests/ — Python regression tests.

See AGENT.md for a deeper map and build/release details, and ROADMAP.md for where the project is headed.

Making Changes

  • Keep changes scoped: don't mix instrumentation, tooling, and docs in one PR.
  • The objc_msgSend hook targets arm64 and arm64e. Preserve the authenticated GOT signing and PAC/BTI wrapper behavior, and run the arm64e device smoke test after changing the hook.
  • Avoid adding work to the tracing hot path; prefer caching/interning and per-thread state over per-event allocation.
  • Update README.md / README_CN.md / AGENT.md when workflows or APIs change.

Testing

# Python tooling
python3 -m pytest tests

# objc_msgSend hook smoke tests (run on a Mac)
./scripts/test_objc_msgsend_hook.sh
./scripts/test_objc_msgsend_hook_experimental.sh

# Real-device PAC validation (text + binary trace modes)
DEVICE_ARCH=arm64e ./scripts/test_objc_msgsend_hook_device.sh

# Verify the merge + export pipeline on real data
python3 merge.py -d <path-to-appletracedata>

When touching the framework, build the relevant Xcode targets and confirm a trace renders correctly in Perfetto.

Code Style

Pull Requests

  1. Fork and create a feature branch.
  2. Make your change with tests where applicable.
  3. Run the test commands above and note any manual testing (device, iOS version).
  4. Open a PR describing the change and its motivation.