Merge remote-tracking branch 'origin/main' into documentation

README.md

@@ -1,4 +1,4 @@
-# (WIP) Microsoft Edge (Beta) Updater
+# Microsoft Edge Updater
 An updater program which can install the latest available version of Microsoft Edge to non-Debian-based Linux distros.
 
 Currently this program can only update the Beta release of Microsoft Edge for amd64 architectures.
@@ -6,12 +6,15 @@ Currently this program can only update the Beta release of Microsoft Edge for am
 ## Usage
 ```
 Usage: updater [OPTION]
-Microsoft Edge Updater (0.1.3) - An updater program which can install the latest available version of Microsoft Edge to non-Debian-based Linux distros.
+Microsoft Edge Updater (0.1.4) - An updater program which can install the latest available version of Microsoft Edge to non-Debian-based Linux distros.
 
 DISCLAIMER: Currently this program can only update the Beta release of Microsoft Edge for amd64 architectures.
 
 Options:
   -nn, --no-notify    Prevent notifications from being set after a session.
+       --mode=        Set the mode of the program to be ran in. Default mode
+                      occurs without this flag.
+                        * debug - run program in debug mode.
    -y, --yes-all      Assume yes to all yes/no decisions.
    -v, --version      Print out the version of the script and exit.
    -h, --help         Print this help message and exit
@@ -19,8 +22,19 @@ Options:
 
 ## Information
 * Program Name - Microsoft Edge Updater
-* Script Name - updater
+* Script Name - `updater`
-* Version - 0.1.3 (Beta)
+* Version - 0.1.4
 * Synopsis - update Microsoft Edge (Beta) to the latest release.
 * Author(s) - Ethan Smith-Coss (No contact)
+* Contributors - Robert Morrison, Documentation
 * License - GNU GPLv3+
+
+## Documentation
+For more in-depth documentation on `updater`, view the manpage in markdown form [here](https://robmc.duckdns.org/git/TheOnePath/Microsoft-Edge-Updater/src/branch/main/updater.1.md).
+Alternatively you can view the manpage from your terminal by downloading the project.
+
+```bash
+    $  git clone https://robmc.duckdns.org/git/TheOnePath/Microsoft-Edge-Updater
+    $  cd Microsoft-Edge-Updater/
+    $  man ./updater.1
+```

updater

@@ -4,10 +4,14 @@
 #        updater - Automatically update Microsoft Edge on Solus         #
 #                                                                       #
 #                             Dependencies:                             #
+#                                 bash                                  #
 #                                 wget                                  #
+#                                  git                                  #
 #                                gunzip                                 #
 #                                  tar                                  #
-#                       sort (coreutils >= 8.32)                        #
+#                          coreutils (>= 8.32)                          #
+#                          binutils (>=2.35.1)                          #
+#                  procps (only BusyBox-based systems)                  #
 #                              notify-send                              #
 #                                                                       #
 #                                                                       #
@@ -18,7 +22,7 @@
 #                       Author: Ethan Smith-Coss                        #
 #                            Version: 0.1.4                             #
 #                    Created: 2021-05-20T16:47+0100                     #
-#                 Last Modified: 2021-06-21T18:23+0100                  #
+#                 Last Modified: 2021-06-22T17:18+0100                  #
 #                                                                       #
 #                 ####################################                  #
 #                                                                       #
@@ -50,10 +54,12 @@ $prog_name ($version) - An updater program which can install the latest availabl
 DISCLAIMER: Currently this program can only update the Beta release of Microsoft Edge for amd64 architectures.
 
 Options:
-  -nn, --no-notify    Prevent notifications from being set after a session.
+  -nn, --no-notify     Prevent notifications from being set after a session.
-   -y, --yes-all      Assume yes to all yes/no decisions.
+       --mode=[debug]  Set the mode of the program to be ran in. Default mode occurs without this flag.
-   -v, --version      Print out the version of the script and exit.
+                         * debug - run program in debug mode.
-   -h, --help         Print this help message and exit
+   -y, --yes-all       Assume yes to all yes/no decisions.
+   -v, --version       Print out the version of the script and exit.
+   -h, --help          Print this help message and exit
 "
 
 runtime_dir=$(realpath "${BASH_SOURCE[0]}" | xargs -r dirname)
@@ -65,10 +71,11 @@ garbage="$tmp_path/garbage.tmp"
 ## program timer
 SECONDS=0
 
+## create the logs directory and tmp location if they don't already exist
 [[ ! -d "$logs_dir" ]] && mkdir "$logs_dir"
 [[ ! -d "$tmp_path" ]] && mkdir "$tmp_path"
 
-
+# function responsible for cleaning up after a session execution
 function clean_up {
 	log "DEBUG" "EXIT signal was raised, cleaning up system after session before exiting..." "$log_file"
 	printf "Cleaning up system after session..."
@@ -93,6 +100,7 @@ function clean_up {
 	[[ $debug_run -eq 0 ]] && cat "$logs_dir/updater.log"
 }
 
+# ensure that the restoration was sucessful in reverting the system back
 function check_restoration {
 	[[ ! $1 -eq 0 ]] && { echo -e "failed.\nThere was an error trying to restore system files." \
 		"Either there no back was made or another issue occurred. Consult $log_file for more information." ; exit $1 ; }
@@ -102,6 +110,7 @@ function check_restoration {
 		"Consult $log_file for more information. Exiting..."
 	[[ ! $nn_flag -eq 0 ]] && notify "Microsoft Edge (Beta) Update" "There was an issue installing the update to your system." \
 		"The previous version, v$current_version, has been restored."
+	echo "$backup_file" >>"$garbage"
 }
 
 ## iterate over all user inputs
@@ -147,7 +156,7 @@ log "DEBUG" "The yes flag has been set to: $yes_flag." "$log_file"
 ## setup the no-notify (nn) flag if notify-send isn't installed
 command -v notify-send >/dev/null 2>&1 || nn_flag=0
 nn_flag=${nn_flag:-1}
-## set the testing flag if not already
+## set the debugging flag if not already
 debug_run=${debug_run:-1}
 [[ $debug_run -eq 0 ]] && log "DEBUG" "The mode flag has been set so script will operate in debug mode." "$log_file"
 
@@ -199,8 +208,7 @@ exit_code=$?
 [[ ! $exit_code -eq 0 ]] && { echo "There was an issue retrieving the package contents for the update. Please check $log_file/updater.log, so more information. Exiting..." ;
 	log "ERROR" "Encountered an issue with wget. Exiting...(4)" "$log_file" ; exit 4 ; }
 log "DEBUG" "Successfully downloaded release contents information." "$log_file"
-
+## decompress the packages file
-### :@TODO: continue with TODO list. Finish off above code section to ensure wget is successful and logging appropriately.
 log "DEBUG" "Uncompressing downloaded gz file using gunzip, $tmp_path/Packages.gz..." "$log_file"
 ## force gunzip to overwrite decompressed file if it already exists
 gunzip -f "$tmp_path/Packages.gz" "$tmp_path/Contents-$archi.gz" >/dev/null 2>&1
@@ -328,8 +336,8 @@ if [[ ! -f "$tmp_path/$filename" ]] ; then
 		"Please check $logs_dir/updater.log, for more information. Exiting update..." ;
 		log "DEBUG" "Encountered an issue with wget. Exiting...(6)" "$log_file" ; exit 6 ; }
 	awk -v end=$(grep -n '^\s*$' "$tmp_path/wget_dump.log" | tr '\n' ' ' | cut -d: -f1) 'NR>1*0&&NR<1*end+1' "$tmp_path/wget_dump.log" >> "$log_file"
-	log "DEBUG" "Download completed successfully in $(echo $wget_timed | cut -d' ' -f2)s, wget log below." "$log_file"
+	log "DEBUG" "Download completed successfully, wget log shown above." "$log_file"
-	printf "Download complete in $(echo $wget_timed | cut -d' ' -f2)s. Validating checksums..."
+	printf "Download complete. Validating checksums..."
 else
 	log "DEBUG" "File already downloaded to system. Skipped download and verifying checksum..." "$log_file"
 	printf "Latest Debian release file is downloaded to the system, skipping download. Validating checksums..."
@@ -371,7 +379,6 @@ rm -r "$tmp_path/etc/"
 echo "$tmp_path/data.tar.xz" >> "$garbage"
 
 # compress archive the currently installed version of Edge (Beta) for restoration on failure
-## :@TODO: compress everything on the system for a backup. Remove it if installation of new version was successful
 log "DEBUG" "Creating an archive gzip tarball of system /opt/ and /usr/ directories..." "$log_file"
 printf "Installing new version to system. This may take a few minutes..."
 archive_system "microsoft/msedge-beta"
@@ -385,7 +392,7 @@ fi
 log "DEBUG" "Successfully created an archive gzip tarball of the system. Safe to continue with installation." "$log_file"
 
 ### :@NOTE: used to terminate the program at a certain point for incremental testing of functionality recently added up to the point of this exit.
-#exit 0
+### exit 0
 
 # install the new version to system
 log "DEBUG" "Copying files to there appropriate location..." "$log_file"
@@ -440,8 +447,11 @@ if [[ "$(microsoft-edge-beta --version | cut -d' ' -f3)" != "$release_version" ]
 	exit 11
 fi
 
+## end of update. Inform user of time taken to complete, notify and log.
 elapsed_time=$SECONDS
 script_time="$(($elapsed_time / 60))m $(($elapsed_time % 60))s"
 log "DEBUG" "Installation and update was successful (completed in: $script_time) and system can be cleaned up to remove any waste." "$log_file"
 echo "Microsoft Edge (Beta) has been successfully updated to the latest version: v$current_version -> v$release_version, in $script_time."
 [[ ! $nn_flag -eq 0 ]] && notify "Microsoft Edge (Beta) Update" "Successfully updated Microsoft Edge (Beta) to the latest version: v$release_version"
+
+# exit of script, clean up function is called now by default exit of script (EOF)

utils/common

@@ -3,13 +3,15 @@
 #        common - Utility file with common functions for updater        #
 #                                                                       #
 #                             Dependencies:                             #
+#                                 bash                                  #
+#                          coreutils (>=8.32)                           #
 #                                  tar                                  #
 #                                                                       #
 #                                                                       #
 #                       Author: Ethan Smith-Coss                        #
 #                            Version: 0.1.4                             #
 #                    Created: 2021-05-20T16:47+0100                     #
-#                 Last Modified: 2021-06-21T15:06+0100                  #
+#                 Last Modified: 2021-06-22T16:57+0100                  #
 #                                                                       #
 #                 ####################################                  #
 #                                                                       #
@@ -31,6 +33,7 @@
 #                                                                       #
 #########################################################################
 
+# logging function called to log information to a file.
 function log {
 	local log_out=$(realpath "${0%/*}/.log.1")
 	[[ $# -eq 0 ]] && log "ERROR" "Log function was called without any arguments. Returning 1." "$log_out" && return 1
@@ -41,6 +44,7 @@ function log {
 	return 0
 }
 
+# archive function used to create an archive compression of Microsoft Edge
 function archive_system {
 	local log_out=$(realpath "${0%/*}/.log.1")
 	[[ -e $1 ]] && log "ERROR" "Archive function was called without any arguments." "$log_out"
@@ -48,10 +52,11 @@ function archive_system {
 	local archive_output="/tmp/microsoft-edge-autoupdater/$(echo $1 | sed 's/\//_/').tar.gz"
 	[[ -f "$archive_output" ]] && return 0
 	
+	## identify the files required for compressing
 	usr_files="$(grep -E '^usr/.*beta.*$' "/tmp/microsoft-edge-autoupdater/Contents-amd64" | awk '{print "/" $1}')"
 	opt_files="$(ls -1 "/opt/$1/" | sed -E "s/^(.*)$/\/opt\/"$(echo $1 | sed 's/\//\\\//')"\/\1/g")"
-	## :@Ethan: we need to identify all the symlinked files and store them in a record. When we decompress we reinstate the symlinks.
+	### :@Ethan: we need to identify all the symlinked files and store them in a record. When we decompress we reinstate the symlinks.
-	## This file is included in the archive and tar will dereference symlink files.
+	## This file is only stored temporarily and any symlinks will be removed from the identified files for compression.
 	symlink_record="/tmp/microsoft-edge-autoupdater/symlink-record"
 	ls -l $opt_files $usr_files | grep -Eo ':.*->.*$' | sed 's/\s->\s/:/g' | cut -d' ' -f2- > "$symlink_record"
 
@@ -62,6 +67,7 @@ function archive_system {
 		[[ "$record" =~ \/opt\/ ]] && record=$(echo $record | sed 's/\//\\\//g') && opt_files=$(echo "$opt_files" | sed "s/^"$record"$//")
 	done < <(cat $symlink_record)
 
+	## use gzip compression to create the tarball archive
 	tar --overwrite -czf "$archive_output" $opt_files $usr_files  > "/tmp/microsoft-edge-autoupdater/tar_dump.log" 2>>"$log_out"
 	exit_code=$?
 	[[ ! $exit_code -eq 0 ]] && { log "ERROR" "(Archive) There was an issue creating the archive file of system. Returning...(10)" "$log_out" ; return 10 ; }
@@ -69,23 +75,26 @@ function archive_system {
 	return 0
 }
 
+# restoration function called at any point when the update fails during an installation process.
 function restore_files {
 	local log_out=$(realpath "${0%/*}/.log.1")
 	[[ -e $1 ]] && log "ERROR" "Restore function was called without any arguments." "$log_out"
-	local backup_file="/tmp/microsoft-edge-autoupdater/$1.tar.gz"
+	backup_file="/tmp/microsoft-edge-autoupdater/$1.tar.gz"
 	[[ ! -f "$backup_file" ]] && { log "ERROR" "There is no backup of Microsoft Edge (Beta) identified. Restoration not possible." "$log_out" ; return 12 ; }
 
+	## decompress the tarball archive using gzip and overwrite all files in the archive on the system
 	tar --overwrite -xzf "$backup_file" -C "/" > "/tmp/microsoft-edge-autoupdater/tar_dump.log" 2>>"$log_out"
 	exit_code=$?
 	[[ ! $exit_code -eq 0 ]] && { log "ERROR" "There was an issue restoring pervious files to system." \
 		"The backup created will not be removed to allow for manual restoration. Returning...(12)" ; return 12 ; }
 
+	## recreate the symlinks
 	log "DEBUG" "Re-establishing symlinks..." "$log_out"
 	symlink_record="/tmp/microsoft-edge-autoupdater/symlink-record"
 	while read -r record ; do
 		symlink="$(echo $record | cut -d':' -f1)"
 		symlink_to="$(echo $record | cut -d':' -f2)"
-		## :NOTE: symlinks may already exist from new update and theoretically could be different in a newer version. Remove them first
+		### :NOTE: symlinks may already exist from new update and theoretically could be different in a newer version. Remove them first
 		rm "$symlink"
 		## create new sylinks based on the restored files
 		ln -s "$symlink_to" "$symlink" >/dev/null 2>>"$log_out"
@@ -98,8 +107,8 @@ function restore_files {
 	return 0
 }
 
+# notification function used to send the user a notification via the dbus
 function notify {
-	## :@TODO: implement notification system.
 	local log_out=$(realpath "${0%/*}/.log.1")
 	[[ $# -eq 0 ]] && log "ERROR" "Notify function was called without any arguments. Returning 1." "$log_out" && return 1
 	[[ ! $# -eq 2 ]] && log "ERROR" "Notify function expected at least 2 arguments, recieved $#. Returning 1." "$log_out" && return 1