Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
212 lines (138 loc) · 7.47 KB

CONTRIBUTING.md

File metadata and controls

212 lines (138 loc) · 7.47 KB
Raw

Contributing

Join the #mesh-llm channel on the Goose Discord for discussion and questions.

This file covers local build and development workflows for this repository.

Prerequisites

  • just
  • cmake
  • Rust toolchain (cargo)
  • Node.js 24 + npm (for UI development)

macOS: Apple Silicon. Metal is used automatically.

Linux NVIDIA: x86_64 with an NVIDIA GPU. Requires the CUDA toolkit (nvcc in your PATH). On Arch Linux, CUDA is typically at /opt/cuda; on Ubuntu/Debian it's at /usr/local/cuda. Auto-detection finds the right SM architecture for your GPU.

Linux AMD: ROCm/HIP is supported when ROCm is installed. Typical installs expose hipcc, hipconfig, and rocm-smi under /opt/rocm/bin.

Linux Vulkan: Vulkan is supported when the Vulkan development files and glslc are installed. On Ubuntu/Debian, install libvulkan-dev glslc. On Arch Linux, install vulkan-headers shaderc.

Windows: just build auto-detects cuda, hip/rocm, vulkan, or cpu. You can override with just build backend=cuda (or rocm, vulkan, cpu). Metal is not supported on Windows.

Build from source

Build everything (llama.cpp fork, mesh binary, and UI production build):

just build

On Linux, just build auto-detects CUDA vs ROCm vs Vulkan. For NVIDIA, make sure nvcc is in your PATH first:

# Arch Linux
PATH=/opt/cuda/bin:$PATH just build

# Ubuntu/Debian
PATH=/usr/local/cuda/bin:$PATH just build

For NVIDIA builds, the script auto-detects your GPU's CUDA architecture. To override:

just build cuda_arch=90   # e.g. H100

For AMD ROCm builds, you can force the backend explicitly:

just build backend=rocm

To override the AMD GPU target list:

just build backend=rocm rocm_arch="gfx90a;gfx942;gfx1100"

For Vulkan builds, force the backend explicitly:

just build backend=vulkan

For CPU-only builds (no GPU acceleration):

just build backend=cpu

On Windows, you can override the detected backend if needed:

just build backend=vulkan
just build backend=cpu
just build backend=cuda cuda_arch=90

Windows release bundles use dedicated Windows release recipes:

just release-build-cuda-windows
just release-bundle-cuda-windows v0.X.0

GitHub Actions uses hosted windows-2022 runners for compile-only Windows CI and release packaging. The workflow installs CUDA, HIP SDK, and Vulkan SDK on demand before invoking the same just recipes.

Create a portable bundle:

just bundle

UI development workflow

Use this two-terminal flow for UI development.

Terminal A (run mesh-llm yourself):

mesh-llm --port 9337 --console 3131

If mesh-llm is not on your PATH:

./target/release/mesh-llm --port 9337 --console 3131

Terminal B (run Vite with HMR):

just ui-dev

Open:

http://127.0.0.1:5173

ui-dev defaults:

  • Serves on 127.0.0.1:5173
  • Proxies /api/* to http://127.0.0.1:3131

Overrides:

# Different backend API origin for /api proxy
just ui-dev http://127.0.0.1:4141

# Different Vite dev port
just ui-dev http://127.0.0.1:3131 5174

Useful commands

just stop             # stop mesh/rpc/llama processes
just test             # quick test against :9337
just compat-smoke ~/.cache/huggingface/hub/<model>.gguf   # optional 2-node + 1-client Python/Node/LiteLLM smoke
just --list           # list all recipes

CI / GitHub Actions

CI uses dorny/paths-filter to skip jobs when unchanged areas of the repo are modified. A changes detection job runs first on every push and PR, then each build job gates on its output.

What triggers what

Changed paths linux / macos linux_cuda / linux_rocm / linux_vulkan / windows
mesh-llm/src/**, Cargo.*, Justfile, scripts/**, mesh-llm/build.rs, mesh-llm/plugin/**, mesh-llm/tests/**, mesh-llm/proto/** ✅ runs ✅ runs
mesh-llm/ui/** ✅ runs ⏭ skipped
**/*.md, docs/**, anything else ⏭ skipped ⏭ skipped
Manual workflow_dispatch ✅ runs ✅ runs

Verifying path filtering works

To confirm builds are skipped on a docs-only change, open a PR and push a commit that touches only a .md file (e.g. add a blank line to README.md). All build jobs should appear as Skipped in the Actions tab — only the changes job runs.

To confirm UI-only changes skip the GPU backend jobs, push a commit touching only mesh-llm/ui/**. The linux and macos jobs run; linux_cuda, linux_rocm, linux_vulkan, and windows are skipped.

Adding new paths

If you add a new Rust crate, build script, or test directory, add its path to the rust filter in .github/workflows/ci.yml under the changes job so it correctly triggers the build matrix.

Benchmark Binaries

Memory bandwidth benchmark source files live in benchmarks/. These are optional — they are not compiled by just build. Each target platform requires its own toolchain.

Building

just benchmark-build-apple    # macOS Apple Silicon — requires swiftc (ships with Xcode)
just benchmark-build-cuda     # NVIDIA GPU — requires CUDA toolkit (nvcc)
just benchmark-build-hip      # AMD GPU — requires ROCm (hipcc)
just benchmark-build-intel    # Intel Arc GPU — requires Intel oneAPI (icpx) — UNVALIDATED

On Windows, use the dedicated recipes:

just benchmark-build-cuda-windows
just benchmark-build-hip-windows
just benchmark-build-intel-windows

These produce .exe binaries next to mesh-llm.exe.

AMD note: The AMD benchmark (benchmarks/membench-fingerprint.hip) has not been tested on real AMD hardware. The recipe is provided for reference only.

Intel Arc note: The Intel Arc benchmark (benchmarks/membench-fingerprint-intel.cpp) has not been tested on real Intel Arc hardware. The recipe is provided for reference only.

Output location

All recipes output to mesh-llm/target/release/, the same directory as the mesh-llm binary. The detect_bin_dir() function in mesh-llm probes that directory at runtime, so benchmark binaries are discovered automatically.

Including in release bundles (Apple Silicon)

The just bundle recipe automatically includes membench-fingerprint if it has been built:

just benchmark-build-apple && just bundle

If the binary is not present, just bundle prints a note and continues without it — the bundle is still valid.

CUDA, HIP, and Intel binaries are not included in the Unix tarball bundle; they must be compiled on the target platform. On Windows release packaging, any membench-fingerprint*.exe binaries present in mesh-llm/target/release/ are included automatically in the generated .zip.