shdrlib 0.1.0

# Installation Guide


Get shdrlib set up on your system.

## Prerequisites


### 1. Rust Installation


shdrlib requires Rust 1.82+ (Edition 2024).

**Install Rust:**
```bash
# Using rustup (recommended)

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

# Or on Windows

# Download from https://rustup.rs/

```

**Verify installation:**
```bash
rustc --version
# Should show: rustc 1.82.0 or higher

```

**Update Rust if needed:**
```bash
rustup update stable
```

### 2. Vulkan SDK


shdrlib requires Vulkan 1.3+ runtime.

#### Windows

1. Download [Vulkan SDK](https://vulkan.lunarg.com/)
2. Install with default options
3. SDK installs both runtime and validation layers

#### Linux

```bash
# Ubuntu/Debian

sudo apt install vulkan-tools libvulkan-dev vulkan-validationlayers

# Fedora

sudo dnf install vulkan-tools vulkan-loader-devel vulkan-validation-layers

# Arch

sudo pacman -S vulkan-tools vulkan-headers vulkan-validation-layers
```

#### macOS

```bash
# Install via Homebrew

brew install --cask vulkan-sdk

# Or download from https://vulkan.lunarg.com/

```

**Verify Vulkan:**
```bash
vulkaninfo | head -n 20
# Should show Vulkan 1.3 or higher
```

### 3. Graphics Driver


Make sure you have up-to-date graphics drivers:

- **NVIDIA:** GeForce Experience or direct download
- **AMD:** Radeon Software
- **Intel:** Intel Graphics Driver

**Verify support:**
```bash
vkcube
# Should display a rotating cube

```

---

## Install shdrlib


### Using Cargo


Add to your `Cargo.toml`:

```toml
[dependencies]
shdrlib = "0.1"
ash = "0.38"  # For Vulkan types like vk::Format
```

**Install from crates.io:**
```bash
cargo add shdrlib ash
```

### Using Git (Development Version)


```toml
[dependencies]
shdrlib = { git = "https://github.com/paulburnettjones-wq/shdrlib" }
ash = "0.38"
```

---

## Verify Installation


### 1. Create Test Project


```bash
cargo new --bin test_shdrlib
cd test_shdrlib
cargo add shdrlib ash
```

### 2. Add Test Code


Edit `src/main.rs`:

```rust
use shdrlib::ez::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Creating EzRenderer...");
    let renderer = EzRenderer::new()?;
    println!("✅ shdrlib is working!");
    Ok(())
}
```

### 3. Run Test


```bash
cargo run
```

**Expected output:**
```
Creating EzRenderer...
✅ shdrlib is working!
```

---

## Troubleshooting


### "Vulkan loader not found"


**Cause:** Vulkan SDK not installed or not in PATH

**Fix:**
- Install Vulkan SDK (see prerequisites)
- On Linux, install `libvulkan1` or `vulkan-loader`
- Restart terminal after installation

### "No suitable device found"


**Cause:** Your GPU doesn't support Vulkan 1.3, or drivers are outdated

**Fix:**
- Update graphics drivers
- Run `vulkaninfo` to check supported version
- Try integrated GPU if available

### "Validation layers not found"


**Cause:** Validation layers not installed (debug builds only)

**Fix:**
- Install Vulkan SDK (includes validation layers)
- On Linux: `sudo apt install vulkan-validationlayers`
- Or build with `--release` to skip validation

### Compile errors about Edition 2024


**Cause:** Rust version too old

**Fix:**
```bash
rustup update stable
rustc --version  # Should be 1.82+
```

### "Cannot find crate `ash`"


**Cause:** Missing dependency

**Fix:**
```bash
cargo add ash
```

---

## Optional: Development Tools


### IDE Support


**Visual Studio Code:**
```bash
# Install rust-analyzer extension

code --install-extension rust-lang.rust-analyzer
```

**Other IDEs:**
- IntelliJ IDEA: Rust plugin
- Vim/Neovim: rust-analyzer + coc.nvim or native LSP
- Emacs: rust-analyzer + lsp-mode

### Vulkan Development Tools


**RenderDoc** (Graphics debugger):
```bash
# Download from https://renderdoc.org/

```

**Vulkan Configurator** (Validation layer control):
- Included with Vulkan SDK
- Configure validation in detail
- Profile and debug features

---

## Next Steps


✅ You've installed shdrlib!

**Now:**
1. Read the **[Quick Start Guide](../../QUICKSTART.md)**
2. Try the **[First Triangle Tutorial](quickstart.md)**
3. Explore **[Examples](../../demos/)**

---

## Platform-Specific Notes


### Windows

- ✅ Works on Windows 10/11
- ✅ Both MSVC and GNU toolchains supported
- ✅ Integrated and discrete GPUs supported

### Linux

- ✅ X11 and Wayland supported
- ✅ Works with Mesa drivers (Intel, AMD)
- ✅ Works with proprietary NVIDIA drivers
- ⚠️ May need `VK_ICD_FILENAMES` environment variable for some setups

### macOS

- ✅ Works via MoltenVK (Vulkan on Metal)
- ✅ macOS 10.15+ recommended
- ⚠️ Some Vulkan features may be limited on Metal
- ⚠️ Validation layers may have reduced functionality

---

## System Requirements


### Minimum

- **CPU:** Any 64-bit processor
- **RAM:** 4 GB
- **GPU:** Vulkan 1.3 support
- **OS:** Windows 10, Linux (kernel 4.4+), macOS 10.15+

### Recommended

- **CPU:** Modern multi-core processor
- **RAM:** 8 GB+
- **GPU:** Dedicated GPU with Vulkan 1.3
- **OS:** Windows 11, Recent Linux, macOS 12+

---

**Having issues?** Check the **[Troubleshooting Guide](troubleshooting.md)** or **[FAQ](faq.md)**.