mirror of
https://github.com/community-scripts/ProxmoxVED.git
synced 2026-02-25 05:57:26 +00:00
Add docs for all files in /misc
This commit is contained in:
Michel Roegl-Brunner
361
docs/misc/build.func/BUILD_FUNC_FUNCTIONS_REFERENCE.md
Normal file
361
docs/misc/build.func/BUILD_FUNC_FUNCTIONS_REFERENCE.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# build.func Functions Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive reference of all functions in `build.func`, organized alphabetically with detailed descriptions, parameters, and usage information.
|
||||
|
||||
## Function Categories
|
||||
|
||||
### Initialization Functions
|
||||
|
||||
#### `start()`
|
||||
**Purpose**: Main entry point when build.func is sourced or executed
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Detects execution context (Proxmox host vs container)
|
||||
- Captures hard environment variables
|
||||
- Sets CT_TYPE based on context
|
||||
- Routes to appropriate workflow (install_script or update_script)
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `CT_TYPE`, `APP`, `CTID`
|
||||
|
||||
#### `variables()`
|
||||
**Purpose**: Load and resolve all configuration variables using precedence chain
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Loads app-specific .vars file
|
||||
- Loads global default.vars file
|
||||
- Applies variable precedence chain
|
||||
- Sets all configuration variables
|
||||
**Dependencies**: `base_settings()`
|
||||
**Environment Variables Used**: All configuration variables
|
||||
|
||||
#### `base_settings()`
|
||||
**Purpose**: Set built-in default values for all configuration variables
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets default values for all variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: All configuration variables
|
||||
|
||||
### UI and Menu Functions
|
||||
|
||||
#### `install_script()`
|
||||
**Purpose**: Main installation workflow coordinator
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Displays installation mode selection menu
|
||||
- Coordinates the entire installation process
|
||||
- Handles user interaction and validation
|
||||
**Dependencies**: `variables()`, `build_container()`, `default_var_settings()`
|
||||
**Environment Variables Used**: `APP`, `CTID`, `var_hostname`
|
||||
|
||||
#### `advanced_settings()`
|
||||
**Purpose**: Provide advanced configuration options via whiptail menus
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Displays whiptail menus for configuration
|
||||
- Updates configuration variables based on user input
|
||||
- Validates user selections
|
||||
**Dependencies**: `select_storage()`, `detect_gpu_devices()`
|
||||
**Environment Variables Used**: All configuration variables
|
||||
|
||||
#### `settings_menu()`
|
||||
**Purpose**: Display and handle settings configuration menu
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Updates configuration variables
|
||||
**Dependencies**: `advanced_settings()`
|
||||
**Environment Variables Used**: All configuration variables
|
||||
|
||||
### Storage Functions
|
||||
|
||||
#### `select_storage()`
|
||||
**Purpose**: Handle storage selection for templates and containers
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Resolves storage preselection
|
||||
- Prompts user for storage selection if needed
|
||||
- Validates storage availability
|
||||
- Sets var_template_storage and var_container_storage
|
||||
**Dependencies**: `resolve_storage_preselect()`, `choose_and_set_storage_for_file()`
|
||||
**Environment Variables Used**: `var_template_storage`, `var_container_storage`, `TEMPLATE_STORAGE`, `CONTAINER_STORAGE`
|
||||
|
||||
#### `resolve_storage_preselect()`
|
||||
**Purpose**: Resolve preselected storage options
|
||||
**Parameters**:
|
||||
- `storage_type`: Type of storage (template or container)
|
||||
**Returns**: Storage name if valid, empty if invalid
|
||||
**Side Effects**: Validates storage availability
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `var_template_storage`, `var_container_storage`
|
||||
|
||||
#### `choose_and_set_storage_for_file()`
|
||||
**Purpose**: Interactive storage selection via whiptail
|
||||
**Parameters**:
|
||||
- `storage_type`: Type of storage (template or container)
|
||||
- `content_type`: Content type (vztmpl or rootdir)
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Displays whiptail menu
|
||||
- Updates storage variables
|
||||
- Validates selection
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `var_template_storage`, `var_container_storage`
|
||||
|
||||
### Container Creation Functions
|
||||
|
||||
#### `build_container()`
|
||||
**Purpose**: Validate settings and prepare container creation
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Validates all configuration
|
||||
- Checks for conflicts
|
||||
- Prepares container configuration
|
||||
- Calls create_lxc_container()
|
||||
**Dependencies**: `create_lxc_container()`
|
||||
**Environment Variables Used**: All configuration variables
|
||||
|
||||
#### `create_lxc_container()`
|
||||
**Purpose**: Create the actual LXC container
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Creates LXC container with basic configuration
|
||||
- Configures network settings
|
||||
- Sets up storage and mount points
|
||||
- Configures features (FUSE, TUN, etc.)
|
||||
- Sets resource limits
|
||||
- Configures startup options
|
||||
- Starts container
|
||||
**Dependencies**: `configure_gpu_passthrough()`, `fix_gpu_gids()`
|
||||
**Environment Variables Used**: All configuration variables
|
||||
|
||||
### GPU and Hardware Functions
|
||||
|
||||
#### `detect_gpu_devices()`
|
||||
**Purpose**: Detect available GPU hardware on the system
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Scans for Intel, AMD, and NVIDIA GPUs
|
||||
- Updates var_gpu_type and var_gpu_devices
|
||||
- Determines GPU capabilities
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `var_gpu_type`, `var_gpu_devices`, `GPU_APPS`
|
||||
|
||||
#### `configure_gpu_passthrough()`
|
||||
**Purpose**: Configure GPU passthrough for the container
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Adds GPU device entries to container config
|
||||
- Configures proper device permissions
|
||||
- Sets up device mapping
|
||||
- Updates /etc/pve/lxc/<ctid>.conf
|
||||
**Dependencies**: `detect_gpu_devices()`
|
||||
**Environment Variables Used**: `var_gpu`, `var_gpu_type`, `var_gpu_devices`, `CTID`
|
||||
|
||||
#### `fix_gpu_gids()`
|
||||
**Purpose**: Fix GPU group IDs after container creation
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Updates GPU group IDs in container
|
||||
- Ensures proper GPU access permissions
|
||||
- Configures video and render groups
|
||||
**Dependencies**: `configure_gpu_passthrough()`
|
||||
**Environment Variables Used**: `CTID`, `var_gpu_type`
|
||||
|
||||
### Settings Persistence Functions
|
||||
|
||||
#### `default_var_settings()`
|
||||
**Purpose**: Offer to save current settings as defaults
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Prompts user to save settings
|
||||
- Saves to default.vars file
|
||||
- Saves to app-specific .vars file
|
||||
**Dependencies**: `maybe_offer_save_app_defaults()`
|
||||
**Environment Variables Used**: All configuration variables
|
||||
|
||||
#### `maybe_offer_save_app_defaults()`
|
||||
**Purpose**: Offer to save app-specific defaults
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Prompts user to save app-specific settings
|
||||
- Saves to app.vars file
|
||||
- Updates app-specific configuration
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `APP`, `SAVE_APP_DEFAULTS`
|
||||
|
||||
### Utility Functions
|
||||
|
||||
#### `validate_settings()`
|
||||
**Purpose**: Validate all configuration settings
|
||||
**Parameters**: None
|
||||
**Returns**: 0 if valid, 1 if invalid
|
||||
**Side Effects**:
|
||||
- Checks for configuration conflicts
|
||||
- Validates resource limits
|
||||
- Validates network configuration
|
||||
- Validates storage configuration
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: All configuration variables
|
||||
|
||||
#### `check_conflicts()`
|
||||
**Purpose**: Check for configuration conflicts
|
||||
**Parameters**: None
|
||||
**Returns**: 0 if no conflicts, 1 if conflicts found
|
||||
**Side Effects**:
|
||||
- Checks for conflicting settings
|
||||
- Validates resource allocation
|
||||
- Checks network configuration
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: All configuration variables
|
||||
|
||||
#### `cleanup_on_error()`
|
||||
**Purpose**: Clean up resources on error
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Removes partially created containers
|
||||
- Cleans up temporary files
|
||||
- Resets configuration
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `CTID`
|
||||
|
||||
## Function Call Flow
|
||||
|
||||
### Main Installation Flow
|
||||
```
|
||||
start()
|
||||
├── variables()
|
||||
│ ├── base_settings()
|
||||
│ ├── Load app.vars
|
||||
│ └── Load default.vars
|
||||
├── install_script()
|
||||
│ ├── advanced_settings()
|
||||
│ │ ├── select_storage()
|
||||
│ │ │ ├── resolve_storage_preselect()
|
||||
│ │ │ └── choose_and_set_storage_for_file()
|
||||
│ │ └── detect_gpu_devices()
|
||||
│ ├── build_container()
|
||||
│ │ ├── validate_settings()
|
||||
│ │ ├── check_conflicts()
|
||||
│ │ └── create_lxc_container()
|
||||
│ │ ├── configure_gpu_passthrough()
|
||||
│ │ └── fix_gpu_gids()
|
||||
│ └── default_var_settings()
|
||||
│ └── maybe_offer_save_app_defaults()
|
||||
```
|
||||
|
||||
### Error Handling Flow
|
||||
```
|
||||
Error Detection
|
||||
├── validate_settings()
|
||||
│ └── check_conflicts()
|
||||
├── Error Handling
|
||||
│ └── cleanup_on_error()
|
||||
└── Exit with error code
|
||||
```
|
||||
|
||||
## Function Dependencies
|
||||
|
||||
### Core Dependencies
|
||||
- `start()` → `install_script()` → `build_container()` → `create_lxc_container()`
|
||||
- `variables()` → `base_settings()`
|
||||
- `advanced_settings()` → `select_storage()` → `detect_gpu_devices()`
|
||||
|
||||
### Storage Dependencies
|
||||
- `select_storage()` → `resolve_storage_preselect()`
|
||||
- `select_storage()` → `choose_and_set_storage_for_file()`
|
||||
|
||||
### GPU Dependencies
|
||||
- `configure_gpu_passthrough()` → `detect_gpu_devices()`
|
||||
- `fix_gpu_gids()` → `configure_gpu_passthrough()`
|
||||
|
||||
### Settings Dependencies
|
||||
- `default_var_settings()` → `maybe_offer_save_app_defaults()`
|
||||
|
||||
## Function Usage Examples
|
||||
|
||||
### Basic Container Creation
|
||||
```bash
|
||||
# Set required variables
|
||||
export APP="plex"
|
||||
export CTID="100"
|
||||
export var_hostname="plex-server"
|
||||
|
||||
# Call main functions
|
||||
start() # Entry point
|
||||
# → variables() # Load configuration
|
||||
# → install_script() # Main workflow
|
||||
# → build_container() # Create container
|
||||
# → create_lxc_container() # Actual creation
|
||||
```
|
||||
|
||||
### Advanced Configuration
|
||||
```bash
|
||||
# Set advanced variables
|
||||
export var_os="debian"
|
||||
export var_version="12"
|
||||
export var_cpu="4"
|
||||
export var_ram="4096"
|
||||
export var_disk="20"
|
||||
|
||||
# Call advanced functions
|
||||
advanced_settings() # Interactive configuration
|
||||
# → select_storage() # Storage selection
|
||||
# → detect_gpu_devices() # GPU detection
|
||||
```
|
||||
|
||||
### GPU Passthrough
|
||||
```bash
|
||||
# Enable GPU passthrough
|
||||
export GPU_APPS="plex"
|
||||
export var_gpu="nvidia"
|
||||
|
||||
# Call GPU functions
|
||||
detect_gpu_devices() # Detect hardware
|
||||
configure_gpu_passthrough() # Configure passthrough
|
||||
fix_gpu_gids() # Fix permissions
|
||||
```
|
||||
|
||||
### Settings Persistence
|
||||
```bash
|
||||
# Save settings as defaults
|
||||
export SAVE_DEFAULTS="true"
|
||||
export SAVE_APP_DEFAULTS="true"
|
||||
|
||||
# Call persistence functions
|
||||
default_var_settings() # Save global defaults
|
||||
maybe_offer_save_app_defaults() # Save app defaults
|
||||
```
|
||||
|
||||
## Function Error Handling
|
||||
|
||||
### Validation Functions
|
||||
- `validate_settings()`: Returns 0 for valid, 1 for invalid
|
||||
- `check_conflicts()`: Returns 0 for no conflicts, 1 for conflicts
|
||||
|
||||
### Error Recovery
|
||||
- `cleanup_on_error()`: Cleans up on any error
|
||||
- Error codes are propagated up the call stack
|
||||
- Critical errors cause script termination
|
||||
|
||||
### Error Types
|
||||
1. **Configuration Errors**: Invalid settings or conflicts
|
||||
2. **Resource Errors**: Insufficient resources or conflicts
|
||||
3. **Network Errors**: Invalid network configuration
|
||||
4. **Storage Errors**: Storage not available or invalid
|
||||
5. **GPU Errors**: GPU configuration failures
|
||||
6. **Container Creation Errors**: LXC creation failures
|
||||
Reference in New Issue
Block a user