Build Guide

Prerequisites

macOS on Apple Silicon (M1, M2, M3, M4)
Go 1.25+
CMake 3.24+
Xcode Command Line Tools (for Metal framework)

Building mlx-c

The C library is built via go generate:

cd /path/to/go-mlx
go generate ./...

This runs CMake which:

Fetches mlx-c v0.4.1 from GitHub
Builds the shared libraries (libmlxc, libmlx)
Installs to dist/ (headers + libs)

CGO Configuration

Set automatically by directives in mlx.go:

#cgo CXXFLAGS: -std=c++17
#cgo CFLAGS: -mmacosx-version-min=26.0
#cgo CPPFLAGS: -I${SRCDIR}/dist/include
#cgo LDFLAGS: -L${SRCDIR}/dist/lib -lmlxc -lmlx
#cgo darwin LDFLAGS: -framework Foundation -framework Metal -framework Accelerate
#cgo darwin LDFLAGS: -Wl,-rpath,${SRCDIR}/dist/lib

Running Tests

# All tests (must be on Apple Silicon with mlx-c built)
go test ./...

# Specific test file
go test -run TestGrad ./...
go test -run TestLoRA ./...

Using in Another Module

// go.mod
require forge.lthn.ai/core/go-mlx v0.0.0

// For local development
replace forge.lthn.ai/core/go-mlx => /path/to/go-mlx

Model Format

Models must be in safetensors format (HuggingFace standard). NOT GGUF.

Example model paths:

/Volumes/Data/lem/safetensors/gemma-3/
/Volumes/Data/lem/safetensors/qwen3-8b/