This guide covers how to install the Misting library and set up your development environment.

System Requirements

Rust Toolchain

Misting requires Rust nightly with the 2024 edition. The project uses a rust-toolchain.toml file to ensure consistent toolchain versions.

Minimum Requirements:

  • Rust nightly (automatically selected via rust-toolchain.toml)
  • Cargo (included with Rust)

Note: The nightly requirement is temporary. The project plans to move to stable Rust when the features in use are incorporated into the stable edition (expected in Mistcraft 0.2).

Operating System Support

Misting is developed and tested on:

  • Linux (primary development platform)
  • macOS
  • Windows

The library uses platform-agnostic Rust code and should work on any platform that Rust supports.

Additional Dependencies

Misting has minimal external dependencies. All required libraries are managed through Cargo and will be installed automatically during the build process.

Optional Runtime Dependencies:

  • PostgreSQL - Required only if using the PostgreSQL state provider (misting-postgres-state-provider crate)

Installing Rust

If you do not have Rust installed, follow these steps:

Install Rust using rustup, the official Rust toolchain installer:

Linux and macOS:

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

Windows:

Download and run the rustup-init.exe installer.

After installation, restart your terminal and verify the installation:

rustc --version
cargo --version

Installing Misting

From Source (Currently Required)

Misting is not yet published to crates.io. To use Misting, you must build from source or reference the Git repository directly.

Clone the repository:

git clone https://github.com/mistcraft/mistcraft.git
cd mistcraft

The project includes a rust-toolchain.toml file that automatically selects the correct nightly toolchain. Rustup will download and install the required toolchain version on first build.

Build the library:

cargo build -p misting

Run tests to verify the build:

cargo test -p misting

Adding Misting to Your Project

Since Misting is not on crates.io, add it as a Git dependency in your Cargo.toml:

[dependencies]
misting = { git = "https://github.com/mistcraft/mistcraft.git" }

To pin to a specific commit or branch:

[dependencies]
# Pin to a specific branch
misting = { git = "https://github.com/mistcraft/mistcraft.git", branch = "main" }

# Or pin to a specific commit
misting = { git = "https://github.com/mistcraft/mistcraft.git", rev = "abc1234" }

Important: Your project must also use Rust nightly with the 2024 edition. Create a rust-toolchain.toml in your project root:

[toolchain]
channel = "nightly"

And set the edition in your Cargo.toml:

[package]
edition = "2024"

Cargo Features

Misting provides the following Cargo features:

FeatureDefaultDescription
runtime-tokioYesEnables Tokio async runtime support
concrete-resourceYesEnables typed resource definitions

To disable default features:

[dependencies]
misting = { git = "https://github.com/mistcraft/mistcraft.git", default-features = false }

Verifying Installation

Create a simple program to verify that Misting is installed correctly.

Create a new project:

cargo new misting-test
cd misting-test

Add the rust-toolchain.toml file:

[toolchain]
channel = "nightly"

Update Cargo.toml:

[package]
name = "misting-test"
version = "0.1.0"
edition = "2024"

[dependencies]
misting = { git = "https://github.com/mistcraft/mistcraft.git" }
tokio = { version = "1", features = ["rt", "macros"] }

Update src/main.rs:

use misting::state::{MemoryStorageBackend, StateProvider};

#[tokio::main]
async fn main() {
    // Create an in-memory state provider
    let backend = MemoryStorageBackend::new();
    let state_provider = StateProvider::new(backend);

    println!("Misting is installed and working!");
    println!("State provider created successfully.");
}

Build and run:

cargo run

If you see the success message, Misting is installed correctly.

Development Environment Setup

When building applications with Misting, consider this project structure:

my-project/
├── Cargo.toml
├── rust-toolchain.toml
├── src/
│   ├── main.rs
│   └── resources/         # Your resource definitions
│       └── mod.rs
└── state/                 # Local state files (if using filesystem backend)
    └── .gitkeep

Development Tools

Install these tools for a better development experience:

Code formatting and linting:

# Format code
cargo fmt

# Run linter
cargo clippy --all-targets --all-features -- -D warnings

Dependency management:

# Security audit
cargo install cargo-audit
cargo audit

# Find unused dependencies
cargo install cargo-udeps
cargo +nightly udeps

# Check for outdated dependencies
cargo install cargo-outdated
cargo outdated

IDE Integration

rust-analyzer provides excellent IDE support for Rust and works with Misting projects.

VS Code:

  1. Install the rust-analyzer extension
  2. Open your project folder in VS Code
  3. rust-analyzer will automatically detect the project and provide:
    • Code completion
    • Go to definition
    • Type information on hover
    • Inline error diagnostics
    • Code actions and refactoring

Configuration for nightly:

rust-analyzer automatically respects the rust-toolchain.toml file. No additional configuration is needed.

If you encounter issues with nightly features, add this to your VS Code settings (.vscode/settings.json):

{
    "rust-analyzer.cargo.features": "all",
    "rust-analyzer.check.command": "clippy"
}

JetBrains IDEs (IntelliJ IDEA, CLion, RustRover)

  1. Install the Rust plugin
  2. Open your project
  3. The plugin will detect the toolchain from rust-toolchain.toml

Other Editors

Most editors with Rust support use rust-analyzer as the language server. Refer to your editor’s documentation for setup instructions.

Troubleshooting

Common Issues

”error: toolchain ‘nightly’ is not installed”

The project requires the nightly toolchain. Install it:

rustup install nightly

The rust-toolchain.toml file should automatically select nightly, but you can also set it manually:

rustup override set nightly

“edition = 2024 is not valid”

Ensure you are using a recent nightly toolchain. Update your toolchain:

rustup update nightly

Build errors with “feature X is not stable”

Misting uses nightly-only features. Ensure your project uses the nightly toolchain by creating a rust-toolchain.toml file in your project root:

[toolchain]
channel = "nightly"

Slow compilation times

Misting has several dependencies that may take time to compile on the first build. Subsequent builds will be faster due to caching.

To speed up development builds:

# Use faster linker (Linux)
sudo apt install lld
# Add to ~/.cargo/config.toml:
# [target.x86_64-unknown-linux-gnu]
# linker = "clang"
# rustflags = ["-C", "link-arg=-fuse-ld=lld"]

“cannot find crate misting”

Ensure the Git dependency is correctly specified in your Cargo.toml:

[dependencies]
misting = { git = "https://github.com/mistcraft/mistcraft.git" }

Then run:

cargo update
cargo build

PostgreSQL state provider errors

If using the PostgreSQL state provider, ensure:

  1. PostgreSQL is installed and running
  2. The misting-postgres-state-provider crate is added to your dependencies
  3. Connection credentials are correct
[dependencies]
misting = { git = "https://github.com/mistcraft/mistcraft.git" }
misting-postgres-state-provider = { git = "https://github.com/mistcraft/mistcraft.git" }

Getting Help

If you encounter issues not covered here:

  1. Check the GitHub Issues for known problems
  2. Start a discussion in GitHub Discussions
  3. Review the Contributing Guide for development setup details

Next Steps

Now that Misting is installed, continue with: