solana-ledger-tool-requirement-setup.md

Solana Development Environment Setup Guide

This guide documents the exact toolchain versions and setup steps to work with the solana-ledger-tool v1.18.26 , including all common errors and their solutions.

Required Toolchain Versions

• Rust: 1.79.0 (can also be pinned via rust-toolchain.toml)
• Solana CLI: 1.18.26
• Anchor CLI: 0.29.0
• Anchor Lang: 0.29.0

Installation Steps

1. Install Rustup (Rust Toolchain Manager)

If you don't have Rustup installed:

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

Follow the prompts and restart your terminal.

2. Install Rust 1.79.0

Install the specific Rust version we need:

rustup install 1.79.0

Important: Don't set this as your global default if you use other Rust projects. The project's rust-toolchain.toml file will automatically use Rust 1.79.0 when you're in this directory.

If you want to set it as default anyway:

rustup default 1.79.0

Verify installation:

rustc --version
# Should show: rustc 1.79.0

3. Install Solana CLI 1.18.26

Install the specific Solana version:

sh -c "$(curl -sSfL https://release.solana.com/v1.18.26/install)"

Add Solana to your PATH (the installer will show you the exact command, but it's typically):

export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"

Add this to your ~/.zshrc to make it permanent:

echo 'export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify installation:

solana --version
# Should show: solana-cli 1.18.26 (src:d9f20e95; feat:3241752014, client:SolanaLabs)

solana-test-validator --version
# Should show: solana-test-validator 1.18.26

4. Install Anchor CLI 0.29.0

Note: You need to temporarily switch to stable Rust to install Anchor CLI (it requires Rust 1.82+), then switch back to 1.79.0 for building the project.

# Switch to stable Rust temporarily
rustup override set stable

# Install Anchor CLI 0.29.0
cargo install --git https://github.com/coral-xyz/anchor --tag v0.29.0 anchor-cli --locked --force

# Switch back to 1.79.0 for the project
rustup override set 1.79.0

Verify installation:

anchor --version
# Should show: anchor-cli 0.29.0

5. macOS-Specific Configuration (Prevent AppleDouble Files)

macOS automatically creates hidden metadata files (called AppleDouble files, starting with ._) when archiving or copying files. These files cause the Solana test validator to fail when unpacking its genesis archive (see Error 5 below for details).

To prevent this system-wide, add the COPYFILE_DISABLE environment variable to your shell:

echo 'export COPYFILE_DISABLE=1' >> ~/.zshrc
source ~/.zshrc

This tells macOS tools like tar to stop creating these ._ metadata files.

Common Errors and Solutions

Error 1: Cargo Lockfile Version 4

Error Message:

error: failed to parse lock file at: Cargo.lock
Caused by: lock file version 4 requires `-Znext-lockfile-bump`

Cause: Using Rust nightly (1.93.0+) which generates lockfile v4, incompatible with Solana's Rust 1.75.0 toolchain.

Solution:

1. Pin Rust to 1.79.0 (already done via rust-toolchain.toml)
2. Delete and regenerate lockfile:

   rm Cargo.lock
   cargo build

Error 2: IDL Doesn't Exist

Error Message:

Error: IDL doesn't exist

Cause: Version mismatch between anchor-cli (0.30.1) and anchor-lang (0.29.0).

Solution: Install matching Anchor CLI version:

cargo install --git https://github.com/coral-xyz/anchor --tag v0.29.0 anchor-cli --locked --force

Error 3: Rayon MSRV Error

Error Message:

error: rustc 1.79.0 is not supported by the following packages:
  [email protected] requires rustc 1.80

Cause: Newer rayon versions require Rust 1.80+.

Solution: Downgrade rayon dependencies:

cargo update -p rayon --precise 1.10.0
cargo update -p rayon-core --precise 1.12.1

Error 4: IndexMap MSRV Error

Error Message:

error: package `indexmap v2.12.1` cannot be built because it requires rustc 1.82 or newer

Cause: Newer dependencies pulled by borsh 1.5.7 require Rust 1.82+.

Solution: Downgrade transitive dependencies:

cargo update -p proc-macro-crate:3.4.0 --precise 3.1.0
cargo update -p indexmap --precise 2.2.6

Error 5: Solana Test Validator Genesis Error (macOS)

Error Message:

Error: failed to start validator: Failed to create ledger at test-ledger: 
io error: Error checking to unpack genesis archive: Archive error: 
extra entry found: "._genesis.bin" Regular

Cause: macOS creates hidden metadata files (._*) that confuse the validator's genesis unpacker.

Temporary Solution:

COPYFILE_DISABLE=1 solana-test-validator

Permanent Solution: Add to ~/.zshrc:

echo 'export COPYFILE_DISABLE=1' >> ~/.zshrc
source ~/.zshrc

Then you can run normally:

solana-test-validator

If the ledger is already corrupted:

rm -rf test-ledger
solana-test-validator

Building the Project

After setup, build with:

anchor build

The compiled program will be at target/deploy/compute_unit.so.

Running the Test Validator

solana-test-validator

Or with a custom ledger location:

solana-test-validator --ledger my-ledger

Troubleshooting Tips

1. Always check versions first:

   rustc --version
   solana --version
   anchor --version

2. If you see dependency errors, check if they're MSRV-related and downgrade as needed.

3. For macOS users, always ensure COPYFILE_DISABLE=1 is set in your environment.

4. Clean build if needed:

   anchor clean
   rm -rf target
   anchor build