Convert comments to shdoc

README.md

@@ -8,7 +8,7 @@ You can always find the latest version of installJRMC, changelog, and documentat
 
 `installJRMC [--option [ARGUMENT]]`
 
-Running `installJRMC` without any options will install the latest version of JRiver Media Center (MC) from the official JRiver repository (Ubuntu/Debian) or my [unofficial repository](https://repos.bryanroessler.com/jriver/) (Fedora/CentOS) using the system package manager (`--install repo`). If any other option is passed, then the default install method (i.e. `--install repo` or `--install local`) must be specified. This makes it possible to install services and containers independent of MC.>
+Running `installJRMC` without any options implies `--install repo` and will install the latest version of JRiver Media Center (MC) from the official JRiver repository (Ubuntu/Debian) or my [unofficial repository](https://repos.bryanroessler.com/jriver/) (Fedora/CentOS) using the system package manager. If any other option is passed, then the default install method (i.e. `--install repo` or `--install local`) must be specified (to allow services and containers to be installed independent of MC).
 
 ## tl;dr
 
@@ -51,6 +51,8 @@ $ installJRMC --help
       The webroot directory to install the repo (default: /var/www/jriver/)
   --createrepo-user USER
       The web server user if different from the current user
+--no-self-update
+    Disable the installJRMC update check
 --yes, -y, --auto
     Always assume yes for questions
 --version, -v
@@ -120,7 +122,7 @@ Multiple services (but not `--service-types`) can be installed at one time using
 
 * `installJRMC --install local --compat --restorefile /path/to/license.mjr --mcversion 33.0.20`
 
-    Build and install an MC 33.0.20 comptability RPM locally and activate it using the `/path/to/license.mjr`
+    Build and install an MC 33.0.20 compatibility RPM locally and activate it using the `/path/to/license.mjr`
 
 * `installJRMC --createrepo --createrepo-webroot /srv/jriver/repo --createrepo-user www-user`
 

installJRMC

@@ -16,12 +16,13 @@
 
 shopt -s extglob
 
-declare -g SCRIPT_VERSION="1.3.4"
+declare -g SCRIPT_VERSION="1.3.5-dev"
 declare -g BOARD_URL="https://yabb.jriver.com/interact/index.php/board,86.0.html" # MC33
 declare -g MC_VERSION="33.0.20" # Do find all replace
 declare -g MC_DEFAULT_REPO="bullseye" # should match the MC_VERSION
-declare -ig SELF_UPDATE=1
+declare -ig SELF_UPDATE=1 # set to 0 to disable automatic self-update
 
+# @description Print help text
 print_help() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -66,6 +67,8 @@ print_help() {
 		            Specify the webroot directory to install the repo (default: /var/www/jriver)
 		        --createrepo-user USER
 		            Specify the web server user if it differs from \$USER
+		    --no-self-update
+		        Disable automatic self-update
 		    --uninstall, -u
 		        Uninstall JRiver MC, remove services, containers, and firewall rules (does not remove library files)
 		    --yes, -y, --auto
@@ -103,35 +106,12 @@ print_help() {
 	EOF
 }
 
-
+# @description Perform OS detection and fallback
-#######################################
-# Helpers
-#######################################
-debug() { (( DEBUG )) && echo "Debug: $*"; }
-err() { echo "Error: $*" >&2; }
-ask_ok() {
-    declare response
-    (( YES_SWITCH )) && return 0
-    read -r -p "$* [y/N]: " response
-    [[ ${response,,} =~ ^(yes|y)$ ]]
-}
-execute() {
-    if debug "$*"; then
-        "$@"
-    else
-        "$@" &>/dev/null
-    fi
-}
-
-
-#######################################
-# Perform OS detection and fallback
 # Generate OS-specific functions
-#######################################
 init() {
     debug "Running: ${FUNCNAME[0]}"
 
-    declare -g ID RPM_MGR ARCH OS_NAME
+    declare -g ID RPM_MGR ARCH NAME
     declare -ga PKG_INSTALL PKG_REMOVE PKG_UPDATE PKG_QUERY
 
     echo "Starting installJRMC"
@@ -147,8 +127,6 @@ init() {
         exit 1
     fi
 
-    OS_NAME="${NAME// /_}"
-
     # Detect architecture and translate to MC convention
     ARCH=$(uname -m)
     case $ARCH in
@@ -220,7 +198,7 @@ init() {
             PKG_REMOVE=(execute sudo "$RPM_MGR" remove -y)
             PKG_UPDATE=(execute sudo "$RPM_MGR" makecache)
             PKG_QUERY=(rpm -q)
-            PKG_INSTALL_LOCAL() { install_mc_rpm; }
+            PKG_INSTALL_LOCAL() { install_mc_rhel; }
             ;;
         debian|ubuntu)
             PKG_INSTALL=(execute sudo apt-get -f install -y -q0)
@@ -252,10 +230,7 @@ init() {
     esac
 }
 
-
+# @description Parses user input and sets sensible defaults
-#######################################
-# Parses user input and sets sensible defaults
-#######################################
 parse_input() {
     debug "Running: ${FUNCNAME[0]} $*"
 
@@ -301,7 +276,7 @@ parse_input() {
     long_opts+="version,debug,verbose,help,uninstall,tests,yes,auto,no-self-update,"
     long_opts+="createrepo::,createrepo-webroot:,createrepo-user:,"
     long_opts+="vncpass:,display:,container:"
-    short_opts="+i:vb::dhus:c:"
+    short_opts="+i:b::s:c:uyvdh"
 
     # Reset DEBUG and catch with getopt
     declare -g DEBUG=0
@@ -419,10 +394,7 @@ parse_input() {
     fi
 }
 
-
+# @description Determines the latest JRiver MC version using several fallback methods 
-#######################################
-# Uses several methods to determine the latest JRiver MC version
-#######################################
 set_mc_version() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -481,17 +453,12 @@ set_mc_version() {
     return 0
 }
 
-
+# @description Installs a package using the system package manager
-#######################################
+# @arg $1 array One or more package names
-# Installs a package using the system package manager
+# @arg --no-install-check Do not check if package is already installed
-# Arguments:
+# @arg --no-gpg-check Disable GPG checks for RPM based distros
-#   One or more package names
+# @arg --allow-downgrades Useful for installing specific MC versions
-# Options:
+# @arg --silent | -s Do not print errors (useful for optional packages)
-#   --no-install-check: Do not check if package is already installed
-#   --no-gpg-check: Disable GPG checks for RPM based distros
-#   --allow-downgrades: Useful for installing specific MC versions
-#   --silent, -s: Do not print errors (useful for optional packages)
-#######################################
 install_package() {
     debug "Running: ${FUNCNAME[0]}" "$@"
 
@@ -568,9 +535,7 @@ install_package() {
 }
 
 
-#######################################
+# @description Installs mesa-va-drivers-freeworld
-# Installs mesa-va-drivers-freeworld
-#######################################
 install_mesa_freeworld() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -593,10 +558,7 @@ install_mesa_freeworld() {
     swap_or_install_freeworld_package "mesa-vdpau-drivers"
 }
 
-
+# @description Installs JRiver Media Center from a remote repository
-#######################################
-# Installs JRiver Media Center from a remote repository
-#######################################
 install_mc_repo() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -647,9 +609,7 @@ install_mc_repo() {
 }
 
 
-#######################################
+# @description Acquires the source DEB package from JRiver
-# Acquires the source DEB package from JRiver
-#######################################
 acquire_deb() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -688,10 +648,7 @@ acquire_deb() {
     [[ -f $MC_DEB ]]
 }
 
-
+# @description Creates a SPEC file and builds the RPM from the source DEB using rpmbuild
-#######################################
-# Creates a SPEC file and builds the RPM from the source DEB using rpmbuild
-#######################################
 build_rpm() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -863,10 +820,7 @@ build_rpm() {
     fi
 }
 
-
+# @description Installs Media Center DEB package and optional compatability fixes
-#######################################
-# Installs Media Center DEB package and optional compatability fixes
-#######################################
 install_mc_deb() {
     debug "Running: ${FUNCNAME[0]}"    
 
@@ -899,10 +853,8 @@ install_mc_deb() {
 }
 
 
-#######################################
+# @description Installs Media Center RPM package on RHEL distros
-# Installs Media Center RPM package
+install_mc_rhel() {
-#######################################
-install_mc_rpm() {
     debug "Running: ${FUNCNAME[0]}"
 
     # Install mesa-va-freeworld separately from the RPM for dnf swap
@@ -911,28 +863,23 @@ install_mc_rpm() {
     install_package --no-install-check --no-gpg-check --allow-downgrades "$MC_RPM"
 }
 
-
+# @description Installs Media Center RPM package on SUSE
-#######################################
-# Installs Media Center RPM package on SUSE
-#######################################
 install_mc_suse() {
     debug "Running: ${FUNCNAME[0]}"
     
     install_package --no-install-check --no-gpg-check --allow-downgrades "$MC_RPM"
 }
 
-
+# @description Installs Media Center generically for unsupported OSes
-#######################################
-# Installs Media Center manually
-#######################################
 install_mc_generic() {
     debug "Running: ${FUNCNAME[0]}"
 
     local -a raw_files
+    local extract_dir
 
     echo "Using generic installation method"
 
-    declare extract_dir && extract_dir="$(mktemp -d)"
+    extract_dir="$(mktemp -d)"
     pushd "$extract_dir" &>/dev/null || return
     execute ar x "$MC_DEB"
     execute tar xJf "control.tar.xz"
@@ -952,10 +899,7 @@ install_mc_generic() {
     return 0
 }
 
-
+# @description Installs Media Center Arch PKGBUILD
-#######################################
-# Installs local Media Center PKGBUILD
-#######################################
 install_mc_arch() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1005,10 +949,7 @@ install_mc_arch() {
     popd &>/dev/null || return
 }
 
-
+# @description Copy the RPM to createrepo-webroot and runs createrepo as the createrepo-user
-#######################################
-# Copy the RPM to createrepo-webroot and runs createrepo as the createrepo-user
-#######################################
 run_createrepo() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1052,10 +993,7 @@ run_createrepo() {
     fi
 }
 
-
+# @description Symlink certificates if they do not exist in default location
-#######################################
-# Symlink certificates if they do not exist in default location
-#######################################
 link_ssl_certs() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1079,10 +1017,7 @@ link_ssl_certs() {
     done
 }
 
-
+# @description Restore the mjr license file from MJR_RESTORE_FILE or other common locations
-#######################################
-# Restore the mjr license file from MJR_RESTORE_FILE or other common locations
-#######################################
 restore_license() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1120,15 +1055,11 @@ restore_license() {
     fi
 }
 
-
+# @description Opens ports using the system firewall tool
-#######################################
+# @arg $1 string Service name
-# Opens ports using the system firewall tool
+# @arg $2 array List of ports in firewall-cmd format
-# Arguments:
-#   1. Service name
-#   2. List of ports in firewall-cmd format
-#######################################
 open_firewall() {
-    debug "Running: ${FUNCNAME[0]}" "$@"
+    debug "Running: ${FUNCNAME[0]}" "$*"
 
     local port
     local service="$1"
@@ -1164,12 +1095,8 @@ open_firewall() {
     fi
 }
 
-
+# @description Create the xvnc or x11vnc password file
-#######################################
+# @arg $1 string Service type (xvnc, x11vnc)
-# Create the xvnc or x11vnc password file
-# Arguments:
-#   Service type (xvnc, x11vnc)
-#######################################
 set_vnc_pass() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1199,10 +1126,7 @@ set_vnc_pass() {
     fi
 }
 
-
+# @description Set display and port variables
-#######################################
-# Set display and port variables
-#######################################
 set_display_vars() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1221,12 +1145,8 @@ set_display_vars() {
     NEXT_DISPLAY=":$NEXT_DISPLAY_NUM"
 }
 
-
+# @description Create associated service variables based on service name
-#######################################
+# @arg $1 string Service name
-# Create associated service variables based on service name
-# Arguments
-#   Pre-defined service name
-#######################################
 set_service_vars() {
     debug "Running: ${FUNCNAME[0]}" "$*"
 
@@ -1277,11 +1197,8 @@ set_service_vars() {
 }
 
 
-#######################################
+# @description Starts and enables (at startup) a JRiver Media Center service
-# Starts and enables (at startup) a JRiver Media Center service
+# @arg $1 string Passes arguments as startup options to /usr/bin/mediacenter??
-# Arguments:
-#   Passes arguments as startup options to /usr/bin/mediacenter??
-#######################################
 service_jriver-mediacenter() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1312,10 +1229,7 @@ service_jriver-mediacenter() {
     && "${ENABLE[@]}" "$SERVICE_NAME"
 }
 
-
+# @description Starts and enables (at startup) a JRiver Media Server service
-#######################################
-# Starts and enables (at startup) a JRiver Media Server service
-#######################################
 service_jriver-mediaserver() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1324,11 +1238,8 @@ service_jriver-mediaserver() {
     service_jriver-mediacenter "/MediaServer"
 }
 
-
+# @description Starts and enables (at startup) JRiver Media Center in a new Xvnc session
-#######################################
-# Starts and enables (at startup) JRiver Media Center in a new Xvnc session
 # TODO https://github.com/TigerVNC/tigervnc/blob/master/unix/vncserver/HOWTO.md
-#######################################
 service_jriver-xvnc() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1394,10 +1305,7 @@ service_jriver-xvnc() {
     fi
 }
 
-
+# @description Starts and enables (at startup) x11vnc screen sharing for the local desktop
-#######################################
-# Starts and enables (at startup) x11vnc screen sharing for the local desktop
-#######################################
 service_jriver-x11vnc() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1461,11 +1369,8 @@ service_jriver-x11vnc() {
     && echo "x11vnc running on localhost:$PORT"
 }
 
-
+# @description Starts and enables (at startup) an hourly service to build the latest version of
-#######################################
-# Starts and enables (at startup) an hourly service to build the latest version of
 # JRiver Media Center RPM from the source DEB and create/update an RPM repository
-#######################################
 service_jriver-createrepo() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1503,10 +1408,7 @@ service_jriver-createrepo() {
     && "${ENABLE[@]}" "$TIMER_NAME"
 }
 
-
+# @description Detects if MC is installed on btrfs and disables CoW
-#######################################
-# Detects if MC is installed on btrfs and disables CoW
-#######################################
 disable_btrfs_cow() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1523,10 +1425,7 @@ disable_btrfs_cow() {
     done
 }
 
-
+# @description Completely uninstalls MC, services, and firewall rules
-#######################################
-# Completely uninstalls MC, services, and firewall rules
-#######################################
 uninstall() {
     debug "Running: ${FUNCNAME[0]}"
 
@@ -1557,7 +1456,7 @@ uninstall() {
     done
 
     echo "Removing repo files"
-    sudo rm -rf \
+    execute sudo rm -rf \
         "/etc/yum.repos.d/jriver.repo" \
         /etc/apt/sources.list.d/{jriver,mediacenter}*.list # also remove legacy repo files
     if [[ $ID == "suse" ]]; then
@@ -1596,10 +1495,7 @@ uninstall() {
     return 0
 }
 
-
+# @description Checks for installJRMC update and re-executes, if necessary
-#######################################
-# Checks for installJRMC update and re-executes, if necessary
-#######################################
 update_self() {
     debug "Running: ${FUNCNAME[0]} $*"
 
@@ -1666,7 +1562,7 @@ update_self() {
     rm -f "$tmp"
 }
 
-
+# @description installJRMC main function
 main() {
     debug "Running: ${FUNCNAME[0]} $*"
 
@@ -1727,7 +1623,7 @@ main() {
             # if ! zypper repos | grep -q "X11_XOrg"; then
             #     echo "Installing the X11 repository"
             #     execute sudo zypper  --non-interactive --quiet addrepo \
-            #         "https://download.opensuse.org/repositories/X11:/XOrg/$OS_NAME/X11:XOrg.repo"
+            #         "https://download.opensuse.org/repositories/X11:/XOrg/${NAME// /_}/X11:XOrg.repo"
             #     execute sudo zypper  --non-interactive --quiet refresh
             # fi
             ;;
@@ -1738,7 +1634,6 @@ main() {
         if install_mc_repo; then
             echo "JRiver Media Center installed successfully from remote repository"
             link_ssl_certs
-            # migrateLibrary
             restore_license
             open_firewall "jriver-mediacenter" "52100-52200/tcp" "1900/udp"
             disable_btrfs_cow
@@ -1768,7 +1663,6 @@ main() {
             return 1
         fi
         link_ssl_certs
-        # migrateLibrary
         restore_license
         open_firewall "jriver-mediacenter" "52100-52200/tcp" "1900/udp"
         disable_btrfs_cow
@@ -1809,7 +1703,24 @@ main() {
     # done
 }
 
-# Roughly turn debugging on, reparse in getInput() with getopt
+# @section Helper functions
+debug() { (( DEBUG )) && echo "Debug: $*"; }
+err() { echo "Error: $*" >&2; }
+ask_ok() {
+    declare response
+    (( YES_SWITCH )) && return 0
+    read -r -p "$* [y/N]: " response
+    [[ ${response,,} =~ ^(yes|y)$ ]]
+}
+execute() {
+    if debug "$*"; then
+        "$@"
+    else
+        "$@" &>/dev/null
+    fi
+}
+
+# Roughly turn debugging on, reparse in get_input() with getopt
 [[ " $* " =~ ( --debug | -d ) ]] && declare -g DEBUG=1
 
 main "$@"