Mac compile script based on v0.6.2

[SuhasSrinivasan]

0. Added help markdown to book/src
1. Installs Xcode Command Line Tools
2. Installs Homebrew package manager
3. Considers uv and pyenv through config
4. Installs rustup (Rust toolchain installer)
5. Installs Rust compiler (rustc) and Cargo build tool
6. Clones the modkit GitHub repository
7. Checks out the latest release version
8. Creates a Python virtual environment
9. Installs PyTorch in the virtual environment
10. Sets and verifies environment variables for libtorch
11. Builds modkit with macOS GPU (MPS) support

[Copilot]

Pull request overview

This PR adds a macOS-focused installation path for building modkit from source with the tch/PyTorch-backed open-chromatin stack, plus companion documentation in the mdBook docs. It fits into the existing repository by extending the current build-note/docs story with a scripted Apple/macOS workflow.

Changes:

• Adds a new mac_compile_modkit.sh installer that sets up toolchains, clones the repo, prepares Python/PyTorch, and builds modkit.
• Adds configurable Python selection via system Python, pyenv, or uv.
• Adds a new mdBook page describing the macOS installation workflow and troubleshooting steps.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 12 comments.

File	Description
mac_compile_modkit.sh	New end-to-end macOS build/install script for compiling modkit with PyTorch/libtorch-based support.
book/src/mac_compile_modkit.md	New user-facing documentation for the macOS installation workflow and common troubleshooting steps.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[SuhasSrinivasan]

Tested on Sunday, May 3, 2026 at 7:30PM PDT
macOS: 26.4.1
M2 Ultra Mac Studio

$ bash mac_compile_modkit.sh ~/projects/modkit/modkit-0.6.2 v0.6.2
.
.
.
   Compiling modkit v0.6.1 (/Users/suhas/projects/modkit/modkit-0.6.2/modkit/modkit)
    Finished `release` profile [optimized] target(s) in 1m 45s
✓ Modkit compiled successfully!
✓ Binary created at: /Users/suhas/projects/modkit/modkit-0.6.2/modkit/target/release/modkit
  Binary size:  21M

Testing modkit binary...
modkit 0.6.1
✓ Modkit is working correctly!

Available modkit commands:
Installation information saved to: /Users/suhas/projects/modkit/modkit-0.6.2/installation_info.txt
✓ Added modkit environment setup to ~/.zprofile
  It will activate automatically in every new terminal session.

Total installation time: 2 minutes 39 seconds

Versioning issue noted in #614

[ArtRand]

Could you change this to say that these steps (installing pytorch, having a python provider, etc) are only required if you want to use the open-chromatin model in Modkit? For all of the other functionality I don't think the user needs to worry about python at all.

[ArtRand]

Could you mention that python isn't really used by Modkit and that it's only required to get the correct version of torchlib on the Mac machine? It's up to you, but you may consider having a toggle in the script that makes a "no features" version of Modkit and skips the python parts all together.

[ArtRand]

Hello @SuhasSrinivasan,

I really appreciate this contribution. My only concern is that a new user to Modkit may read this and think that they need python and pytorch to use Modkit at all. You and I both know this isn't true and that the only subcommand which optionally uses torchlib is open-chromatin. I imagine that nearly all users getting started won't need to worry about that to get started.

Basically, it's entirely a matter of appearance, I'd like the "compile from source" for any OS to still be the same basic two steps: (1) install cargo, (2) use cargo to compile Modkit. I appreciate that your script will build an optimized version of Modkit, but I think it's just a little more advanced than what is absolutely necessary to get started.

I mentioned this in the comments, and it's up to you, but you may consider making the --features tch build optional so that all of the python parts are also optional. I know for me personally, once I see that I have to deal with python providers I immediately expect more headache than a vanilla cargo project.

[ArtRand]

I don't think that git comes installed on a "fresh" Mac, so maybe this step isn't necessary? I appreciate that this script is supposed to be a "dot-slash" style script that handles everything but what is the user story around getting to the start line here? Does someone clone the repo from GitHub by downloading the source, wget-ting the script? Maybe add those details to the documentation you've added (👍 on that by the way).

[ArtRand]

As of Modkit v0.6.2 rayon isn't used in pileup at all but I suppose this doesn't hurt anything. Could you add a comment that you should still use the --threads argument?