mirror of
https://github.com/community-scripts/ProxmoxVE.git
synced 2025-12-27 09:26:25 +01:00
add comprehensive documentation (#9537)
This commit is contained in:
CanbiZ
517
docs/misc/core.func/CORE_INTEGRATION.md
Normal file
517
docs/misc/core.func/CORE_INTEGRATION.md
Normal file
@ -0,0 +1,517 @@
|
||||
# core.func Integration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes how `core.func` integrates with other components in the Proxmox Community Scripts project, including dependencies, data flow, and API surface.
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External Dependencies
|
||||
|
||||
#### Required Commands
|
||||
- **`pveversion`**: Proxmox VE version checking
|
||||
- **`dpkg`**: Architecture detection
|
||||
- **`ps`**: Process and shell detection
|
||||
- **`id`**: User ID checking
|
||||
- **`curl`**: Header file downloading
|
||||
- **`swapon`**: Swap status checking
|
||||
- **`dd`**: Swap file creation
|
||||
- **`mkswap`**: Swap file formatting
|
||||
|
||||
#### Optional Commands
|
||||
- **`tput`**: Terminal control (installed if missing)
|
||||
- **`apk`**: Alpine package manager
|
||||
- **`apt-get`**: Debian package manager
|
||||
|
||||
### Internal Dependencies
|
||||
|
||||
#### error_handler.func
|
||||
- **Purpose**: Provides error code explanations for silent execution
|
||||
- **Usage**: Automatically loaded when `silent()` encounters errors
|
||||
- **Integration**: Called via `explain_exit_code()` function
|
||||
- **Data Flow**: Error code → explanation → user display
|
||||
|
||||
## Integration Points
|
||||
|
||||
### With build.func
|
||||
|
||||
#### System Validation
|
||||
```bash
|
||||
# build.func uses core.func for system checks
|
||||
source core.func
|
||||
pve_check
|
||||
arch_check
|
||||
shell_check
|
||||
root_check
|
||||
```
|
||||
|
||||
#### User Interface
|
||||
```bash
|
||||
# build.func uses core.func for UI elements
|
||||
msg_info "Creating container..."
|
||||
msg_ok "Container created successfully"
|
||||
msg_error "Container creation failed"
|
||||
```
|
||||
|
||||
#### Silent Execution
|
||||
```bash
|
||||
# build.func uses core.func for command execution
|
||||
silent pct create "$CTID" "$TEMPLATE" \
|
||||
--hostname "$HOSTNAME" \
|
||||
--memory "$MEMORY" \
|
||||
--cores "$CORES"
|
||||
```
|
||||
|
||||
### With tools.func
|
||||
|
||||
#### Utility Functions
|
||||
```bash
|
||||
# tools.func uses core.func utilities
|
||||
source core.func
|
||||
|
||||
# System checks
|
||||
pve_check
|
||||
root_check
|
||||
|
||||
# UI elements
|
||||
msg_info "Running maintenance tasks..."
|
||||
msg_ok "Maintenance completed"
|
||||
```
|
||||
|
||||
#### Error Handling
|
||||
```bash
|
||||
# tools.func uses core.func for error handling
|
||||
if silent systemctl restart service; then
|
||||
msg_ok "Service restarted"
|
||||
else
|
||||
msg_error "Service restart failed"
|
||||
fi
|
||||
```
|
||||
|
||||
### With api.func
|
||||
|
||||
#### System Validation
|
||||
```bash
|
||||
# api.func uses core.func for system checks
|
||||
source core.func
|
||||
pve_check
|
||||
root_check
|
||||
```
|
||||
|
||||
#### API Operations
|
||||
```bash
|
||||
# api.func uses core.func for API calls
|
||||
msg_info "Connecting to Proxmox API..."
|
||||
if silent curl -k -H "Authorization: PVEAPIToken=$API_TOKEN" \
|
||||
"$API_URL/api2/json/nodes/$NODE/lxc"; then
|
||||
msg_ok "API connection successful"
|
||||
else
|
||||
msg_error "API connection failed"
|
||||
fi
|
||||
```
|
||||
|
||||
### With error_handler.func
|
||||
|
||||
#### Error Explanations
|
||||
```bash
|
||||
# error_handler.func provides explanations for core.func
|
||||
explain_exit_code() {
|
||||
local code="$1"
|
||||
case "$code" in
|
||||
1) echo "General error" ;;
|
||||
2) echo "Misuse of shell builtins" ;;
|
||||
126) echo "Command invoked cannot execute" ;;
|
||||
127) echo "Command not found" ;;
|
||||
128) echo "Invalid argument to exit" ;;
|
||||
*) echo "Unknown error code" ;;
|
||||
esac
|
||||
}
|
||||
```
|
||||
|
||||
### With install.func
|
||||
|
||||
#### Installation Process
|
||||
```bash
|
||||
# install.func uses core.func for installation
|
||||
source core.func
|
||||
|
||||
# System checks
|
||||
pve_check
|
||||
root_check
|
||||
|
||||
# Installation steps
|
||||
msg_info "Installing packages..."
|
||||
silent apt-get update
|
||||
silent apt-get install -y package
|
||||
|
||||
msg_ok "Installation completed"
|
||||
```
|
||||
|
||||
### With alpine-install.func
|
||||
|
||||
#### Alpine-Specific Operations
|
||||
```bash
|
||||
# alpine-install.func uses core.func for Alpine operations
|
||||
source core.func
|
||||
|
||||
# Alpine detection
|
||||
if is_alpine; then
|
||||
msg_info "Detected Alpine Linux"
|
||||
silent apk add --no-cache package
|
||||
else
|
||||
msg_info "Detected Debian-based system"
|
||||
silent apt-get install -y package
|
||||
fi
|
||||
```
|
||||
|
||||
### With alpine-tools.func
|
||||
|
||||
#### Alpine Utilities
|
||||
```bash
|
||||
# alpine-tools.func uses core.func for Alpine tools
|
||||
source core.func
|
||||
|
||||
# Alpine-specific operations
|
||||
if is_alpine; then
|
||||
msg_info "Running Alpine-specific operations..."
|
||||
# Alpine tools logic
|
||||
msg_ok "Alpine operations completed"
|
||||
fi
|
||||
```
|
||||
|
||||
### With passthrough.func
|
||||
|
||||
#### Hardware Passthrough
|
||||
```bash
|
||||
# passthrough.func uses core.func for hardware operations
|
||||
source core.func
|
||||
|
||||
# System checks
|
||||
pve_check
|
||||
root_check
|
||||
|
||||
# Hardware operations
|
||||
msg_info "Configuring GPU passthrough..."
|
||||
if silent lspci | grep -i nvidia; then
|
||||
msg_ok "NVIDIA GPU detected"
|
||||
else
|
||||
msg_warn "No NVIDIA GPU found"
|
||||
fi
|
||||
```
|
||||
|
||||
### With vm-core.func
|
||||
|
||||
#### VM Operations
|
||||
```bash
|
||||
# vm-core.func uses core.func for VM management
|
||||
source core.func
|
||||
|
||||
# System checks
|
||||
pve_check
|
||||
root_check
|
||||
|
||||
# VM operations
|
||||
msg_info "Creating virtual machine..."
|
||||
silent qm create "$VMID" \
|
||||
--name "$VMNAME" \
|
||||
--memory "$MEMORY" \
|
||||
--cores "$CORES"
|
||||
|
||||
msg_ok "Virtual machine created"
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Input Data
|
||||
|
||||
#### Environment Variables
|
||||
- **`APP`**: Application name for header display
|
||||
- **`APP_TYPE`**: Application type (ct/vm) for header paths
|
||||
- **`VERBOSE`**: Verbose mode setting
|
||||
- **`var_os`**: OS type for Alpine detection
|
||||
- **`PCT_OSTYPE`**: Alternative OS type variable
|
||||
- **`var_verbose`**: Alternative verbose setting
|
||||
- **`var_full_verbose`**: Debug mode setting
|
||||
|
||||
#### Command Parameters
|
||||
- **Function arguments**: Passed to individual functions
|
||||
- **Command arguments**: Passed to `silent()` function
|
||||
- **User input**: Collected via `read` commands
|
||||
|
||||
### Processing Data
|
||||
|
||||
#### System Information
|
||||
- **Proxmox version**: Parsed from `pveversion` output
|
||||
- **Architecture**: Retrieved from `dpkg --print-architecture`
|
||||
- **Shell type**: Detected from process information
|
||||
- **User ID**: Retrieved from `id -u`
|
||||
- **SSH connection**: Detected from `SSH_CLIENT` environment
|
||||
|
||||
#### UI State
|
||||
- **Message tracking**: `MSG_INFO_SHOWN` associative array
|
||||
- **Spinner state**: `SPINNER_PID` and `SPINNER_MSG` variables
|
||||
- **Terminal state**: Cursor position and display mode
|
||||
|
||||
#### Error Information
|
||||
- **Exit codes**: Captured from command execution
|
||||
- **Log output**: Redirected to temporary log files
|
||||
- **Error explanations**: Retrieved from error_handler.func
|
||||
|
||||
### Output Data
|
||||
|
||||
#### User Interface
|
||||
- **Colored messages**: ANSI color codes for terminal output
|
||||
- **Icons**: Symbolic representations for different message types
|
||||
- **Spinners**: Animated progress indicators
|
||||
- **Formatted text**: Consistent message formatting
|
||||
|
||||
#### System State
|
||||
- **Exit codes**: Returned from functions
|
||||
- **Log files**: Created for silent execution
|
||||
- **Configuration**: Modified system settings
|
||||
- **Process state**: Spinner processes and cleanup
|
||||
|
||||
## API Surface
|
||||
|
||||
### Public Functions
|
||||
|
||||
#### System Validation
|
||||
- **`pve_check()`**: Proxmox VE version validation
|
||||
- **`arch_check()`**: Architecture validation
|
||||
- **`shell_check()`**: Shell validation
|
||||
- **`root_check()`**: Privilege validation
|
||||
- **`ssh_check()`**: SSH connection warning
|
||||
|
||||
#### User Interface
|
||||
- **`msg_info()`**: Informational messages
|
||||
- **`msg_ok()`**: Success messages
|
||||
- **`msg_error()`**: Error messages
|
||||
- **`msg_warn()`**: Warning messages
|
||||
- **`msg_custom()`**: Custom messages
|
||||
- **`msg_debug()`**: Debug messages
|
||||
|
||||
#### Spinner Control
|
||||
- **`spinner()`**: Start spinner animation
|
||||
- **`stop_spinner()`**: Stop spinner and cleanup
|
||||
- **`clear_line()`**: Clear current terminal line
|
||||
|
||||
#### Silent Execution
|
||||
- **`silent()`**: Execute commands with error handling
|
||||
|
||||
#### Utility Functions
|
||||
- **`is_alpine()`**: Alpine Linux detection
|
||||
- **`is_verbose_mode()`**: Verbose mode detection
|
||||
- **`fatal()`**: Fatal error handling
|
||||
- **`ensure_tput()`**: Terminal control setup
|
||||
|
||||
#### Header Management
|
||||
- **`get_header()`**: Download application headers
|
||||
- **`header_info()`**: Display header information
|
||||
|
||||
#### System Management
|
||||
- **`check_or_create_swap()`**: Swap file management
|
||||
|
||||
### Internal Functions
|
||||
|
||||
#### Initialization
|
||||
- **`load_functions()`**: Function loader
|
||||
- **`color()`**: Color setup
|
||||
- **`formatting()`**: Formatting setup
|
||||
- **`icons()`**: Icon setup
|
||||
- **`default_vars()`**: Default variables
|
||||
- **`set_std_mode()`**: Standard mode setup
|
||||
|
||||
#### Color Management
|
||||
- **`color_spinner()`**: Spinner colors
|
||||
|
||||
### Global Variables
|
||||
|
||||
#### Color Variables
|
||||
- **`YW`**, **`YWB`**, **`BL`**, **`RD`**, **`BGN`**, **`GN`**, **`DGN`**, **`CL`**: Color codes
|
||||
- **`CS_YW`**, **`CS_YWB`**, **`CS_CL`**: Spinner colors
|
||||
|
||||
#### Formatting Variables
|
||||
- **`BFR`**, **`BOLD`**, **`HOLD`**, **`TAB`**, **`TAB3`**: Formatting helpers
|
||||
|
||||
#### Icon Variables
|
||||
- **`CM`**, **`CROSS`**, **`INFO`**, **`OS`**, **`OSVERSION`**, etc.: Message icons
|
||||
|
||||
#### Configuration Variables
|
||||
- **`RETRY_NUM`**, **`RETRY_EVERY`**: Retry settings
|
||||
- **`STD`**: Standard mode setting
|
||||
- **`SILENT_LOGFILE`**: Log file path
|
||||
|
||||
#### State Variables
|
||||
- **`_CORE_FUNC_LOADED`**: Loading prevention
|
||||
- **`__FUNCTIONS_LOADED`**: Function loading prevention
|
||||
- **`SPINNER_PID`**, **`SPINNER_MSG`**: Spinner state
|
||||
- **`MSG_INFO_SHOWN`**: Message tracking
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Standard Integration Pattern
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Standard integration pattern
|
||||
|
||||
# 1. Source core.func first
|
||||
source core.func
|
||||
|
||||
# 2. Run system checks
|
||||
pve_check
|
||||
arch_check
|
||||
shell_check
|
||||
root_check
|
||||
|
||||
# 3. Set up error handling
|
||||
trap 'stop_spinner' EXIT INT TERM
|
||||
|
||||
# 4. Use UI functions
|
||||
msg_info "Starting operation..."
|
||||
|
||||
# 5. Use silent execution
|
||||
silent command
|
||||
|
||||
# 6. Show completion
|
||||
msg_ok "Operation completed"
|
||||
```
|
||||
|
||||
### Minimal Integration Pattern
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Minimal integration pattern
|
||||
|
||||
source core.func
|
||||
pve_check
|
||||
root_check
|
||||
|
||||
msg_info "Running operation..."
|
||||
silent command
|
||||
msg_ok "Operation completed"
|
||||
```
|
||||
|
||||
### Advanced Integration Pattern
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Advanced integration pattern
|
||||
|
||||
source core.func
|
||||
|
||||
# System validation
|
||||
pve_check
|
||||
arch_check
|
||||
shell_check
|
||||
root_check
|
||||
ssh_check
|
||||
|
||||
# Error handling
|
||||
trap 'stop_spinner' EXIT INT TERM
|
||||
|
||||
# Verbose mode handling
|
||||
if is_verbose_mode; then
|
||||
msg_info "Verbose mode enabled"
|
||||
fi
|
||||
|
||||
# OS-specific operations
|
||||
if is_alpine; then
|
||||
msg_info "Alpine Linux detected"
|
||||
# Alpine-specific logic
|
||||
else
|
||||
msg_info "Debian-based system detected"
|
||||
# Debian-specific logic
|
||||
fi
|
||||
|
||||
# Operation execution
|
||||
msg_info "Starting operation..."
|
||||
if silent command; then
|
||||
msg_ok "Operation succeeded"
|
||||
else
|
||||
msg_error "Operation failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Error Handling Integration
|
||||
|
||||
### Silent Execution Error Flow
|
||||
|
||||
```
|
||||
silent() command
|
||||
├── Execute command
|
||||
├── Capture output to log
|
||||
├── Check exit code
|
||||
├── If error:
|
||||
│ ├── Load error_handler.func
|
||||
│ ├── Get error explanation
|
||||
│ ├── Display error details
|
||||
│ ├── Show log excerpt
|
||||
│ └── Exit with error code
|
||||
└── If success: Continue
|
||||
```
|
||||
|
||||
### System Check Error Flow
|
||||
|
||||
```
|
||||
System Check Function
|
||||
├── Check system state
|
||||
├── If valid: Return 0
|
||||
└── If invalid:
|
||||
├── Display error message
|
||||
├── Show fix instructions
|
||||
├── Sleep for user to read
|
||||
└── Exit with error code
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Loading Optimization
|
||||
- **Single Loading**: `_CORE_FUNC_LOADED` prevents multiple loading
|
||||
- **Function Loading**: `__FUNCTIONS_LOADED` prevents multiple function loading
|
||||
- **Lazy Loading**: Functions loaded only when needed
|
||||
|
||||
### Memory Usage
|
||||
- **Minimal Footprint**: Core functions use minimal memory
|
||||
- **Variable Reuse**: Global variables reused across functions
|
||||
- **Cleanup**: Spinner processes cleaned up on exit
|
||||
|
||||
### Execution Speed
|
||||
- **Fast Checks**: System checks are optimized for speed
|
||||
- **Efficient Spinners**: Spinner animation uses minimal CPU
|
||||
- **Quick Messages**: Message functions optimized for performance
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Privilege Escalation
|
||||
- **Root Check**: Ensures script runs with sufficient privileges
|
||||
- **Shell Check**: Validates shell environment
|
||||
- **Process Validation**: Checks parent process for sudo usage
|
||||
|
||||
### Input Validation
|
||||
- **Parameter Checking**: Functions validate input parameters
|
||||
- **Error Handling**: Proper error handling prevents crashes
|
||||
- **Safe Execution**: Silent execution with proper error handling
|
||||
|
||||
### System Protection
|
||||
- **Version Validation**: Ensures compatible Proxmox version
|
||||
- **Architecture Check**: Prevents execution on unsupported systems
|
||||
- **SSH Warning**: Warns about external SSH usage
|
||||
|
||||
## Future Integration Considerations
|
||||
|
||||
### Extensibility
|
||||
- **Function Groups**: Easy to add new function groups
|
||||
- **Message Types**: Easy to add new message types
|
||||
- **System Checks**: Easy to add new system checks
|
||||
|
||||
### Compatibility
|
||||
- **Version Support**: Easy to add new Proxmox versions
|
||||
- **OS Support**: Easy to add new operating systems
|
||||
- **Architecture Support**: Easy to add new architectures
|
||||
|
||||
### Performance
|
||||
- **Optimization**: Functions can be optimized for better performance
|
||||
- **Caching**: Results can be cached for repeated operations
|
||||
- **Parallelization**: Operations can be parallelized where appropriate
|
||||
Reference in New Issue
Block a user