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
316
docs/misc/core.func/CORE_FLOWCHART.md
Normal file
316
docs/misc/core.func/CORE_FLOWCHART.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# core.func Execution Flowchart
|
||||
|
||||
## Main Execution Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ core.func Loading │
|
||||
│ Entry point when core.func is sourced by other scripts │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Load Prevention Check │
|
||||
│ • Check if _CORE_FUNC_LOADED is set │
|
||||
│ • Return early if already loaded │
|
||||
│ • Set _CORE_FUNC_LOADED=1 to prevent reloading │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ LOAD_FUNCTIONS() │
|
||||
│ Main function loader - sets up all core utilities │
|
||||
└─────────────────────┬───────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Core Function Loading Sequence │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │
|
||||
│ │ color() │ │ formatting() │ │ icons() │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Set ANSI │ │ • Set format │ │ • Set symbolic icons │ │
|
||||
│ │ color codes │ │ helpers │ │ • Define message │ │
|
||||
│ │ • Define │ │ • Tab, bold, │ │ symbols │ │
|
||||
│ │ colors │ │ line reset │ │ • Status indicators │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │
|
||||
│ │ default_vars() │ │ set_std_mode() │ │ Additional Functions │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Set retry │ │ • Set verbose │ │ • Add more functions │ │
|
||||
│ │ variables │ │ mode │ │ as needed │ │
|
||||
│ │ • Initialize │ │ • Configure │ │ │ │
|
||||
│ │ counters │ │ STD variable │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## System Check Functions Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ System Validation Flow │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ PVE_CHECK() │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Get PVE │ │ Check PVE │ │ Check PVE │ │ │
|
||||
│ │ │ Version │ │ 8.x Support │ │ 9.x Support │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • pveversion │ │ • Allow 8.0-8.9│ │ • Allow ONLY 9.0 │ │ │
|
||||
│ │ │ • Parse version │ │ • Reject others │ │ • Reject 9.1+ │ │ │
|
||||
│ │ │ • Extract │ │ • Exit if │ │ • Exit if │ │ │
|
||||
│ │ │ major.minor │ │ unsupported │ │ unsupported │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ ARCH_CHECK() │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check │ │ AMD64 Check │ │ PiMox Warning │ │ │
|
||||
│ │ │ Architecture │ │ │ │ │ │ │
|
||||
│ │ │ │ │ • dpkg --print- │ │ • Show PiMox │ │ │
|
||||
│ │ │ • Get system │ │ architecture │ │ message │ │ │
|
||||
│ │ │ architecture │ │ • Must be │ │ • Point to ARM64 │ │ │
|
||||
│ │ │ • Compare with │ │ "amd64" │ │ support │ │ │
|
||||
│ │ │ "amd64" │ │ • Exit if not │ │ • Exit script │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ SHELL_CHECK() │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check │ │ Bash Check │ │ Error Handling │ │ │
|
||||
│ │ │ Shell Type │ │ │ │ │ │ │
|
||||
│ │ │ │ │ • ps -p $$ -o │ │ • Clear screen │ │ │
|
||||
│ │ │ • Get current │ │ comm= │ │ • Show error │ │ │
|
||||
│ │ │ shell │ │ • Must be │ │ • Sleep and exit │ │ │
|
||||
│ │ │ • Compare with │ │ "bash" │ │ │ │ │
|
||||
│ │ │ "bash" │ │ • Exit if not │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ ROOT_CHECK() │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check │ │ Root Check │ │ Sudo Check │ │ │
|
||||
│ │ │ User ID │ │ │ │ │ │ │
|
||||
│ │ │ │ │ • id -u │ │ • Check parent │ │ │
|
||||
│ │ │ • Get user ID │ │ • Must be 0 │ │ process │ │ │
|
||||
│ │ │ • Check if │ │ • Exit if not │ │ • Detect sudo │ │ │
|
||||
│ │ │ root (0) │ │ root │ │ usage │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Message System Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Message System Flow │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ MSG_INFO() │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Message │ │ Duplicate │ │ Display Mode │ │ │
|
||||
│ │ │ Validation │ │ Check │ │ Selection │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Check if │ │ • Track shown │ │ • Verbose mode: │ │ │
|
||||
│ │ │ message │ │ messages │ │ Show directly │ │ │
|
||||
│ │ │ exists │ │ • Skip if │ │ • Normal mode: │ │ │
|
||||
│ │ │ • Return if │ │ already │ │ Start spinner │ │ │
|
||||
│ │ │ empty │ │ shown │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ SPINNER() │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Spinner │ │ Animation │ │ Display │ │ │
|
||||
│ │ │ Initialization│ │ Loop │ │ Control │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Define │ │ • Cycle through │ │ • Print spinner │ │ │
|
||||
│ │ │ characters │ │ characters │ │ character │ │ │
|
||||
│ │ │ • Set index │ │ • Sleep 0.1s │ │ • Print message │ │ │
|
||||
│ │ │ • Start loop │ │ • Increment │ │ • Clear line │ │ │
|
||||
│ │ │ │ │ index │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ STOP_SPINNER() │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Get Spinner │ │ Kill Process │ │ Cleanup │ │ │
|
||||
│ │ │ PID │ │ │ │ │ │ │
|
||||
│ │ │ │ │ • Send TERM │ │ • Remove PID file │ │ │
|
||||
│ │ │ • From │ │ • Wait for │ │ • Unset variables │ │ │
|
||||
│ │ │ SPINNER_PID │ │ termination │ │ • Reset terminal │ │ │
|
||||
│ │ │ • From PID │ │ • Force kill │ │ settings │ │ │
|
||||
│ │ │ file │ │ if needed │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Silent Execution Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ SILENT() Execution Flow │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Command Execution │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Setup │ │ Execute │ │ Capture Output │ │ │
|
||||
│ │ │ Environment │ │ Command │ │ │ │ │
|
||||
│ │ │ │ │ │ │ • Redirect stdout │ │ │
|
||||
│ │ │ • Disable │ │ • Run command │ │ to log file │ │ │
|
||||
│ │ │ error │ │ • Capture │ │ • Redirect stderr │ │ │
|
||||
│ │ │ handling │ │ return code │ │ to log file │ │ │
|
||||
│ │ │ • Remove │ │ • Store exit │ │ • Log all output │ │ │
|
||||
│ │ │ traps │ │ code │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Error Handling │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check Exit │ │ Load Error │ │ Display Error │ │ │
|
||||
│ │ │ Code │ │ Handler │ │ Information │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • If exit code │ │ • Source │ │ • Show error code │ │ │
|
||||
│ │ │ != 0 │ │ error_handler │ │ • Show explanation │ │ │
|
||||
│ │ │ • Proceed to │ │ if needed │ │ • Show command │ │ │
|
||||
│ │ │ error │ │ • Get error │ │ • Show log lines │ │ │
|
||||
│ │ │ handling │ │ explanation │ │ • Show full log │ │ │
|
||||
│ │ │ │ │ │ │ command │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Log Management │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Log File │ │ Log Display │ │ Log Access │ │ │
|
||||
│ │ │ Management │ │ │ │ │ │ │
|
||||
│ │ │ │ │ • Show last 10 │ │ • Provide command │ │ │
|
||||
│ │ │ • Create log │ │ lines │ │ to view full log │ │ │
|
||||
│ │ │ file path │ │ • Count total │ │ • Show line count │ │ │
|
||||
│ │ │ • Use process │ │ lines │ │ • Enable debugging │ │ │
|
||||
│ │ │ ID in name │ │ • Format │ │ │ │ │
|
||||
│ │ │ │ │ output │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Header Management Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Header Management Flow │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ GET_HEADER() │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Prepare │ │ Check Local │ │ Download Header │ │ │
|
||||
│ │ │ Parameters │ │ File │ │ │ │ │
|
||||
│ │ │ │ │ │ │ • Construct URL │ │ │
|
||||
│ │ │ • Get app name │ │ • Check if │ │ • Download file │ │ │
|
||||
│ │ │ from APP │ │ file exists │ │ • Save to local │ │ │
|
||||
│ │ │ • Get app type │ │ • Check if │ │ path │ │ │
|
||||
│ │ │ from APP_TYPE │ │ file has │ │ • Return success │ │ │
|
||||
│ │ │ • Construct │ │ content │ │ status │ │ │
|
||||
│ │ │ paths │ │ • Return if │ │ │ │ │
|
||||
│ │ │ │ │ available │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ HEADER_INFO() │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Get Header │ │ Clear Screen │ │ Display Header │ │ │
|
||||
│ │ │ Content │ │ │ │ │ │ │
|
||||
│ │ │ │ │ • Clear │ │ • Show header │ │ │
|
||||
│ │ │ • Call │ │ terminal │ │ content if │ │ │
|
||||
│ │ │ get_header() │ │ • Get terminal │ │ available │ │ │
|
||||
│ │ │ • Handle │ │ width │ │ • Format output │ │ │
|
||||
│ │ │ errors │ │ • Set default │ │ • Center content │ │ │
|
||||
│ │ │ • Return │ │ width if │ │ if possible │ │ │
|
||||
│ │ │ content │ │ needed │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Swap Management Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ CHECK_OR_CREATE_SWAP() Flow │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Swap Detection │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ Check Active │ │ Swap Found │ │ No Swap Found │ │ │
|
||||
│ │ │ Swap │ │ │ │ │ │ │
|
||||
│ │ │ │ │ • Show success │ │ • Show error │ │ │
|
||||
│ │ │ • Use swapon │ │ message │ │ message │ │ │
|
||||
│ │ │ command │ │ • Return 0 │ │ • Ask user for │ │ │
|
||||
│ │ │ • Check for │ │ │ │ creation │ │ │
|
||||
│ │ │ swap devices │ │ │ │ • Proceed to │ │ │
|
||||
│ │ │ • Return │ │ │ │ creation flow │ │ │
|
||||
│ │ │ status │ │ │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Swap Creation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
|
||||
│ │ │ User Input │ │ Size │ │ File Creation │ │ │
|
||||
│ │ │ Collection │ │ Validation │ │ │ │ │
|
||||
│ │ │ │ │ │ │ • Create swap file │ │ │
|
||||
│ │ │ • Ask for │ │ • Validate │ │ with dd │ │ │
|
||||
│ │ │ confirmation │ │ numeric input │ │ • Set permissions │ │ │
|
||||
│ │ │ • Convert to │ │ • Check range │ │ • Format swap │ │ │
|
||||
│ │ │ lowercase │ │ • Abort if │ │ • Activate swap │ │ │
|
||||
│ │ │ • Check for │ │ invalid │ │ • Show success │ │ │
|
||||
│ │ │ y/yes │ │ │ │ message │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### With Other Scripts
|
||||
- **build.func**: Provides system checks and UI functions
|
||||
- **tools.func**: Uses core utilities for extended operations
|
||||
- **api.func**: Uses system checks and error handling
|
||||
- **error_handler.func**: Provides error explanations for silent execution
|
||||
|
||||
### External Dependencies
|
||||
- **curl**: For downloading header files
|
||||
- **tput**: For terminal control (installed if missing)
|
||||
- **swapon/mkswap**: For swap management
|
||||
- **pveversion**: For Proxmox version checking
|
||||
|
||||
### Data Flow
|
||||
- **Input**: Environment variables, command parameters
|
||||
- **Processing**: System validation, UI rendering, command execution
|
||||
- **Output**: Messages, log files, exit codes, system state changes
|
||||
637
docs/misc/core.func/CORE_FUNCTIONS_REFERENCE.md
Normal file
637
docs/misc/core.func/CORE_FUNCTIONS_REFERENCE.md
Normal file
@@ -0,0 +1,637 @@
|
||||
# core.func Functions Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive alphabetical reference of all functions in `core.func`, including parameters, dependencies, usage examples, and error handling.
|
||||
|
||||
## Function Categories
|
||||
|
||||
### Initialization Functions
|
||||
|
||||
#### `load_functions()`
|
||||
**Purpose**: Main function loader that initializes all core utilities
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Sets `__FUNCTIONS_LOADED=1` to prevent reloading
|
||||
- Calls all core function groups in sequence
|
||||
- Initializes color, formatting, icons, defaults, and standard mode
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `__FUNCTIONS_LOADED`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
# Automatically called when core.func is sourced
|
||||
source core.func
|
||||
# load_functions() is called automatically
|
||||
```
|
||||
|
||||
### Color and Formatting Functions
|
||||
|
||||
#### `color()`
|
||||
**Purpose**: Set ANSI color codes for styled terminal output
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets global color variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Sets Variables**:
|
||||
- `YW`: Yellow
|
||||
- `YWB`: Bright yellow
|
||||
- `BL`: Blue
|
||||
- `RD`: Red
|
||||
- `BGN`: Bright green
|
||||
- `GN`: Green
|
||||
- `DGN`: Dark green
|
||||
- `CL`: Clear/reset
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
color
|
||||
echo -e "${GN}Success message${CL}"
|
||||
echo -e "${RD}Error message${CL}"
|
||||
```
|
||||
|
||||
#### `color_spinner()`
|
||||
**Purpose**: Set color codes specifically for spinner output
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets spinner-specific color variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Sets Variables**:
|
||||
- `CS_YW`: Yellow for spinner
|
||||
- `CS_YWB`: Bright yellow for spinner
|
||||
- `CS_CL`: Clear for spinner
|
||||
|
||||
#### `formatting()`
|
||||
**Purpose**: Define formatting helpers for terminal output
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets global formatting variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Sets Variables**:
|
||||
- `BFR`: Back and forward reset
|
||||
- `BOLD`: Bold text
|
||||
- `HOLD`: Space character
|
||||
- `TAB`: Two spaces
|
||||
- `TAB3`: Six spaces
|
||||
|
||||
### Icon Functions
|
||||
|
||||
#### `icons()`
|
||||
**Purpose**: Set symbolic icons used throughout user feedback and prompts
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets global icon variables
|
||||
**Dependencies**: `formatting()` (for TAB variable)
|
||||
**Environment Variables Used**: `TAB`, `CL`
|
||||
|
||||
**Sets Variables**:
|
||||
- `CM`: Check mark
|
||||
- `CROSS`: Cross mark
|
||||
- `DNSOK`: DNS success
|
||||
- `DNSFAIL`: DNS failure
|
||||
- `INFO`: Information icon
|
||||
- `OS`: Operating system icon
|
||||
- `OSVERSION`: OS version icon
|
||||
- `CONTAINERTYPE`: Container type icon
|
||||
- `DISKSIZE`: Disk size icon
|
||||
- `CPUCORE`: CPU core icon
|
||||
- `RAMSIZE`: RAM size icon
|
||||
- `SEARCH`: Search icon
|
||||
- `VERBOSE_CROPPED`: Verbose mode icon
|
||||
- `VERIFYPW`: Password verification icon
|
||||
- `CONTAINERID`: Container ID icon
|
||||
- `HOSTNAME`: Hostname icon
|
||||
- `BRIDGE`: Bridge icon
|
||||
- `NETWORK`: Network icon
|
||||
- `GATEWAY`: Gateway icon
|
||||
- `DISABLEIPV6`: IPv6 disable icon
|
||||
- `DEFAULT`: Default settings icon
|
||||
- `MACADDRESS`: MAC address icon
|
||||
- `VLANTAG`: VLAN tag icon
|
||||
- `ROOTSSH`: SSH key icon
|
||||
- `CREATING`: Creating icon
|
||||
- `ADVANCED`: Advanced settings icon
|
||||
- `FUSE`: FUSE icon
|
||||
- `HOURGLASS`: Hourglass icon
|
||||
|
||||
### Default Variables Functions
|
||||
|
||||
#### `default_vars()`
|
||||
**Purpose**: Set default retry and wait variables for system actions
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets retry configuration variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Sets Variables**:
|
||||
- `RETRY_NUM`: Number of retry attempts (default: 10)
|
||||
- `RETRY_EVERY`: Seconds between retries (default: 3)
|
||||
- `i`: Retry counter initialized to RETRY_NUM
|
||||
|
||||
#### `set_std_mode()`
|
||||
**Purpose**: Set default verbose mode for script execution
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Sets STD variable based on VERBOSE setting
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `VERBOSE`
|
||||
|
||||
**Sets Variables**:
|
||||
- `STD`: "silent" if VERBOSE != "yes", empty string if VERBOSE = "yes"
|
||||
|
||||
### Silent Execution Functions
|
||||
|
||||
#### `silent()`
|
||||
**Purpose**: Execute commands silently with detailed error reporting
|
||||
**Parameters**: `$*` - Command and arguments to execute
|
||||
**Returns**: None (exits on error)
|
||||
**Side Effects**:
|
||||
- Executes command with output redirected to log file
|
||||
- On error, displays detailed error information
|
||||
- Exits with command's exit code
|
||||
**Dependencies**: `error_handler.func` (for error explanations)
|
||||
**Environment Variables Used**: `SILENT_LOGFILE`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
silent apt-get update
|
||||
silent apt-get install -y package-name
|
||||
```
|
||||
|
||||
**Error Handling**:
|
||||
- Captures command output to `/tmp/silent.$$.log`
|
||||
- Shows error code explanation
|
||||
- Displays last 10 lines of log
|
||||
- Provides command to view full log
|
||||
|
||||
### System Check Functions
|
||||
|
||||
#### `shell_check()`
|
||||
**Purpose**: Verify that the script is running in Bash shell
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits if not Bash)
|
||||
**Side Effects**:
|
||||
- Checks current shell process
|
||||
- Exits with error message if not Bash
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
shell_check
|
||||
# Script continues if Bash, exits if not
|
||||
```
|
||||
|
||||
#### `root_check()`
|
||||
**Purpose**: Ensure script is running as root user
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits if not root)
|
||||
**Side Effects**:
|
||||
- Checks user ID and parent process
|
||||
- Exits with error message if not root
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
root_check
|
||||
# Script continues if root, exits if not
|
||||
```
|
||||
|
||||
#### `pve_check()`
|
||||
**Purpose**: Verify Proxmox VE version compatibility
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits if unsupported version)
|
||||
**Side Effects**:
|
||||
- Checks PVE version using pveversion command
|
||||
- Exits with error message if unsupported
|
||||
**Dependencies**: `pveversion` command
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Supported Versions**:
|
||||
- Proxmox VE 8.0 - 8.9
|
||||
- Proxmox VE 9.0 (only)
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
pve_check
|
||||
# Script continues if supported version, exits if not
|
||||
```
|
||||
|
||||
#### `arch_check()`
|
||||
**Purpose**: Verify system architecture is AMD64
|
||||
**Parameters**: None
|
||||
**Returns**: None (exits if not AMD64)
|
||||
**Side Effects**:
|
||||
- Checks system architecture
|
||||
- Exits with PiMox warning if not AMD64
|
||||
**Dependencies**: `dpkg` command
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
arch_check
|
||||
# Script continues if AMD64, exits if not
|
||||
```
|
||||
|
||||
#### `ssh_check()`
|
||||
**Purpose**: Detect and warn about external SSH usage
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Checks SSH_CLIENT environment variable
|
||||
- Warns if connecting from external IP
|
||||
- Allows local connections (127.0.0.1 or host IP)
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `SSH_CLIENT`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
ssh_check
|
||||
# Shows warning if external SSH, continues anyway
|
||||
```
|
||||
|
||||
### Header Management Functions
|
||||
|
||||
#### `get_header()`
|
||||
**Purpose**: Download and cache application header files
|
||||
**Parameters**: None (uses APP and APP_TYPE variables)
|
||||
**Returns**: Header content on success, empty on failure
|
||||
**Side Effects**:
|
||||
- Downloads header from remote URL
|
||||
- Caches header locally
|
||||
- Creates directory structure if needed
|
||||
**Dependencies**: `curl` command
|
||||
**Environment Variables Used**: `APP`, `APP_TYPE`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
export APP="plex"
|
||||
export APP_TYPE="ct"
|
||||
header_content=$(get_header)
|
||||
```
|
||||
|
||||
#### `header_info()`
|
||||
**Purpose**: Display application header information
|
||||
**Parameters**: None (uses APP variable)
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Clears screen
|
||||
- Displays header content
|
||||
- Gets terminal width for formatting
|
||||
**Dependencies**: `get_header()`, `tput` command
|
||||
**Environment Variables Used**: `APP`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
export APP="plex"
|
||||
header_info
|
||||
# Displays Plex header information
|
||||
```
|
||||
|
||||
### Utility Functions
|
||||
|
||||
#### `ensure_tput()`
|
||||
**Purpose**: Ensure tput command is available for terminal control
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Installs ncurses package if tput missing
|
||||
- Works on Alpine and Debian-based systems
|
||||
**Dependencies**: `apk` or `apt-get` package managers
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
ensure_tput
|
||||
# Installs ncurses if needed, continues if already available
|
||||
```
|
||||
|
||||
#### `is_alpine()`
|
||||
**Purpose**: Detect if running on Alpine Linux
|
||||
**Parameters**: None
|
||||
**Returns**: 0 if Alpine, 1 if not Alpine
|
||||
**Side Effects**: None
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `var_os`, `PCT_OSTYPE`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
if is_alpine; then
|
||||
echo "Running on Alpine Linux"
|
||||
else
|
||||
echo "Not running on Alpine Linux"
|
||||
fi
|
||||
```
|
||||
|
||||
#### `is_verbose_mode()`
|
||||
**Purpose**: Check if verbose mode is enabled
|
||||
**Parameters**: None
|
||||
**Returns**: 0 if verbose mode, 1 if not verbose
|
||||
**Side Effects**: None
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `VERBOSE`, `var_verbose`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
if is_verbose_mode; then
|
||||
echo "Verbose mode enabled"
|
||||
else
|
||||
echo "Verbose mode disabled"
|
||||
fi
|
||||
```
|
||||
|
||||
#### `fatal()`
|
||||
**Purpose**: Display fatal error and terminate script
|
||||
**Parameters**: `$1` - Error message
|
||||
**Returns**: None (terminates script)
|
||||
**Side Effects**:
|
||||
- Displays error message
|
||||
- Sends INT signal to current process
|
||||
**Dependencies**: `msg_error()`
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
fatal "Critical error occurred"
|
||||
# Script terminates after displaying error
|
||||
```
|
||||
|
||||
### Spinner Functions
|
||||
|
||||
#### `spinner()`
|
||||
**Purpose**: Display animated spinner for progress indication
|
||||
**Parameters**: None (uses SPINNER_MSG variable)
|
||||
**Returns**: None (runs indefinitely)
|
||||
**Side Effects**:
|
||||
- Displays rotating spinner characters
|
||||
- Uses terminal control sequences
|
||||
**Dependencies**: `color_spinner()`
|
||||
**Environment Variables Used**: `SPINNER_MSG`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
SPINNER_MSG="Processing..."
|
||||
spinner &
|
||||
SPINNER_PID=$!
|
||||
# Spinner runs in background
|
||||
```
|
||||
|
||||
#### `clear_line()`
|
||||
**Purpose**: Clear current terminal line
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**: Clears current line using terminal control
|
||||
**Dependencies**: `tput` command
|
||||
**Environment Variables Used**: None
|
||||
|
||||
#### `stop_spinner()`
|
||||
**Purpose**: Stop running spinner and cleanup
|
||||
**Parameters**: None
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Kills spinner process
|
||||
- Removes PID file
|
||||
- Resets terminal settings
|
||||
- Unsets spinner variables
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `SPINNER_PID`, `SPINNER_MSG`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
stop_spinner
|
||||
# Stops spinner and cleans up
|
||||
```
|
||||
|
||||
### Message Functions
|
||||
|
||||
#### `msg_info()`
|
||||
**Purpose**: Display informational message with spinner
|
||||
**Parameters**: `$1` - Message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Starts spinner if not in verbose mode
|
||||
- Tracks shown messages to prevent duplicates
|
||||
- Displays message with hourglass icon in verbose mode
|
||||
**Dependencies**: `spinner()`, `is_verbose_mode()`, `is_alpine()`
|
||||
**Environment Variables Used**: `MSG_INFO_SHOWN`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_info "Installing package..."
|
||||
# Shows spinner with message
|
||||
```
|
||||
|
||||
#### `msg_ok()`
|
||||
**Purpose**: Display success message
|
||||
**Parameters**: `$1` - Success message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Stops spinner
|
||||
- Displays green checkmark with message
|
||||
- Removes message from shown tracking
|
||||
**Dependencies**: `stop_spinner()`
|
||||
**Environment Variables Used**: `MSG_INFO_SHOWN`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_ok "Package installed successfully"
|
||||
# Shows green checkmark with message
|
||||
```
|
||||
|
||||
#### `msg_error()`
|
||||
**Purpose**: Display error message
|
||||
**Parameters**: `$1` - Error message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Stops spinner
|
||||
- Displays red cross with message
|
||||
**Dependencies**: `stop_spinner()`
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_error "Installation failed"
|
||||
# Shows red cross with message
|
||||
```
|
||||
|
||||
#### `msg_warn()`
|
||||
**Purpose**: Display warning message
|
||||
**Parameters**: `$1` - Warning message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Stops spinner
|
||||
- Displays yellow info icon with message
|
||||
**Dependencies**: `stop_spinner()`
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_warn "This operation may take some time"
|
||||
# Shows yellow info icon with message
|
||||
```
|
||||
|
||||
#### `msg_custom()`
|
||||
**Purpose**: Display custom message with specified symbol and color
|
||||
**Parameters**:
|
||||
- `$1` - Custom symbol (default: "[*]")
|
||||
- `$2` - Color code (default: "\e[36m")
|
||||
- `$3` - Message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Stops spinner
|
||||
- Displays custom formatted message
|
||||
**Dependencies**: `stop_spinner()`
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
msg_custom "⚡" "\e[33m" "Custom warning message"
|
||||
# Shows custom symbol and color with message
|
||||
```
|
||||
|
||||
#### `msg_debug()`
|
||||
**Purpose**: Display debug message if debug mode enabled
|
||||
**Parameters**: `$*` - Debug message text
|
||||
**Returns**: None
|
||||
**Side Effects**:
|
||||
- Only displays if var_full_verbose is set
|
||||
- Shows timestamp and debug prefix
|
||||
**Dependencies**: None
|
||||
**Environment Variables Used**: `var_full_verbose`, `var_verbose`
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
export var_full_verbose=1
|
||||
msg_debug "Debug information here"
|
||||
# Shows debug message with timestamp
|
||||
```
|
||||
|
||||
### System Management Functions
|
||||
|
||||
#### `check_or_create_swap()`
|
||||
**Purpose**: Check for active swap and optionally create swap file
|
||||
**Parameters**: None
|
||||
**Returns**: 0 if swap exists or created, 1 if skipped
|
||||
**Side Effects**:
|
||||
- Checks for active swap
|
||||
- Prompts user to create swap if none found
|
||||
- Creates swap file if user confirms
|
||||
**Dependencies**: `swapon`, `dd`, `mkswap` commands
|
||||
**Environment Variables Used**: None
|
||||
|
||||
**Usage Example**:
|
||||
```bash
|
||||
if check_or_create_swap; then
|
||||
echo "Swap is available"
|
||||
else
|
||||
echo "No swap available"
|
||||
fi
|
||||
```
|
||||
|
||||
## Function Call Hierarchy
|
||||
|
||||
### Initialization Flow
|
||||
```
|
||||
load_functions()
|
||||
├── color()
|
||||
├── formatting()
|
||||
├── icons()
|
||||
├── default_vars()
|
||||
└── set_std_mode()
|
||||
```
|
||||
|
||||
### Message System Flow
|
||||
```
|
||||
msg_info()
|
||||
├── is_verbose_mode()
|
||||
├── is_alpine()
|
||||
├── spinner()
|
||||
└── color_spinner()
|
||||
|
||||
msg_ok()
|
||||
├── stop_spinner()
|
||||
└── clear_line()
|
||||
|
||||
msg_error()
|
||||
└── stop_spinner()
|
||||
|
||||
msg_warn()
|
||||
└── stop_spinner()
|
||||
```
|
||||
|
||||
### System Check Flow
|
||||
```
|
||||
pve_check()
|
||||
├── pveversion command
|
||||
└── version parsing
|
||||
|
||||
arch_check()
|
||||
├── dpkg command
|
||||
└── architecture check
|
||||
|
||||
shell_check()
|
||||
├── ps command
|
||||
└── shell detection
|
||||
|
||||
root_check()
|
||||
├── id command
|
||||
└── parent process check
|
||||
```
|
||||
|
||||
### Silent Execution Flow
|
||||
```
|
||||
silent()
|
||||
├── Command execution
|
||||
├── Output redirection
|
||||
├── Error handling
|
||||
├── error_handler.func loading
|
||||
└── Log management
|
||||
```
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### System Check Errors
|
||||
- All system check functions exit with appropriate error messages
|
||||
- Clear indication of what's wrong and how to fix it
|
||||
- Graceful exit with sleep delay for user to read message
|
||||
|
||||
### Silent Execution Errors
|
||||
- Commands executed via `silent()` capture output to log file
|
||||
- On failure, displays error code explanation
|
||||
- Shows last 10 lines of log output
|
||||
- Provides command to view full log
|
||||
|
||||
### Spinner Errors
|
||||
- Spinner functions handle process cleanup on exit
|
||||
- Trap handlers ensure spinners are stopped
|
||||
- Terminal settings are restored on error
|
||||
|
||||
## Environment Variable Dependencies
|
||||
|
||||
### Required Variables
|
||||
- `APP`: Application name for header display
|
||||
- `APP_TYPE`: Application type (ct/vm) for header paths
|
||||
- `VERBOSE`: Verbose mode setting
|
||||
|
||||
### Optional Variables
|
||||
- `var_os`: OS type for Alpine detection
|
||||
- `PCT_OSTYPE`: Alternative OS type variable
|
||||
- `var_verbose`: Alternative verbose setting
|
||||
- `var_full_verbose`: Debug mode setting
|
||||
|
||||
### Internal Variables
|
||||
- `_CORE_FUNC_LOADED`: Prevents multiple loading
|
||||
- `__FUNCTIONS_LOADED`: Prevents multiple function loading
|
||||
- `SILENT_LOGFILE`: Silent execution log file path
|
||||
- `SPINNER_PID`: Spinner process ID
|
||||
- `SPINNER_MSG`: Spinner message text
|
||||
- `MSG_INFO_SHOWN`: Tracks shown info messages
|
||||
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
|
||||
728
docs/misc/core.func/CORE_USAGE_EXAMPLES.md
Normal file
728
docs/misc/core.func/CORE_USAGE_EXAMPLES.md
Normal file
@@ -0,0 +1,728 @@
|
||||
# core.func Usage Examples
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides practical usage examples for `core.func` functions, covering common scenarios, integration patterns, and best practices.
|
||||
|
||||
## Basic Script Setup
|
||||
|
||||
### Standard Script Initialization
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Standard script setup using core.func
|
||||
|
||||
# Source core functions
|
||||
source core.func
|
||||
|
||||
# Run system checks
|
||||
pve_check
|
||||
arch_check
|
||||
shell_check
|
||||
root_check
|
||||
|
||||
# Optional: Check SSH connection
|
||||
ssh_check
|
||||
|
||||
# Set up error handling
|
||||
trap 'stop_spinner' EXIT INT TERM
|
||||
|
||||
# Your script logic here
|
||||
msg_info "Starting script execution"
|
||||
# ... script code ...
|
||||
msg_ok "Script completed successfully"
|
||||
```
|
||||
|
||||
### Minimal Script Setup
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Minimal setup for simple scripts
|
||||
|
||||
source core.func
|
||||
|
||||
# Basic checks only
|
||||
pve_check
|
||||
root_check
|
||||
|
||||
# Simple execution
|
||||
msg_info "Running operation"
|
||||
# ... your code ...
|
||||
msg_ok "Operation completed"
|
||||
```
|
||||
|
||||
## Message Display Examples
|
||||
|
||||
### Progress Indication
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Show progress with spinner
|
||||
msg_info "Downloading package..."
|
||||
sleep 2
|
||||
msg_ok "Download completed"
|
||||
|
||||
msg_info "Installing package..."
|
||||
sleep 3
|
||||
msg_ok "Installation completed"
|
||||
|
||||
msg_info "Configuring service..."
|
||||
sleep 1
|
||||
msg_ok "Configuration completed"
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Function with error handling
|
||||
install_package() {
|
||||
local package="$1"
|
||||
|
||||
msg_info "Installing $package..."
|
||||
|
||||
if silent apt-get install -y "$package"; then
|
||||
msg_ok "$package installed successfully"
|
||||
return 0
|
||||
else
|
||||
msg_error "Failed to install $package"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Usage
|
||||
if install_package "nginx"; then
|
||||
msg_ok "Nginx installation completed"
|
||||
else
|
||||
msg_error "Nginx installation failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Warning Messages
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Show warnings for potentially dangerous operations
|
||||
msg_warn "This will modify system configuration"
|
||||
read -p "Continue? [y/N]: " confirm
|
||||
|
||||
if [[ "$confirm" =~ ^[yY]$ ]]; then
|
||||
msg_info "Proceeding with modification..."
|
||||
# ... dangerous operation ...
|
||||
msg_ok "Modification completed"
|
||||
else
|
||||
msg_info "Operation cancelled"
|
||||
fi
|
||||
```
|
||||
|
||||
### Custom Messages
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Custom message with specific icon and color
|
||||
msg_custom "🚀" "\e[32m" "Launching application"
|
||||
msg_custom "⚡" "\e[33m" "High performance mode enabled"
|
||||
msg_custom "🔒" "\e[31m" "Security mode activated"
|
||||
```
|
||||
|
||||
### Debug Messages
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Enable debug mode
|
||||
export var_full_verbose=1
|
||||
|
||||
# Debug messages
|
||||
msg_debug "Variable value: $some_variable"
|
||||
msg_debug "Function called: $FUNCNAME"
|
||||
msg_debug "Current directory: $(pwd)"
|
||||
```
|
||||
|
||||
## Silent Execution Examples
|
||||
|
||||
### Package Management
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Update package lists
|
||||
msg_info "Updating package lists..."
|
||||
silent apt-get update
|
||||
|
||||
# Install packages
|
||||
msg_info "Installing required packages..."
|
||||
silent apt-get install -y curl wget git
|
||||
|
||||
# Upgrade packages
|
||||
msg_info "Upgrading packages..."
|
||||
silent apt-get upgrade -y
|
||||
|
||||
msg_ok "Package management completed"
|
||||
```
|
||||
|
||||
### File Operations
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Create directories
|
||||
msg_info "Creating directory structure..."
|
||||
silent mkdir -p /opt/myapp/{config,logs,data}
|
||||
|
||||
# Set permissions
|
||||
msg_info "Setting permissions..."
|
||||
silent chmod 755 /opt/myapp
|
||||
silent chmod 644 /opt/myapp/config/*
|
||||
|
||||
# Copy files
|
||||
msg_info "Copying configuration files..."
|
||||
silent cp config/* /opt/myapp/config/
|
||||
|
||||
msg_ok "File operations completed"
|
||||
```
|
||||
|
||||
### Service Management
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Start service
|
||||
msg_info "Starting service..."
|
||||
silent systemctl start myservice
|
||||
|
||||
# Enable service
|
||||
msg_info "Enabling service..."
|
||||
silent systemctl enable myservice
|
||||
|
||||
# Check service status
|
||||
msg_info "Checking service status..."
|
||||
if silent systemctl is-active --quiet myservice; then
|
||||
msg_ok "Service is running"
|
||||
else
|
||||
msg_error "Service failed to start"
|
||||
fi
|
||||
```
|
||||
|
||||
### Network Operations
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Test network connectivity
|
||||
msg_info "Testing network connectivity..."
|
||||
if silent ping -c 1 8.8.8.8; then
|
||||
msg_ok "Network connectivity confirmed"
|
||||
else
|
||||
msg_error "Network connectivity failed"
|
||||
fi
|
||||
|
||||
# Download files
|
||||
msg_info "Downloading configuration..."
|
||||
silent curl -fsSL https://example.com/config -o /tmp/config
|
||||
|
||||
# Extract archives
|
||||
msg_info "Extracting archive..."
|
||||
silent tar -xzf /tmp/archive.tar.gz -C /opt/
|
||||
```
|
||||
|
||||
## System Check Examples
|
||||
|
||||
### Comprehensive System Validation
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Complete system validation
|
||||
validate_system() {
|
||||
msg_info "Validating system requirements..."
|
||||
|
||||
# Check Proxmox version
|
||||
if pve_check; then
|
||||
msg_ok "Proxmox VE version is supported"
|
||||
fi
|
||||
|
||||
# Check architecture
|
||||
if arch_check; then
|
||||
msg_ok "System architecture is supported"
|
||||
fi
|
||||
|
||||
# Check shell
|
||||
if shell_check; then
|
||||
msg_ok "Shell environment is correct"
|
||||
fi
|
||||
|
||||
# Check privileges
|
||||
if root_check; then
|
||||
msg_ok "Running with sufficient privileges"
|
||||
fi
|
||||
|
||||
# Check SSH connection
|
||||
ssh_check
|
||||
|
||||
msg_ok "System validation completed"
|
||||
}
|
||||
|
||||
# Run validation
|
||||
validate_system
|
||||
```
|
||||
|
||||
### Conditional System Checks
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Check if running in container
|
||||
if [[ -f /.dockerenv ]] || [[ -f /run/.containerenv ]]; then
|
||||
msg_warn "Running inside container"
|
||||
# Skip some checks
|
||||
else
|
||||
# Full system checks
|
||||
pve_check
|
||||
arch_check
|
||||
fi
|
||||
|
||||
# Always check shell and privileges
|
||||
shell_check
|
||||
root_check
|
||||
```
|
||||
|
||||
## Header Management Examples
|
||||
|
||||
### Application Header Display
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Set application information
|
||||
export APP="plex"
|
||||
export APP_TYPE="ct"
|
||||
|
||||
# Display header
|
||||
header_info
|
||||
|
||||
# Continue with application setup
|
||||
msg_info "Setting up Plex Media Server..."
|
||||
```
|
||||
|
||||
### Custom Header Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Get header content
|
||||
export APP="nextcloud"
|
||||
export APP_TYPE="ct"
|
||||
|
||||
header_content=$(get_header)
|
||||
if [[ -n "$header_content" ]]; then
|
||||
echo "Header found:"
|
||||
echo "$header_content"
|
||||
else
|
||||
msg_warn "No header found for $APP"
|
||||
fi
|
||||
```
|
||||
|
||||
## Swap Management Examples
|
||||
|
||||
### Interactive Swap Creation
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Check and create swap
|
||||
if check_or_create_swap; then
|
||||
msg_ok "Swap is available"
|
||||
else
|
||||
msg_warn "No swap available - continuing without swap"
|
||||
fi
|
||||
```
|
||||
|
||||
### Automated Swap Check
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Check swap without prompting
|
||||
check_swap_quiet() {
|
||||
if swapon --noheadings --show | grep -q 'swap'; then
|
||||
msg_ok "Swap is active"
|
||||
return 0
|
||||
else
|
||||
msg_warn "No active swap detected"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
if check_swap_quiet; then
|
||||
msg_info "System has sufficient swap"
|
||||
else
|
||||
msg_warn "Consider adding swap for better performance"
|
||||
fi
|
||||
```
|
||||
|
||||
## Spinner Usage Examples
|
||||
|
||||
### Long-Running Operations
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Long-running operation with spinner
|
||||
long_operation() {
|
||||
msg_info "Processing large dataset..."
|
||||
|
||||
# Simulate long operation
|
||||
for i in {1..100}; do
|
||||
sleep 0.1
|
||||
# Update spinner message periodically
|
||||
if (( i % 20 == 0 )); then
|
||||
SPINNER_MSG="Processing... $i%"
|
||||
fi
|
||||
done
|
||||
|
||||
msg_ok "Dataset processing completed"
|
||||
}
|
||||
|
||||
long_operation
|
||||
```
|
||||
|
||||
### Background Operations
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Background operation with spinner
|
||||
background_operation() {
|
||||
msg_info "Starting background process..."
|
||||
|
||||
# Start spinner
|
||||
SPINNER_MSG="Processing in background..."
|
||||
spinner &
|
||||
SPINNER_PID=$!
|
||||
|
||||
# Do background work
|
||||
sleep 5
|
||||
|
||||
# Stop spinner
|
||||
stop_spinner
|
||||
msg_ok "Background process completed"
|
||||
}
|
||||
|
||||
background_operation
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### With build.func
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Integration with build.func
|
||||
|
||||
source core.func
|
||||
source build.func
|
||||
|
||||
# Use core functions for system validation
|
||||
pve_check
|
||||
arch_check
|
||||
root_check
|
||||
|
||||
# Use build.func for container creation
|
||||
export APP="plex"
|
||||
export CTID="100"
|
||||
# ... container creation ...
|
||||
```
|
||||
|
||||
### With tools.func
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Integration with tools.func
|
||||
|
||||
source core.func
|
||||
source tools.func
|
||||
|
||||
# Use core functions for UI
|
||||
msg_info "Starting maintenance tasks..."
|
||||
|
||||
# Use tools.func for maintenance
|
||||
update_system
|
||||
cleanup_logs
|
||||
optimize_storage
|
||||
|
||||
msg_ok "Maintenance completed"
|
||||
```
|
||||
|
||||
### With error_handler.func
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Integration with error_handler.func
|
||||
|
||||
source core.func
|
||||
source error_handler.func
|
||||
|
||||
# Use core functions for execution
|
||||
msg_info "Running operation..."
|
||||
|
||||
# Silent execution will use error_handler for explanations
|
||||
silent apt-get install -y package
|
||||
|
||||
msg_ok "Operation completed"
|
||||
```
|
||||
|
||||
## Best Practices Examples
|
||||
|
||||
### Error Handling Pattern
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Robust error handling
|
||||
run_with_error_handling() {
|
||||
local operation="$1"
|
||||
local description="$2"
|
||||
|
||||
msg_info "$description"
|
||||
|
||||
if silent "$operation"; then
|
||||
msg_ok "$description completed successfully"
|
||||
return 0
|
||||
else
|
||||
msg_error "$description failed"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Usage
|
||||
run_with_error_handling "apt-get update" "Package list update"
|
||||
run_with_error_handling "apt-get install -y nginx" "Nginx installation"
|
||||
```
|
||||
|
||||
### Verbose Mode Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Handle verbose mode
|
||||
if is_verbose_mode; then
|
||||
msg_info "Verbose mode enabled - showing detailed output"
|
||||
# Show more information
|
||||
else
|
||||
msg_info "Normal mode - showing minimal output"
|
||||
# Show less information
|
||||
fi
|
||||
```
|
||||
|
||||
### Alpine Linux Detection
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Handle different OS types
|
||||
if is_alpine; then
|
||||
msg_info "Detected Alpine Linux"
|
||||
# Use Alpine-specific commands
|
||||
silent apk add --no-cache package
|
||||
else
|
||||
msg_info "Detected Debian-based system"
|
||||
# Use Debian-specific commands
|
||||
silent apt-get install -y package
|
||||
fi
|
||||
```
|
||||
|
||||
### Conditional Execution
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Conditional execution based on system state
|
||||
if [[ -f /etc/nginx/nginx.conf ]]; then
|
||||
msg_warn "Nginx configuration already exists"
|
||||
read -p "Overwrite? [y/N]: " overwrite
|
||||
if [[ "$overwrite" =~ ^[yY]$ ]]; then
|
||||
msg_info "Overwriting configuration..."
|
||||
# ... overwrite logic ...
|
||||
else
|
||||
msg_info "Skipping configuration"
|
||||
fi
|
||||
else
|
||||
msg_info "Creating new Nginx configuration..."
|
||||
# ... create logic ...
|
||||
fi
|
||||
```
|
||||
|
||||
## Advanced Usage Examples
|
||||
|
||||
### Custom Spinner Messages
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Custom spinner with progress
|
||||
download_with_progress() {
|
||||
local url="$1"
|
||||
local file="$2"
|
||||
|
||||
msg_info "Starting download..."
|
||||
|
||||
# Start spinner
|
||||
SPINNER_MSG="Downloading..."
|
||||
spinner &
|
||||
SPINNER_PID=$!
|
||||
|
||||
# Download with progress
|
||||
curl -L "$url" -o "$file" --progress-bar
|
||||
|
||||
# Stop spinner
|
||||
stop_spinner
|
||||
msg_ok "Download completed"
|
||||
}
|
||||
|
||||
download_with_progress "https://example.com/file.tar.gz" "/tmp/file.tar.gz"
|
||||
```
|
||||
|
||||
### Message Deduplication
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Messages are automatically deduplicated
|
||||
for i in {1..5}; do
|
||||
msg_info "Processing item $i"
|
||||
# This message will only show once
|
||||
done
|
||||
|
||||
# Different messages will show separately
|
||||
msg_info "Starting phase 1"
|
||||
msg_info "Starting phase 2"
|
||||
msg_info "Starting phase 3"
|
||||
```
|
||||
|
||||
### Terminal Control
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Ensure terminal control is available
|
||||
ensure_tput
|
||||
|
||||
# Use terminal control
|
||||
clear_line
|
||||
echo "This line will be cleared"
|
||||
clear_line
|
||||
echo "New content"
|
||||
```
|
||||
|
||||
## Troubleshooting Examples
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Enable debug mode
|
||||
export var_full_verbose=1
|
||||
export VERBOSE="yes"
|
||||
|
||||
# Debug information
|
||||
msg_debug "Script started"
|
||||
msg_debug "Current user: $(whoami)"
|
||||
msg_debug "Current directory: $(pwd)"
|
||||
msg_debug "Environment variables: $(env | grep -E '^(APP|CTID|VERBOSE)')"
|
||||
```
|
||||
|
||||
### Silent Execution Debugging
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Debug silent execution
|
||||
debug_silent() {
|
||||
local cmd="$1"
|
||||
local log_file="/tmp/debug.$$.log"
|
||||
|
||||
echo "Command: $cmd" > "$log_file"
|
||||
echo "Timestamp: $(date)" >> "$log_file"
|
||||
echo "Working directory: $(pwd)" >> "$log_file"
|
||||
echo "Environment:" >> "$log_file"
|
||||
env >> "$log_file"
|
||||
echo "--- Command Output ---" >> "$log_file"
|
||||
|
||||
if silent "$cmd"; then
|
||||
msg_ok "Command succeeded"
|
||||
else
|
||||
msg_error "Command failed - check $log_file for details"
|
||||
fi
|
||||
}
|
||||
|
||||
debug_silent "apt-get update"
|
||||
```
|
||||
|
||||
### Error Recovery
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
source core.func
|
||||
|
||||
# Error recovery pattern
|
||||
retry_operation() {
|
||||
local max_attempts=3
|
||||
local attempt=1
|
||||
|
||||
while [[ $attempt -le $max_attempts ]]; do
|
||||
msg_info "Attempt $attempt of $max_attempts"
|
||||
|
||||
if silent "$@"; then
|
||||
msg_ok "Operation succeeded on attempt $attempt"
|
||||
return 0
|
||||
else
|
||||
msg_warn "Attempt $attempt failed"
|
||||
((attempt++))
|
||||
|
||||
if [[ $attempt -le $max_attempts ]]; then
|
||||
msg_info "Retrying in 5 seconds..."
|
||||
sleep 5
|
||||
fi
|
||||
fi
|
||||
done
|
||||
|
||||
msg_error "Operation failed after $max_attempts attempts"
|
||||
return 1
|
||||
}
|
||||
|
||||
# Usage
|
||||
retry_operation "apt-get install -y package"
|
||||
```
|
||||
181
docs/misc/core.func/README.md
Normal file
181
docs/misc/core.func/README.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# core.func Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The `core.func` file provides fundamental utility functions and system checks that form the foundation for all other scripts in the Proxmox Community Scripts project. It handles basic system operations, user interface elements, validation, and core infrastructure.
|
||||
|
||||
## Purpose and Use Cases
|
||||
|
||||
- **System Validation**: Checks for Proxmox VE compatibility, architecture, shell requirements
|
||||
- **User Interface**: Provides colored output, icons, spinners, and formatted messages
|
||||
- **Core Utilities**: Basic functions used across all scripts
|
||||
- **Error Handling**: Silent execution with detailed error reporting
|
||||
- **System Information**: OS detection, verbose mode handling, swap management
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Key Function Groups
|
||||
- **System Checks**: `pve_check()`, `arch_check()`, `shell_check()`, `root_check()`
|
||||
- **User Interface**: `msg_info()`, `msg_ok()`, `msg_error()`, `msg_warn()`, `spinner()`
|
||||
- **Core Utilities**: `silent()`, `is_alpine()`, `is_verbose_mode()`, `get_header()`
|
||||
- **System Management**: `check_or_create_swap()`, `ensure_tput()`
|
||||
|
||||
### Dependencies
|
||||
- **External**: `curl` for downloading headers, `tput` for terminal control
|
||||
- **Internal**: `error_handler.func` for error explanations
|
||||
|
||||
### Integration Points
|
||||
- Used by: All other `.func` files and installation scripts
|
||||
- Uses: `error_handler.func` for error explanations
|
||||
- Provides: Core utilities for `build.func`, `tools.func`, `api.func`
|
||||
|
||||
## Documentation Files
|
||||
|
||||
### 📊 [CORE_FLOWCHART.md](./CORE_FLOWCHART.md)
|
||||
Visual execution flows showing how core functions interact and the system validation process.
|
||||
|
||||
### 📚 [CORE_FUNCTIONS_REFERENCE.md](./CORE_FUNCTIONS_REFERENCE.md)
|
||||
Complete alphabetical reference of all functions with parameters, dependencies, and usage details.
|
||||
|
||||
### 💡 [CORE_USAGE_EXAMPLES.md](./CORE_USAGE_EXAMPLES.md)
|
||||
Practical examples showing how to use core functions in scripts and common patterns.
|
||||
|
||||
### 🔗 [CORE_INTEGRATION.md](./CORE_INTEGRATION.md)
|
||||
How core.func integrates with other components and provides foundational services.
|
||||
|
||||
## Key Features
|
||||
|
||||
### System Validation
|
||||
- **Proxmox VE Version Check**: Supports PVE 8.0-8.9 and 9.0
|
||||
- **Architecture Check**: Ensures AMD64 architecture (excludes PiMox)
|
||||
- **Shell Check**: Validates Bash shell usage
|
||||
- **Root Check**: Ensures root privileges
|
||||
- **SSH Check**: Warns about external SSH usage
|
||||
|
||||
### User Interface
|
||||
- **Colored Output**: ANSI color codes for styled terminal output
|
||||
- **Icons**: Symbolic icons for different message types
|
||||
- **Spinners**: Animated progress indicators
|
||||
- **Formatted Messages**: Consistent message formatting across scripts
|
||||
|
||||
### Core Utilities
|
||||
- **Silent Execution**: Execute commands with detailed error reporting
|
||||
- **OS Detection**: Alpine Linux detection
|
||||
- **Verbose Mode**: Handle verbose output settings
|
||||
- **Header Management**: Download and display application headers
|
||||
- **Swap Management**: Check and create swap files
|
||||
|
||||
## Common Usage Patterns
|
||||
|
||||
### Basic Script Setup
|
||||
```bash
|
||||
# Source core functions
|
||||
source core.func
|
||||
|
||||
# Run system checks
|
||||
pve_check
|
||||
arch_check
|
||||
shell_check
|
||||
root_check
|
||||
```
|
||||
|
||||
### Message Display
|
||||
```bash
|
||||
# Show progress
|
||||
msg_info "Installing package..."
|
||||
|
||||
# Show success
|
||||
msg_ok "Package installed successfully"
|
||||
|
||||
# Show error
|
||||
msg_error "Installation failed"
|
||||
|
||||
# Show warning
|
||||
msg_warn "This operation may take some time"
|
||||
```
|
||||
|
||||
### Silent Command Execution
|
||||
```bash
|
||||
# Execute command silently with error handling
|
||||
silent apt-get update
|
||||
silent apt-get install -y package-name
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Core Variables
|
||||
- `VERBOSE`: Enable verbose output mode
|
||||
- `SILENT_LOGFILE`: Path to silent execution log file
|
||||
- `APP`: Application name for header display
|
||||
- `APP_TYPE`: Application type (ct/vm) for header paths
|
||||
|
||||
### Internal Variables
|
||||
- `_CORE_FUNC_LOADED`: Prevents multiple loading
|
||||
- `__FUNCTIONS_LOADED`: Prevents multiple function loading
|
||||
- `RETRY_NUM`: Number of retry attempts (default: 10)
|
||||
- `RETRY_EVERY`: Seconds between retries (default: 3)
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Silent Execution Errors
|
||||
- Commands executed via `silent()` capture output to log file
|
||||
- On failure, displays error code explanation
|
||||
- Shows last 10 lines of log output
|
||||
- Provides command to view full log
|
||||
|
||||
### System Check Failures
|
||||
- Each system check function exits with appropriate error message
|
||||
- Clear indication of what's wrong and how to fix it
|
||||
- Graceful exit with sleep delay for user to read message
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Script Initialization
|
||||
1. Source `core.func` first
|
||||
2. Run system checks early
|
||||
3. Set up error handling
|
||||
4. Use appropriate message functions
|
||||
|
||||
### Message Usage
|
||||
1. Use `msg_info()` for progress updates
|
||||
2. Use `msg_ok()` for successful completions
|
||||
3. Use `msg_error()` for failures
|
||||
4. Use `msg_warn()` for warnings
|
||||
|
||||
### Silent Execution
|
||||
1. Use `silent()` for commands that might fail
|
||||
2. Check return codes after silent execution
|
||||
3. Provide meaningful error messages
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
1. **Proxmox Version**: Ensure running supported PVE version
|
||||
2. **Architecture**: Script only works on AMD64 systems
|
||||
3. **Shell**: Must use Bash shell
|
||||
4. **Permissions**: Must run as root
|
||||
5. **Network**: SSH warnings for external connections
|
||||
|
||||
### Debug Mode
|
||||
Enable verbose output for debugging:
|
||||
```bash
|
||||
export VERBOSE="yes"
|
||||
source core.func
|
||||
```
|
||||
|
||||
### Log Files
|
||||
Check silent execution logs:
|
||||
```bash
|
||||
cat /tmp/silent.$$.log
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [build.func](../build.func/) - Main container creation script
|
||||
- [error_handler.func](../error_handler.func/) - Error handling utilities
|
||||
- [tools.func](../tools.func/) - Extended utility functions
|
||||
- [api.func](../api.func/) - Proxmox API interactions
|
||||
|
||||
---
|
||||
|
||||
*This documentation covers the core.func file which provides fundamental utilities for all Proxmox Community Scripts.*
|
||||
Reference in New Issue
Block a user