Development
Build

Build Guide

Comprehensive instructions for building MLGraph, including both the C++ core and the React UI.

Prerequisites

System Requirements

  • macOS: 15.0+ (for Metal support)
  • Linux: Ubuntu 20.04+ or equivalent
  • CMake: 3.20+
  • Node.js: 18+ and npm 9+

Compiler

  • macOS: Clang/Clang++ (NOT gcc/g++)
  • Linux: GCC 9+ or Clang 10+
  • Python: 3.8+ (for Python bindings)

Required Libraries

# macOS (using Homebrew)
brew install cmake protobuf grpc faiss nlohmann-json \
             yaml-cpp gtest benchmark libarchive curl \
             openssl argon2 libsodium zstd

# Linux (using vcpkg or apt)
# For FAISS: Check version compatibility (currently 1.11+)

Building the C++ Core

Important

Always build in the build/ directory, never in the project root!

# Create and enter build directory
mkdir -p build
cd build

# Configure with CMake
cmake .. -DBUILD_TESTS=ON \
         -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_CXX_COMPILER=/usr/bin/clang++ \
         -DCMAKE_C_COMPILER=/usr/bin/clang

# Build all targets (parallel build)
make -j8

# Build specific target
make mlgraphd -j8

CMake Parameters

ParameterDefaultDescription
BUILD_TESTSOFFBuild all test executables
BUILD_EXTENDED_TESTSOFFBuild extended tests (large datasets)
CMAKE_BUILD_TYPEReleaseDebug, Release, RelWithDebInfo
USE_TLSONEnable TLS support for gRPC

Build Targets

Main Executables

  • mlgraphd
  • centroid_server
  • distributed_centroid_server
  • client_example
  • benchmark_cli
  • status_cli
  • replica_cli

Libraries

  • libcore.a
  • libclient.a
  • libserver.a
  • libutilities.a

Building the React UI

# Navigate to UI directory
cd ui/mlgraph-ui
npm install

# Development Build (with hot reload)
npm run dev

# With Mock Service Worker (MSW) for API mocking
npm run dev -- --open "?mock=true"

# Production Build
npm run build

# Output will be in ui/mlgraph-ui/dist/

Platform-Specific Notes

macOS

  • Always use Clang/Clang++, NOT gcc/g++
  • For coverage: Use llvm-cov and llvm-profdata
  • Metal support requires macOS 15.0+

Linux

  • Can use GCC or Clang
  • For FAISS updates: Use vcpkg or build from source
  • Ensure all shared libs are in LD_LIBRARY_PATH

Troubleshooting

Build in wrong directory

Solution: Always use build/ directory

Missing dependencies

Solution: Check /usr/local first, install missing libs

Library not found at runtime

Solution: Set DYLD_LIBRARY_PATH (macOS) or LD_LIBRARY_PATH (Linux)

Clean Build

# Remove all build artifacts
rm -rf build/*
cd build
cmake ..
make -j8

# Verification
./mlgraphd --version
Next: Testing GuideBack to Quick Start