Add comprehensive build system documentation
Expanded build/README.md with detailed instructions for CI/CD and local builds, directory structure, build script options, output artifacts, requirements, troubleshooting, version management, and future enhancements for the YTSage build system.
This commit is contained in:
Your Name
+211
-1
@@ -1 +1,211 @@
|
||||
create dir
|
||||
# YTSage Build System
|
||||
|
||||
This directory contains all build-related files and configurations for creating YTSage distributions.
|
||||
|
||||
## 🏗️ Build Architecture
|
||||
|
||||
### Automated Builds (CI/CD)
|
||||
- **GitHub Actions**: Fully automated releases triggered by git tags
|
||||
- **Location**: `.github/workflows/build-windows.yml`
|
||||
- **Triggers**: Version tags (e.g., `v4.8.0`, `v4.9.1`)
|
||||
- **Output**: MSI installers + ZIP portable versions (Standard & FFmpeg)
|
||||
|
||||
### Local Development Builds
|
||||
- **Script**: `build/windows/windows-build-universal.ps1`
|
||||
- **Purpose**: Local testing and development
|
||||
- **Flexibility**: Manual control over build options
|
||||
|
||||
## 📁 Directory Structure
|
||||
|
||||
```
|
||||
build/
|
||||
├── windows/
|
||||
│ ├── setup.py # Standard cx_Freeze configuration
|
||||
│ ├── setup-ffmpeg.py # FFmpeg bundle cx_Freeze configuration
|
||||
│ ├── windows-build-universal.ps1 # Local development build script
|
||||
│ └── README.md # This file
|
||||
└── (future platforms)
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### For Releases (Recommended)
|
||||
```bash
|
||||
# Create and push a version tag
|
||||
git tag v4.8.1
|
||||
git push origin v4.8.1
|
||||
|
||||
# GitHub Actions will automatically:
|
||||
# 1. Build both versions
|
||||
# 2. Create MSI installers
|
||||
# 3. Create ZIP portable versions
|
||||
# 4. Generate draft release with artifacts
|
||||
```
|
||||
|
||||
### For Local Development
|
||||
```powershell
|
||||
# Navigate to project root
|
||||
cd c:\path\to\YTSage\build-env
|
||||
|
||||
# Run the universal build script
|
||||
.\build\windows\windows-build-universal.ps1 -Verbose
|
||||
|
||||
# Build only FFmpeg version
|
||||
.\build\windows\windows-build-universal.ps1 -FFmpeg -Verbose
|
||||
|
||||
# Build only MSI (no ZIP)
|
||||
.\build\windows\windows-build-universal.ps1 -MSIOnly
|
||||
|
||||
# Build only ZIP (no MSI)
|
||||
.\build\windows\windows-build-universal.ps1 -ZIPOnly
|
||||
```
|
||||
|
||||
## 📋 Build Configurations
|
||||
|
||||
### Standard Version (`setup.py`)
|
||||
- **Target**: General users
|
||||
- **Size**: Smaller download
|
||||
- **FFmpeg**: Downloaded automatically when needed
|
||||
|
||||
### FFmpeg Bundle (`setup-ffmpeg.py`)
|
||||
- **Target**: Users without internet or restricted environments
|
||||
- **Size**: Larger download (~100MB+)
|
||||
- **FFmpeg**: Included in installer
|
||||
|
||||
## 🔧 Build Script Options
|
||||
|
||||
### windows-build-universal.ps1 Parameters
|
||||
```powershell
|
||||
-SkipVenv # Skip virtual environment creation
|
||||
-Verbose # Enable detailed output
|
||||
-FFmpeg # Build FFmpeg bundle version
|
||||
-MSIOnly # Create only MSI installer
|
||||
-ZIPOnly # Create only ZIP distribution
|
||||
-OutputDir # Custom output directory (default: "releases")
|
||||
-FFmpegPath # Custom FFmpeg binaries path
|
||||
```
|
||||
|
||||
### Examples
|
||||
```powershell
|
||||
# Full build with verbose output
|
||||
.\build\windows\windows-build-universal.ps1 -Verbose
|
||||
|
||||
# Quick standard version build
|
||||
.\build\windows\windows-build-universal.ps1 -MSIOnly
|
||||
|
||||
# FFmpeg version to custom directory
|
||||
.\build\windows\windows-build-universal.ps1 -FFmpeg -OutputDir "custom-builds"
|
||||
```
|
||||
|
||||
## 📦 Output Artifacts
|
||||
|
||||
### CI/CD Builds (GitHub Actions)
|
||||
```
|
||||
releases/
|
||||
├── YTSage-v4.8.1.msi # Standard installer
|
||||
├── YTSage-v4.8.1.zip # Standard portable
|
||||
├── YTSage-v4.8.1-ffmpeg.msi # FFmpeg installer
|
||||
└── YTSage-v4.8.1-ffmpeg.zip # FFmpeg portable
|
||||
```
|
||||
|
||||
### Local Builds
|
||||
```
|
||||
releases/
|
||||
├── YTSage-4.8.1.msi # Standard installer
|
||||
├── YTSage-4.8.1.zip # Standard portable
|
||||
├── YTSage-4.8.1-ffmpeg.msi # FFmpeg installer (if built)
|
||||
└── YTSage-4.8.1-ffmpeg.zip # FFmpeg portable (if built)
|
||||
```
|
||||
|
||||
## 🛠️ Build Requirements
|
||||
|
||||
### System Requirements
|
||||
- **OS**: Windows 10/11
|
||||
- **PowerShell**: 5.1 or later
|
||||
- **Python**: 3.12+ (3.12.10 recommended for MSI compatibility)
|
||||
- **Memory**: 4GB+ RAM recommended
|
||||
- **Storage**: 2GB+ free space
|
||||
|
||||
### Python Dependencies
|
||||
- **cx_Freeze**: 6.x for MSI creation
|
||||
- **playsound3**: Audio notification system
|
||||
- **All project dependencies**: Listed in `requirements.txt`
|
||||
|
||||
### Optional Components
|
||||
- **FFmpeg**: For bundled builds (auto-downloaded if not present)
|
||||
- **Code Signing**: Certificate for signed installers (optional)
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Build Fails with Import Errors
|
||||
```powershell
|
||||
# Recreate virtual environment
|
||||
Remove-Item venv -Recurse -Force
|
||||
.\build\windows\windows-build-universal.ps1 -Verbose
|
||||
```
|
||||
|
||||
#### MSI Creation Fails
|
||||
- Ensure Python 3.12.x (required for MSI compatibility)
|
||||
- Check cx_Freeze version (should be 6.x)
|
||||
- Verify all dependencies are installed
|
||||
|
||||
#### FFmpeg Not Found
|
||||
```powershell
|
||||
# Specify custom FFmpeg path
|
||||
.\build\windows\windows-build-universal.ps1 -FFmpeg -FFmpegPath "C:\ffmpeg\bin"
|
||||
```
|
||||
|
||||
#### CI/CD Build Fails
|
||||
- Check GitHub Actions logs
|
||||
- Verify tag format (`v*`)
|
||||
- Ensure all required files are present
|
||||
- Check file paths in workflow
|
||||
|
||||
### Debug Mode
|
||||
```powershell
|
||||
# Enable maximum verbosity
|
||||
.\build\windows\windows-build-universal.ps1 -Verbose -Debug
|
||||
```
|
||||
|
||||
## 📈 Version Management
|
||||
|
||||
### Automatic Version Detection
|
||||
- **CI/CD**: Extracts version from git tag
|
||||
- **Local**: Uses version from setup.py files
|
||||
- **Format**: Semantic versioning (e.g., 4.8.1)
|
||||
|
||||
### Manual Version Update
|
||||
```powershell
|
||||
# Update version in setup files
|
||||
(Get-Content build\windows\setup.py) -replace 'version="[^"]*"', 'version="4.8.2"' | Set-Content build\windows\setup.py
|
||||
(Get-Content build\windows\setup-ffmpeg.py) -replace 'version="[^"]*"', 'version="4.8.2"' | Set-Content build\windows\setup-ffmpeg.py
|
||||
```
|
||||
|
||||
## 🔮 Future Enhancements
|
||||
|
||||
### Planned Features
|
||||
- **Linux builds**: Future cross-platform support
|
||||
- **macOS builds**: Apple platform support
|
||||
- **Auto-updater**: Built-in update mechanism
|
||||
- **Digital signing**: Code signing for Windows
|
||||
|
||||
### Contributing
|
||||
- Build improvements welcome
|
||||
- Cross-platform configurations
|
||||
- Performance optimizations
|
||||
- Documentation enhancements
|
||||
|
||||
## 📚 Related Documentation
|
||||
|
||||
- **CI/CD Guide**: `.github/CI_CD_README.md`
|
||||
- **Project README**: `../README.md`
|
||||
- **Release Notes**: GitHub Releases
|
||||
- **Issue Tracking**: GitHub Issues
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: August 2025
|
||||
**Build System Version**: 4.8.x
|
||||
**Supported Platforms**: Windows (primary)
|
||||
|
||||
Reference in New Issue
Block a user