Add comprehensive Build and Run guide

Complete documentation for building and running VideoTools: Sections: • Quick start (2-minute setup) • Making VideoTools permanent (bash/zsh setup) • Script documentation (what each does) • Build requirements and versions • Troubleshooting guide • Development workflow • DVD encoding complete workflow • Performance notes • Production deployment guide • Getting help and reporting issues Easy setup: source scripts/alias.sh VideoTools That's all users need to run the application!
2025-11-29 19:54:13 -05:00 · 2025-11-29 19:54:13 -05:00 · 0bd704d7dc
commit 0bd704d7dc
parent ce60508480
1 changed files with 374 additions and 0 deletions
--- a/BUILD_AND_RUN.md
+++ b/BUILD_AND_RUN.md
@ -0,0 +1,374 @@
+# VideoTools - Build and Run Guide
+
+## Quick Start (2 minutes)
+
+### Option 1: Using the Convenience Script (Recommended)
+
+```bash
+cd /home/stu/Projects/VideoTools
+source scripts/alias.sh
+VideoTools
+```
+
+This will:
+1. Load the convenience commands
+2. Build the application (if needed)
+3. Run VideoTools GUI
+
+**Available commands after sourcing alias.sh:**
+- `VideoTools` - Run the application
+- `VideoToolsRebuild` - Force a clean rebuild
+- `VideoToolsClean` - Clean all build artifacts
+
+### Option 2: Using build.sh Directly
+
+```bash
+cd /home/stu/Projects/VideoTools
+bash scripts/build.sh
+./VideoTools
+```
+
+### Option 3: Using run.sh
+
+```bash
+cd /home/stu/Projects/VideoTools
+bash scripts/run.sh
+```
+
+---
+
+## Making VideoTools Permanent (Optional)
+
+To use `VideoTools` command from anywhere in your terminal:
+
+### For Bash users:
+Add this line to `~/.bashrc`:
+```bash
+source /home/stu/Projects/VideoTools/scripts/alias.sh
+```
+
+Then reload:
+```bash
+source ~/.bashrc
+```
+
+### For Zsh users:
+Add this line to `~/.zshrc`:
+```bash
+source /home/stu/Projects/VideoTools/scripts/alias.sh
+```
+
+Then reload:
+```bash
+source ~/.zshrc
+```
+
+### After setting up:
+From any directory, you can simply type:
+```bash
+VideoTools
+```
+
+---
+
+## What Each Script Does
+
+### build.sh
+```bash
+bash scripts/build.sh
+```
+
+**Purpose:** Builds VideoTools from source with full dependency management
+
+**What it does:**
+1. Checks if Go is installed
+2. Displays Go version
+3. Cleans previous builds and cache
+4. Downloads and verifies all dependencies
+5. Builds the application
+6. Shows output file location and size
+
+**When to use:**
+- First time building
+- After major code changes
+- When you want a clean rebuild
+- When dependencies are out of sync
+
+**Exit codes:**
+- `0` = Success
+- `1` = Build failed (check errors above)
+
+### run.sh
+```bash
+bash scripts/run.sh
+```
+
+**Purpose:** Runs VideoTools, building first if needed
+
+**What it does:**
+1. Checks if binary exists
+2. If binary missing, runs `build.sh`
+3. Verifies binary was created
+4. Launches the application
+
+**When to use:**
+- Every time you want to run VideoTools
+- When you're not sure if it's built
+- After code changes (will rebuild if needed)
+
+**Advantages:**
+- Automatic build detection
+- No manual steps needed
+- Always runs the latest code
+
+### alias.sh
+```bash
+source scripts/alias.sh
+```
+
+**Purpose:** Creates convenient shell commands
+
+**What it does:**
+1. Adds `VideoTools` command (alias for `scripts/run.sh`)
+2. Adds `VideoToolsRebuild` function
+3. Adds `VideoToolsClean` function
+4. Prints help text
+
+**When to use:**
+- Once per shell session
+- Add to ~/.bashrc or ~/.zshrc for permanent access
+
+**Commands created:**
+```
+VideoTools              # Run the app
+VideoToolsRebuild       # Force rebuild
+VideoToolsClean         # Remove build artifacts
+```
+
+---
+
+## Build Requirements
+
+### Required:
+- **Go 1.21 or later**
+  ```bash
+  go version
+  ```
+  If not installed: https://golang.org/dl
+
+### Recommended:
+- At least 2 GB free disk space (for dependencies)
+- Stable internet connection (for downloading dependencies)
+
+### Optional:
+- FFmpeg (for actual video encoding)
+  ```bash
+  ffmpeg -version
+  ```
+
+---
+
+## Troubleshooting
+
+### Problem: "Go is not installed"
+**Solution:**
+1. Install Go from https://golang.org/dl
+2. Add Go to PATH: Add `/usr/local/go/bin` to your `$PATH`
+3. Verify: `go version`
+
+### Problem: Build fails with "CGO_ENABLED" error
+**Solution:** The script already handles this with `CGO_ENABLED=0`. If you still get errors:
+```bash
+export CGO_ENABLED=0
+bash scripts/build.sh
+```
+
+### Problem: "Permission denied" on scripts
+**Solution:**
+```bash
+chmod +x scripts/*.sh
+bash scripts/build.sh
+```
+
+### Problem: Out of disk space
+**Solution:** Clean the cache
+```bash
+bash scripts/build.sh
+# Or manually:
+go clean -cache -modcache
+```
+
+### Problem: Outdated dependencies
+**Solution:** Clean and rebuild
+```bash
+rm -rf go.mod go.sum
+go mod init git.leaktechnologies.dev/stu/VideoTools
+bash scripts/build.sh
+```
+
+### Problem: Binary won't run
+**Solution:** Check if it was built:
+```bash
+ls -lh VideoTools
+file VideoTools
+```
+
+If missing, rebuild:
+```bash
+bash scripts/build.sh
+```
+
+---
+
+## Development Workflow
+
+### Making code changes and testing:
+
+```bash
+# After editing code, rebuild and run:
+VideoToolsRebuild
+VideoTools
+
+# Or in one command:
+bash scripts/build.sh && ./VideoTools
+```
+
+### Quick test loop:
+```bash
+# Terminal 1: Watch for changes and rebuild
+while true; do bash scripts/build.sh; sleep 2; done
+
+# Terminal 2: Test the app
+VideoTools
+```
+
+---
+
+## DVD Encoding Workflow
+
+### To create a professional DVD video:
+
+1. **Start the application**
+   ```bash
+   VideoTools
+   ```
+
+2. **Go to Convert module**
+   - Click the Convert tile from main menu
+
+3. **Load a video**
+   - Drag and drop, or use file browser
+
+4. **Select DVD format**
+   - Choose "DVD-NTSC (MPEG-2)" or "DVD-PAL (MPEG-2)"
+   - DVD options appear automatically
+
+5. **Choose aspect ratio**
+   - Select 4:3 or 16:9
+
+6. **Name output**
+   - Enter filename (without .mpg extension)
+
+7. **Add to queue**
+   - Click "Add to Queue"
+
+8. **Start encoding**
+   - Click "View Queue" → "Start Queue"
+
+9. **Use output file**
+   - Output: `filename.mpg`
+   - Import into DVDStyler
+   - Author and burn to disc
+
+**Output specifications:**
+
+NTSC:
+- 720×480 @ 29.97fps
+- MPEG-2 video
+- AC-3 stereo audio @ 48 kHz
+- Perfect for USA, Canada, Japan, Australia
+
+PAL:
+- 720×576 @ 25 fps
+- MPEG-2 video
+- AC-3 stereo audio @ 48 kHz
+- Perfect for Europe, Africa, Asia
+
+Both output region-free, DVDStyler-compatible, PS2-compatible video.
+
+---
+
+## Performance Notes
+
+### Build time:
+- First build: 30-60 seconds (downloads dependencies)
+- Subsequent builds: 5-15 seconds (uses cached dependencies)
+- Rebuild with changes: 10-20 seconds
+
+### File sizes:
+- Binary: ~35 MB (optimized)
+- With dependencies in cache: ~1 GB total
+
+### Runtime:
+- Startup: 1-3 seconds
+- Memory usage: 50-150 MB depending on video complexity
+- Encoding speed: Depends on CPU and video complexity
+
+---
+
+## Production Use
+
+For production deployment:
+
+```bash
+# Create optimized binary
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o VideoTools
+
+# Verify it works
+./VideoTools
+
+# File size will be smaller with -ldflags
+ls -lh VideoTools
+```
+
+---
+
+## Getting Help
+
+### Check the documentation:
+- `DVD_USER_GUIDE.md` - How to use DVD encoding
+- `DVD_IMPLEMENTATION_SUMMARY.md` - Technical details
+- `README.md` - Project overview
+
+### Debug a build:
+```bash
+# Verbose output
+bash scripts/build.sh 2>&1 | tee build.log
+
+# Check go environment
+go env
+
+# Verify dependencies
+go mod graph
+```
+
+### Report issues:
+Include:
+1. Output from `go version`
+2. OS and architecture (`uname -a`)
+3. Exact error message
+4. Steps to reproduce
+
+---
+
+## Summary
+
+**Easiest way:**
+```bash
+cd /home/stu/Projects/VideoTools
+source scripts/alias.sh
+VideoTools
+```
+
+**That's it!** The scripts handle everything else automatically.
+