CONTRIBUTING.rst: Missing Apple Silicon setup instructions - `./configure --dev` fails on M1/M2/M3

[Sainava]

Description

Following the contributor setup instructions in CONTRIBUTING.rst fails on Apple Silicon (M1/M2/M3/M4) Macs with no documented workaround or warning. New contributors following the official guide encounter cryptic dependency errors with no guidance.

Current State:

• CONTRIBUTING.rst says to simply run ./configure --dev (line 137)
• This fails on Apple Silicon with: ERROR: No matching distribution found for extractcode-7z==16.5.210531
• No mention of Apple Silicon compatibility issues in contributor documentation

The Documentation Gap:

• Issue Many scancode dependencies are broken for Mac M1 #3205 documents that pip install doesn't work on Apple Silicon ✅
• Installation docs (install-scancode-using-pip.rst) correctly warn about this ✅
• But CONTRIBUTING.rst has zero mention of Apple Silicon ❌
• New contributors assume the documented setup will work (it doesn't)

Root Cause:
Native dependencies (extractcode-7z, pyahocorasick, intbitset) lack ARM64 wheels. The configure script has Rosetta detection logic (line 122-125) but doesn't account for ARM-native Homebrew Python being used, causing the x86_64 fallback to fail silently.

Suggested Fix:
Add a note in CONTRIBUTING.rst before step 5 (around line 127):

⚠️ Note for Apple Silicon (M1/M2/M3/M4) users:

Due to missing ARM64 wheels for native dependencies, you must use x86_64 Python under Rosetta:

# Install x86_64 Python via Rosetta
arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
arch -x86_64 /usr/local/bin/brew install python@3.12

# Tell configure to use it
echo "/usr/local/bin/python3.12" > PYTHON_EXECUTABLE
./configure --dev

See issue #3205 for more context on Apple Silicon compatibility.

Impact:
Blocks ALL new contributors on Apple Silicon Macs (increasingly common hardware in 2024-2025).

Link to Documentation Page

https://scancode-toolkit.readthedocs.io/en/stable/contribute/contrib_dev.html

Direct file: https://github.com/aboutcode-org/scancode-toolkit/blob/develop/CONTRIBUTING.rst (lines 128-142)

Select Category

• Inconsistency (between installation docs warning and contributor docs silence)
• General Improvement (add missing platform-specific instructions)
• New Section Request
• Typo/Mistakes
• Other

System Info

• macOS Sonoma on Apple M3
• Python 3.12 (ARM64 from Homebrew)
• Following CONTRIBUTING.rst exactly as documented

I'd Like to Help!

I've thoroughly investigated this issue and would be happy to submit a documentation PR to fix it.

Specifically, I propose:

File: CONTRIBUTING.rst
Location: Add a NOTE section between lines 127-134 (right before "Run this command to configure ScanCode")
Content: Add an Apple Silicon warning box with:

• Explanation of why standard setup fails (missing ARM64 wheels)
• Step-by-step instructions to install x86_64 Python via Rosetta
• How to use the PYTHON_EXECUTABLE file to specify Python version
• Link to issue Many scancode dependencies are broken for Mac M1 #3205 for additional context

This would:

• Warn contributors on Apple Silicon before they hit the error
• Provide a tested workaround (the same one I followed to investigate this)
• Maintain consistency with the existing NOTE format in the docs
• Save future contributors hours of frustration

Let me know if you'd like me to submit this PR! I can have it ready quickly since I understand the issue and solution.

[thedrishtigupta]

Hi, I was able to reproduce this issue on Apple Silicon and I believe a small documentation update in CONTRIBUTING.rst could address it.
I’d like to submit a PR adding an Apple Silicon note before the failing step. Please let me know if that works.