# Installation Scripts Documentation

This directory contains improved installation scripts for the mt_dao project development environment.

## Scripts Overview

### `install_env.sh` - General Environment Setup
A comprehensive installation script for setting up the mt_dao development environment on standard Linux systems.

**Features:**
- ✨ Comprehensive documentation and help system
- 🔧 Modular function-based architecture
- 🛡️ Robust error handling with `set -euo pipefail`
- 📝 Detailed logging with informational messages
- 🎯 CUDA version validation (≥ 12.4)
- ⚡ Flash-attention automatic installation
- 🔄 Environment synchronization with UV
- 📊 Installation completion summary

**Usage:**
```bash
# Standard installation
./scripts/install_env.sh

# Custom project path
./scripts/install_env.sh -p /custom/path/to/project

# Skip CUDA/GPU setup
./scripts/install_env.sh no_cuda

# Show help
./scripts/install_env.sh --help
```

### `install_hpc_env.sh` - HPC Environment Setup
Specialized installation script for High Performance Computing (HPC) environments with module systems.

**Features:**
- 🏛️ HPC module system management
- 🎯 CUDA 12.1 and cuDNN 8.9 specific setup
- 🐍 Python 3.10.13 validation
- ⚡ Flash-attention 2.3.2 installation
- 📊 Comprehensive environment validation
- 🔧 HPC-specific configurations
- 📝 Detailed progress logging

**Usage:**
```bash
# Standard HPC installation
./scripts/install_hpc_env.sh

# Custom project path
./scripts/install_hpc_env.sh -p /custom/path/to/project

# Show help
./scripts/install_hpc_env.sh --help
```

## Key Improvements

### 1. **Documentation & User Experience**
- Comprehensive header documentation with purpose, usage, and examples
- Professional help system with `--help` option
- Clear error messages and warnings
- Installation progress tracking with visual indicators (✓, ✅)

### 2. **Code Quality & Maintainability**
- Modular function-based architecture
- Consistent coding style and formatting
- Comprehensive comments and inline documentation
- Shellcheck compliance improvements
- Error handling with `set -euo pipefail`

### 3. **Robustness & Reliability**
- Input validation and error checking
- Graceful handling of missing dependencies
- Path validation and safety checks
- Comprehensive system validation
- Proper exit codes and error reporting

### 4. **Logging & Observability**
- Structured logging functions (`log_info`, `log_error`, `log_warn`)
- Consistent message formatting
- Installation progress tracking
- Comprehensive completion summaries

### 5. **Configuration Management**
- Constants defined at the top for easy modification
- Environment-specific configurations
- Flexible path handling
- Version requirements clearly specified

## Testing

The scripts include comprehensive test coverage:

```bash
# Run all tests
uv run python -m pytest mt_dao/tests/test_install_scripts.py -v

# Test specific functionality
uv run python -m pytest mt_dao/tests/test_install_scripts.py::TestInstallationScripts::test_help_option -v
```

**Test Coverage:**
- ✅ Bash syntax validation
- ✅ Shellcheck linting (if available)
- ✅ Help option functionality
- ✅ Invalid option handling
- ✅ Documentation requirements
- ✅ Logging function definitions

## Requirements

### For `install_env.sh`:
- Linux system with bash
- UV package manager
- CUDA ≥ 12.4 (for GPU support)
- Git with LFS support
- Internet connection for package downloads

### For `install_hpc_env.sh`:
- HPC system with module support
- CUDA 12.1 module available
- Python 3.10.13
- Singularity/Apptainer support
- UV package manager

## Environment Variables

Both scripts configure the following environment variables:

- `TRITON_CACHE_DIR`: User-specific Triton cache directory
- `RAY_TEMP_DIR`: Ray temporary directory (install_env.sh only)
- `PYTHONWARNINGS`: Python warning filters for HPC environments (install_hpc_env.sh only)

## Troubleshooting

### Common Issues

1. **CUDA Not Found**: Ensure CUDA is installed in standard paths or available as modules
2. **Permission Issues**: Check write permissions for project directory and cache directories
3. **UV Not Available**: Install UV package manager using the official installer
4. **Flash-attention Compilation**: Ensure sufficient disk space and compilation tools

### Debug Mode

For additional debugging information, you can run the scripts with bash debugging:

```bash
bash -x scripts/install_env.sh
```

## Contributing

When modifying the installation scripts:

1. Follow the established function-based architecture
2. Add comprehensive documentation for new features
3. Update test coverage for new functionality
4. Validate with shellcheck and bash syntax checking
5. Test on both standard and HPC environments

## Version History

- **v1.0**: Complete refactoring with improved documentation, error handling, and modular architecture
- **v0.x**: Original scripts with basic functionality
