254 lines
9.7 KiB
Markdown
254 lines
9.7 KiB
Markdown
|
# Build Scripts Directory
|
||
|
|
|
||
|
|
This directory contains all build-related scripts for the Rustelo project. These tools are organized by common build tasks and contexts to help you find the right tool for your needs.
|
||
|
|
|
||
|
|
## 📋 Requirements
|
||
|
|
|
||
|
|
**Required Tools:**
|
||
|
|
- [Nushell](https://www.nushell.sh/) - All `.nu` scripts require Nushell to be installed
|
||
|
|
- [Just](https://github.com/casey/just) - Task runner (recommended for easy command execution)
|
||
|
|
- For complete setup, see [Rustelo Requirements - Tools](https://github.com/your-repo/rustelo#tools)
|
||
|
|
|
||
|
|
## 🏗️ Build Tools by Context
|
||
|
|
|
||
|
|
### 🚀 Production Build & Deployment
|
||
|
|
|
||
|
|
#### `leptos-build.nu` - Complete Production Build Pipeline
|
||
|
|
**Purpose:** Full production build with dependencies, CSS, and optimization
|
||
|
|
**Task:** Build production-ready Leptos application
|
||
|
|
**Context:** Use when preparing for deployment or creating release builds
|
||
|
|
**Command:** `nu scripts/build/leptos-build.nu` or `just leptos-build-nu`
|
||
|
|
**Features:**
|
||
|
|
- Installs all dependencies (main + end2end)
|
||
|
|
- Builds CSS assets with UnoCSS
|
||
|
|
- Compiles Leptos with release optimizations
|
||
|
|
- Enables TLS and content-static features
|
||
|
|
- Minifies JavaScript output
|
||
|
|
|
||
|
|
#### `deploy.nu` - Application Deployment Manager
|
||
|
|
**Purpose:** Complete deployment management with Docker Compose
|
||
|
|
**Task:** Deploy, manage, and monitor application environments
|
||
|
|
**Context:** Production, staging, and development deployments
|
||
|
|
**Command:** `nu scripts/build/deploy.nu [OPTIONS] COMMAND`
|
||
|
|
**Main Arguments:**
|
||
|
|
- `-e, --env ENV` - Environment (dev|staging|production)
|
||
|
|
- `-f, --file FILE` - Docker compose file
|
||
|
|
- `-s, --scale N` - Number of replicas
|
||
|
|
- `--migrate` - Run database migrations
|
||
|
|
- `--backup` - Create database backup
|
||
|
|
- `--features FEATURES` - Cargo features to enable
|
||
|
|
|
||
|
|
**Commands:**
|
||
|
|
- `deploy` - Deploy application with health checks
|
||
|
|
- `stop/restart` - Control application lifecycle
|
||
|
|
- `status` - Show deployment status and resource usage
|
||
|
|
- `logs` - View application logs
|
||
|
|
- `scale` - Scale replicas
|
||
|
|
- `health` - Check application health
|
||
|
|
- `backup/migrate` - Database operations
|
||
|
|
- `clean` - Clean up unused containers
|
||
|
|
|
||
|
|
**Examples:**
|
||
|
|
```bash
|
||
|
|
nu scripts/build/deploy.nu deploy -e production --migrate --backup
|
||
|
|
nu scripts/build/deploy.nu scale -s 3
|
||
|
|
nu scripts/build/deploy.nu health
|
||
|
|
```
|
||
|
|
|
||
|
|
### 📦 Distribution & Packaging
|
||
|
|
|
||
|
|
#### `dist-pack.nu` - Distribution Package Creator
|
||
|
|
**Purpose:** Create compressed distribution packages for deployment
|
||
|
|
**Task:** Package built application for different architectures
|
||
|
|
**Context:** CI/CD pipelines, manual distribution, release preparation
|
||
|
|
**Command:** `nu scripts/build/dist-pack.nu [OS_ARCH]` or `just dist-pack-nu [target]`
|
||
|
|
**Arguments:**
|
||
|
|
- `OS_ARCH` - Target architecture (e.g., linux-x64, darwin-arm64)
|
||
|
|
|
||
|
|
**Features:**
|
||
|
|
- Validates build artifacts exist
|
||
|
|
- Packages server binary, site assets, public files
|
||
|
|
- Creates compressed tar.gz archives
|
||
|
|
- Shows package size and contents
|
||
|
|
|
||
|
|
### 🔧 Cross-Platform Development
|
||
|
|
|
||
|
|
#### `cross-build.nu` - Docker Cross-Platform Builder
|
||
|
|
**Purpose:** Build application for different architectures using Docker
|
||
|
|
**Task:** Cross-compile for Linux from macOS/Windows
|
||
|
|
**Context:** Multi-platform releases, Linux deployment from dev machines
|
||
|
|
**Command:** `nu scripts/build/cross-build.nu` or `just cross-build-nu`
|
||
|
|
**Features:**
|
||
|
|
- Uses Docker for consistent Linux builds
|
||
|
|
- Handles volume mounts for project, node_modules, target
|
||
|
|
- Runs complete build pipeline in container
|
||
|
|
- Shows distribution file results
|
||
|
|
|
||
|
|
#### `build-docker-cross.nu` - Cross-Compilation Image Builder
|
||
|
|
**Purpose:** Build Docker image for cross-platform compilation
|
||
|
|
**Task:** Create/update build environment Docker image
|
||
|
|
**Context:** Setting up cross-compilation environment, updating build tools
|
||
|
|
**Command:** `nu scripts/build/build-docker-cross.nu` or `just docker-cross-build-nu`
|
||
|
|
**Features:**
|
||
|
|
- Builds custom Docker image for cross-compilation
|
||
|
|
- Validates Docker availability
|
||
|
|
- Shows image information and size
|
||
|
|
|
||
|
|
### 📚 Documentation & Examples
|
||
|
|
|
||
|
|
#### `build-docs.nu` - Documentation Generator with Assets
|
||
|
|
**Purpose:** Generate Cargo documentation with integrated logo assets
|
||
|
|
**Task:** Build comprehensive project documentation
|
||
|
|
**Context:** Documentation updates, release preparation, developer onboarding
|
||
|
|
**Command:** `nu scripts/build/build-docs.nu` or `just docs-cargo-nu`
|
||
|
|
**Features:**
|
||
|
|
- Generates cargo doc with private items
|
||
|
|
- Copies logo assets to documentation output
|
||
|
|
- Validates documentation structure
|
||
|
|
- Shows documentation size and location
|
||
|
|
- Provides next steps for viewing docs
|
||
|
|
|
||
|
|
#### `build-examples.nu` - Multi-Configuration Build Examples
|
||
|
|
**Purpose:** Demonstrate building with different Cargo feature combinations
|
||
|
|
**Task:** Test and showcase various application configurations
|
||
|
|
**Context:** Testing feature combinations, documentation examples, CI validation
|
||
|
|
**Command:** `nu scripts/build/build-examples.nu [OPTIONS]`
|
||
|
|
**Arguments:**
|
||
|
|
- `-c, --clean` - Clean build artifacts first
|
||
|
|
- `-a, --all` - Build all configurations (default)
|
||
|
|
- `-m, --minimal` - Minimal configuration only
|
||
|
|
- `-f, --full` - Full-featured configuration only
|
||
|
|
- `-p, --prod` - Production configuration only
|
||
|
|
- `-q, --quick` - Common configurations only
|
||
|
|
|
||
|
|
**Configurations Built:**
|
||
|
|
- Minimal (no database)
|
||
|
|
- TLS-only (secure static)
|
||
|
|
- Auth-only (authentication)
|
||
|
|
- Content-DB (database content)
|
||
|
|
- Full-featured (auth + content)
|
||
|
|
- Production (all features)
|
||
|
|
- Specialized combinations
|
||
|
|
|
||
|
|
### 🌍 Content & Localization
|
||
|
|
|
||
|
|
#### `build-localized-content.nu` - Markdown to HTML Content Builder
|
||
|
|
**Purpose:** Convert localized markdown content to HTML for web serving
|
||
|
|
**Task:** Process multilingual content with categories, tags, and metadata
|
||
|
|
**Context:** Content updates, adding new languages, preparing content for deployment
|
||
|
|
**Command:** `nu scripts/build/build-localized-content.nu`
|
||
|
|
**Features:**
|
||
|
|
- Reads content types from content-kinds.toml
|
||
|
|
- Processes English and Spanish content
|
||
|
|
- Converts markdown to HTML with frontmatter
|
||
|
|
- Generates category indices and filter indices
|
||
|
|
- Creates content manifest
|
||
|
|
- Validates JSON structure
|
||
|
|
- Shows content statistics
|
||
|
|
|
||
|
|
**Content Processing:**
|
||
|
|
- Discovers content types dynamically
|
||
|
|
- Handles category directory structures
|
||
|
|
- Extracts metadata (tags, categories, publishing status)
|
||
|
|
- Generates navigation indices
|
||
|
|
- Creates backward compatibility links
|
||
|
|
|
||
|
|
### 🛠️ Development Tools
|
||
|
|
|
||
|
|
#### `dev-quiet.nu` - Filtered Development Server
|
||
|
|
**Purpose:** Run development server with filtered, relevant output only
|
||
|
|
**Task:** Start Leptos development server without noise
|
||
|
|
**Context:** Daily development, focusing on important messages
|
||
|
|
**Command:** `nu scripts/build/dev-quiet.nu` or `just dev-quiet-nu`
|
||
|
|
**Features:**
|
||
|
|
- Runs `cargo leptos watch`
|
||
|
|
- Filters out verbose/irrelevant output
|
||
|
|
- Highlights errors, warnings, and important messages
|
||
|
|
- Shows clean, focused development feedback
|
||
|
|
|
||
|
|
#### `kill-3030.nu` - Development Port Process Killer
|
||
|
|
**Purpose:** Kill processes running on development ports (3030, 3031)
|
||
|
|
**Task:** Clean up stuck development servers
|
||
|
|
**Context:** Development workflow, server restart, port conflicts
|
||
|
|
**Command:** `nu scripts/build/kill-3030.nu`
|
||
|
|
**Features:**
|
||
|
|
- Finds processes using ports 3030 and 3031
|
||
|
|
- Safely kills development server processes
|
||
|
|
- Shows which processes were killed
|
||
|
|
- Handles cases where no processes are found
|
||
|
|
|
||
|
|
## 🎨 Asset Build Tools (JavaScript)
|
||
|
|
|
||
|
|
### CSS & Theme Building
|
||
|
|
- **`build-css-bundles.js`** - CSS bundling and optimization
|
||
|
|
- **`build-design-system.js`** - Design system compilation
|
||
|
|
- **`build-theme.js`** - Theme file generation
|
||
|
|
- **`copy-css-assets.js`** - CSS asset management
|
||
|
|
|
||
|
|
### JavaScript & Highlighting
|
||
|
|
- **`build-highlight-bundle.js`** - Syntax highlighting bundle creation
|
||
|
|
- **`build-inline-scripts.js`** - Inline script optimization
|
||
|
|
|
||
|
|
**Usage:** These are typically called through the main build pipeline or package.json scripts.
|
||
|
|
|
||
|
|
## 🚀 Quick Start Commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Complete production build
|
||
|
|
just leptos-build-nu
|
||
|
|
|
||
|
|
# Development with clean output
|
||
|
|
just dev-quiet-nu
|
||
|
|
|
||
|
|
# Deploy to production
|
||
|
|
nu scripts/build/deploy.nu deploy -e production --migrate
|
||
|
|
|
||
|
|
# Build all configuration examples
|
||
|
|
nu scripts/build/build-examples.nu --all
|
||
|
|
|
||
|
|
# Generate documentation
|
||
|
|
just docs-cargo-nu
|
||
|
|
|
||
|
|
# Create distribution package
|
||
|
|
just dist-pack-nu linux-x64
|
||
|
|
|
||
|
|
# Build localized content
|
||
|
|
nu scripts/build/build-localized-content.nu
|
||
|
|
|
||
|
|
# Clean development ports
|
||
|
|
nu scripts/build/kill-3030.nu
|
||
|
|
```
|
||
|
|
|
||
|
|
## 📁 File Organization
|
||
|
|
|
||
|
|
```
|
||
|
|
scripts/build/
|
||
|
|
├── README.md # This documentation
|
||
|
|
├── leptos-build.nu # 🚀 Main production build
|
||
|
|
├── deploy.nu # 🚀 Deployment manager
|
||
|
|
├── dist-pack.nu # 📦 Distribution packaging
|
||
|
|
├── cross-build.nu # 🔧 Cross-platform building
|
||
|
|
├── build-docker-cross.nu # 🔧 Docker build environment
|
||
|
|
├── build-docs.nu # 📚 Documentation generation
|
||
|
|
├── build-examples.nu # 📚 Configuration examples
|
||
|
|
├── build-localized-content.nu # 🌍 Content localization
|
||
|
|
├── dev-quiet.nu # 🛠️ Development server
|
||
|
|
├── kill-3030.nu # 🛠️ Port cleanup
|
||
|
|
└── [*.js files] # 🎨 Asset build tools
|
||
|
|
```
|
||
|
|
|
||
|
|
## 🔄 Integration with Just
|
||
|
|
|
||
|
|
Most scripts are integrated with the project's `justfile` for convenient access:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
just dev-quiet-nu # Quiet development server
|
||
|
|
just docs-cargo-nu # Build documentation
|
||
|
|
just dist-pack-nu linux-x64 # Create distribution
|
||
|
|
just cross-build-nu # Cross-platform build
|
||
|
|
just docker-cross-build-nu # Build Docker image
|
||
|
|
```
|
||
|
|
|
||
|
|
## 🔧 Original Bash Scripts
|
||
|
|
|
||
|
|
Original bash scripts are preserved in `scripts/sh/build/` for reference during the transition period. The Nushell versions provide enhanced error handling, structured data processing, and better cross-platform compatibility.
|