Installation & Usage Questions

[kolkov]

Getting started with racedetector? Having issues? Ask here and we'll help!

Before Asking

Please check these resources first:

• 📖 Installation Guide
• 📖 Usage Guide
• 🎯 Examples
• 📦 Release Notes

Still stuck? Ask below!

---

Common Questions

Installation

Q: How do I install racedetector?

go install github.com/kolkov/racedetector/cmd/racedetector@v0.1.0

Q: What Go version do I need?

• Minimum: Go 1.21
• Recommended: Go 1.25 with GOEXPERIMENT=jsonv2

Q: Does it work on Windows/macOS?
Yes! Fully cross-platform (Linux, macOS, Windows).

---

Usage

Q: How do I use it instead of go build -race?

# Instead of: CGO_ENABLED=0 go build -race main.go
# Use:
racedetector build -o myapp main.go

Q: Can I use it with go test -race?
Not directly in v0.1.0. You need to build your tests first:

racedetector build -o myapp.test .
./myapp.test

Direct go test integration is planned for a future version.

Q: Does it work with Go modules?
Yes, fully compatible with Go modules.

Q: Can I use it in CI/CD?
Yes! Example GitHub Actions workflow:

- name: Install racedetector
  run: go install github.com/kolkov/racedetector/cmd/racedetector@v0.1.0

- name: Build with race detection
  run: racedetector build -o app ./cmd/app

- name: Run tests
  run: ./app --test

---

Troubleshooting

Q: I'm getting "undefined: race.Read" errors
Make sure you're using racedetector build, not regular go build. The race detector runtime is injected during instrumentation.

Q: Performance is very slow (>20x overhead)
This can happen with:

• Very large number of goroutines (1000+)
• High-frequency memory access patterns
• Nested synchronization

Share your details in Performance Discussion and we'll investigate.

Q: I'm seeing a panic/crash
Please create an Issue with:

• Go version: go version
• OS: Linux/macOS/Windows
• Command used
• Full error output
• Minimal reproduction code if possible

---

Advanced

Q: How do I instrument specific packages only?
v0.1.0 instruments all your code. Selective instrumentation is planned for v0.2.0.

Q: Can I use this with vendor dependencies?
Yes, but vendored dependencies won't be instrumented. Only your code and standard library calls are tracked.

Q: Does it detect races in CGO code?
No - this is a Pure-Go implementation. CGO code is opaque to the detector.

---

Ask Your Question

Please include:

• Go version: go version
• OS: Linux / macOS / Windows
• What you tried
• Error message (if any)
• Minimal code example (if relevant)

The more details you provide, the faster we can help!

---

Found a bug? → Create an Issue
Want to request a feature? → See Roadmap Discussion
Have performance data? → Share in Show and Tell