From 2c4b0880778caa14efc139d8e15ff0074bc273a0 Mon Sep 17 00:00:00 2001 From: CanbiZ <47820557+MickLesk@users.noreply.github.com> Date: Fri, 17 Jan 2025 10:17:06 +0100 Subject: [PATCH] Created build.func - script function explanations (markdown) --- build.func-‐-script-function-explanations.md | 332 +++++++++++++++++++ 1 file changed, 332 insertions(+) create mode 100644 build.func-‐-script-function-explanations.md diff --git a/build.func-‐-script-function-explanations.md b/build.func-‐-script-function-explanations.md new file mode 100644 index 0000000..3e5f1b8 --- /dev/null +++ b/build.func-‐-script-function-explanations.md @@ -0,0 +1,332 @@ + +# Script Function Explanations + +## 1. `variables()` +**Purpose**: This function sets up various global variables that will be used throughout the script. + +### Details: +- `NSAPP`: Converts the string value in the `APP` variable to lowercase and removes any spaces. +- `var_install`: Appends `-install` to the `NSAPP` value, representing the installation script name. +- `INTEGER`: A regular expression used to validate integer values (with or without decimals). +- `PVEHOST_NAME`: Sets the variable to the current hostname of the Proxmox server. + +### Example: +```bash +APP="MyApp" +variables +echo $NSAPP # Output: "myapp" +echo $var_install # Output: "myapp-install" +``` + +--- + +## 2. `color()` +**Purpose**: Defines various color and formatting variables for terminal output. + +### Details: +- Defines colors like yellow (`YW`), green (`GN`), and red (`RD`) using ANSI escape codes for text formatting. +- Also defines icons for different types of output, such as checkmarks (`CM`), error crosses (`CROSS`), and information (`INFO`). + +### Example: +```bash +color +echo -e "${GN}Success${CL}" # Output: Green colored "Success" +echo -e "${INFO}Info${CL}" # Output: Info icon followed by text "Info" +``` + +--- + +## 3. `catch_errors()` +**Purpose**: Sets up error handling for the script. + +### Details: +- `set -Eeuo pipefail`: Ensures the script exits immediately if a command fails, an undefined variable is accessed, or if any command in a pipeline fails. +- `trap`: Defines a trap to call `error_handler()` when an error occurs, passing the line number and command that failed. + +### Example: +```bash +catch_errors +ls non_existent_file # This will cause an error and call the error_handler +``` + +--- + +## 4. `error_handler()` +**Purpose**: Handles errors by displaying the error details. + +### Details: +- If a spinner is running, it is stopped. +- The function prints the error details, including the line number and the command that caused the error. + +### Example: +```bash +error_handler 42 "ls non_existent_file" +# Output: [ERROR] in line 42: exit code 2: while executing command "ls non_existent_file" +``` + +--- + +## 5. `spinner()` +**Purpose**: Displays a rotating spinner animation. + +### Details: +- The spinner uses a set of frames (`⠋`, `⠙`, `⠹`, etc.) to simulate a spinning animation in the terminal. +- The spinner runs until the process it is indicating is completed. + +### Example: +```bash +spinner # Call this function to start the spinner +``` + +--- + +## 6. `msg_info()`, `msg_ok()`, `msg_error()` +**Purpose**: Functions for displaying different types of messages. + +### Details: +- `msg_info()`: Displays an informational message with a spinner animation. +- `msg_ok()`: Displays a success message. +- `msg_error()`: Displays an error message. + +### Example: +```bash +msg_info "This is an informational message" +msg_ok "Success!" +msg_error "An error occurred" +``` + +--- + +## 7. `shell_check()` +**Purpose**: Verifies if the script is running in the Bash shell. + +### Details: +- If the script is not running in Bash, it exits with a message indicating that Bash is required. + +### Example: +```bash +shell_check # Exits if the shell is not Bash +``` + +--- + +## 8. `root_check()` +**Purpose**: Ensures the script is being run as root. + +### Details: +- If the script is not run as root, it exits with a message asking the user to run the script as root. + +### Example: +```bash +root_check # Exits if not run as root +``` + +--- + +## 9. `pve_check()` +**Purpose**: Verifies the Proxmox Virtual Environment (PVE) version. + +### Details: +- Ensures the Proxmox version is in the range 8.1 to 8.3, exiting with an error if not. + +### Example: +```bash +pve_check # Exits if Proxmox version is not 8.1-8.3 +``` + +--- + +## 10. `arch_check()` +**Purpose**: Verifies if the system architecture is `amd64`. + +### Details: +- If the system architecture is not `amd64`, it exits with a message indicating that the script will not work on ARM architectures (e.g., PiMox). + +### Example: +```bash +arch_check # Exits if the architecture is not amd64 +``` + +--- + +## 11. `get_current_ip()` +**Purpose**: Retrieves the current IP address based on the operating system. + +### Details: +- For Debian/Ubuntu systems, it uses `hostname -I`. +- For Alpine systems, it uses `ip addr show`. + +### Example: +```bash +get_current_ip # Outputs the system's current IP address +``` + +--- + +## 12. `update_motd_ip()` +**Purpose**: Updates the `/etc/motd` file with the current IP address. + +### Details: +- Removes any existing IP address entries from the file and adds the new IP address. + +### Example: +```bash +update_motd_ip # Updates the IP address in /etc/motd +``` + +--- + +## 13. `header_info()` +**Purpose**: Displays an ASCII art header with the application name. + +### Details: +- If `figlet` is not installed, it will install it, download the slant font, and generate the ASCII header. + +### Example: +```bash +header_info # Displays the ASCII header with the app name +``` + +--- + +## 14. `ssh_check()` +**Purpose**: Detects if the script is running over SSH. + +### Details: +- Prompts the user for confirmation to proceed if SSH is detected, as SSH might cause complications with certain commands. + +### Example: +```bash +ssh_check # Exits if SSH is used, or prompts to proceed +``` + +--- + +## 15. `base_settings()` +**Purpose**: Sets up default values for container configuration. + +### Details: +- Sets default values for container type, disk size, CPU count, RAM, and other settings. +- Can be overridden with user inputs. + +### Example: +```bash +base_settings # Sets up default settings for the container +``` + +--- + +## 16. `echo_default()` +**Purpose**: Outputs the default values for the container configuration. + +### Details: +- Displays the configured settings with corresponding icons. + +### Example: +```bash +echo_default # Displays the default configuration values +``` + +--- + +## 17. `exit_script()` +**Purpose**: Exits the script with a message. + +### Details: +- Clears the screen and prints a message indicating that the script has exited. + +### Example: +```bash +exit_script # Exits the script +``` + +--- + +## 18. `advanced_settings()` +**Purpose**: Allows the user to configure advanced settings for the container. + +### Details: +- Provides an interactive interface using `whiptail` to set advanced options, such as operating system, version, disk size, network configuration, and more. + +### Example: +```bash +advanced_settings # Displays an interactive configuration menu +``` + +--- + +## 19. `install_script()` +**Purpose**: Installs the container according to the selected settings. + +### Details: +- Checks system requirements and starts the installation process. + +### Example: +```bash +install_script # Starts the container installation process +``` + +--- + +## 20. `check_container_resources()` +**Purpose**: Verifies the system has sufficient resources for the container. + +### Details: +- Ensures that the system has enough RAM and CPU cores for the container. + +### Example: +```bash +check_container_resources # Verifies if enough resources are available +``` + +--- + +## 21. `check_container_storage()` +**Purpose**: Verifies if the `/boot` partition has sufficient space. + +### Details: +- Warns the user if storage is more than 80% full. + +### Example: +```bash +check_container_storage # Warns if /boot partition is over 80% full +``` + +--- + +## 22. `start()` +**Purpose**: Initializes the installation or update process based on user choice. + +### Details: +- Prompts the user to confirm before proceeding with container creation or updates. + +### Example: +```bash +start # Starts the container creation or update process +``` + +--- + +## 23. `build_container()` +**Purpose**: Builds the container using the defined settings. + +### Details: +- Collects user inputs, configures the container, and creates it using `pct` commands. + +### Example: +```bash +build_container # Builds the container with the selected settings +``` + +--- + +## 24. `description()` +**Purpose**: Sets the description for the created container. + +### Details: +- Generates an HTML description for the container and adds it to the container configuration. + +### Example: +```bash +description # Sets the container description +```