Development Setup

Set up your development environment for LibXMTP

This guide will help you set up your development environment for contributing to LibXMTP.

Prerequisites

Before you begin, ensure you have the following tools installed:

1. Install Rust

   Install Rustup, the Rust toolchain installer:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
2. Install Docker

   Install Docker Desktop to run the XMTP node and other services.

   After installation, make sure Docker Desktop is running.

3. Install Foundry

   Install Foundry for Ethereum development tools:

   curl -L https://foundry.paradigm.xyz | bash
   foundryup
   

Environment Setup Options

You can set up your development environment using one of three methods:

Method 1: Standard Setup

Start Docker Desktop, then install dependencies and start background services:

dev/up

This command:

• Installs required dependencies
• Creates and runs an XMTP node in Docker Desktop
• Sets up other necessary services

Method 2: Nix Setup (Recommended)

LibXMTP supports Determinate Nix for reproducible development environments with pinned toolchains for Rust, Android, iOS, WebAssembly, and Node.js.

1. One-time setup

   Install Determinate Nix, direnv, and binary caches:

   ./dev/nix-up
   
2. Enter dev shell

   nix develop
   

To temporarily disable/enable direnv:

dev/direnv-down  # Disable direnv auto-activation
dev/direnv-up    # Re-enable direnv

For more details, see the Nix setup documentation.

Method 3: Dev Containers

For containerized development using Visual Studio Code:

1. Install the Dev Containers extension
2. Open the command palette and select “Reopen in Container”
3. Select the Dockerfile as the target

Or build the container manually:

docker build . -t libxmtp:1

Managing Dependencies

When adding Rust dependencies, you must regenerate the workspace-hack crate:

nix develop --command cargo hakari generate

Optionally verify correctness:

nix develop --command cargo hakari verify

Managing Backend Services

Start Services

Standard

dev/up

Stop Services

Docker Only

dev/docker/down

Using Just Command Runner

LibXMTP uses just as a command runner for common development tasks.

List all available commands:

just

This will show all available recipes, including submodules for Android, iOS, Node.js, and WASM.

Next Steps

Now that your environment is set up:

• Learn about Testing
• Explore Benchmarks
• Read the Contributing Guidelines