Moved some modules and added documentation

scrbl/racket-webview-downloader.scrbl

@@ -0,0 +1,151 @@
+#lang scribble/manual
+
+@(require racket/base
+          scribble/core
+          (for-label racket/base
+                     racket/file
+                     setup/dirs
+                     "../racket-webview-downloader.rkt"))
+
+@title{racket-webview-downloader}
+@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
+
+@defmodule[racket-webview/racket-webview-downloader]
+
+Downloader support for the native @tt{racket-webview-qt} runtime.
+
+This module provides functions for checking whether the native runtime is
+already installed, whether it can be resolved and downloaded, and for
+downloading and unpacking it into the user's addon directory.
+
+@section{Overview}
+
+The module manages one specific downloadable version of the native
+@tt{racket-webview-qt} package. The version is fixed in the source code through
+three constants: a major, minor, and patch number.
+
+The download URL is derived from:
+
+@itemlist[#:style 'compact
+ @item{the configured download site}
+ @item{the configured base path}
+ @item{the version string}
+ @item{the current operating system}
+ @item{the current machine architecture}]
+
+The downloaded archive is installed below the user's addon directory in a
+subdirectory named @tt{racket-webview-qt}.
+
+@section{Installation Layout}
+
+The installation directory is:
+
+@racketblock[
+(build-path (find-system-path 'addon-dir) "racket-webview-qt")
+]
+
+Within that directory, the module uses:
+
+@itemlist[#:style 'compact
+ @item{@tt{version.txt} to store the installed version}
+ @item{an OS/architecture-specific subdirectory for the unpacked native files}]
+
+The OS and architecture components are derived from:
+
+@racketblock[
+(system-type 'os*)
+(system-type 'arch)
+]
+
+@section{Availability and Version Checks}
+
+@defproc[(racket-webview-qt-is-available?) boolean?]{
+
+Returns @racket[#t] if the expected native runtime version is already installed,
+and @racket[#f] otherwise.
+
+The function checks whether @tt{version.txt} exists and can be read as a value.
+It then compares the stored major, minor, and patch numbers with the version
+hard-coded in this module.
+
+If reading the version file fails, the result is @racket[#f].
+}
+
+@defproc[(racket-webview-qt-version) (or/c list? #f)]{
+
+Returns the installed version as stored in @tt{version.txt}, or @racket[#f] if
+the expected native runtime is not available.
+
+The returned value is the value read from the version file. In the current
+implementation this is a list of three numbers: major, minor, and patch.
+}
+
+@defproc[(racket-webview-qt-directory) (or/c path? #f)]{
+
+Returns the directory containing the unpacked native runtime for the current
+operating system and architecture, or @racket[#f] if the expected version is not
+available.
+
+The returned path has the form:
+
+@racketblock[
+(build-path install-path (format "~a-~a" rkt-qt-os rkt-qt-arch))
+]
+}
+
+@section{Downloadability Checks}
+
+@defproc[(racket-webview-qt-resolves?) boolean?]{
+
+Returns @racket[#t] if the configured download host can be resolved through DNS,
+and @racket[#f] otherwise.
+
+If no nameserver can be found, or if DNS resolution fails, the result is
+@racket[#f].
+}
+
+@defproc[(racket-webview-qt-is-downloadable?) boolean?]{
+
+Returns @racket[#t] if the configured download URL can be opened, and
+@racket[#f] otherwise.
+
+The function attempts to open an HTTPS input port for the download URL. If that
+succeeds, the port is closed immediately and the function returns
+@racket[#t]. Any failure is caught and results in @racket[#f].
+}
+
+@section{Downloading}
+
+@defproc[(download-racket-webview-qt) boolean?]{
+
+Downloads and installs the configured version of @tt{racket-webview-qt}.
+
+The function performs the following steps:
+
+@itemlist[#:style 'compact
+ @item{opens an HTTPS input port for the configured download URL}
+ @item{creates the installation directory if necessary}
+ @item{downloads the archive to @tt{archive.zip}}
+ @item{removes any existing unpacked directory for the current OS and architecture}
+ @item{unzips the archive into the installation directory}
+ @item{removes the downloaded zip archive}
+ @item{writes the installed version to @tt{version.txt}}]
+
+Progress information is printed to the current output port while downloading and
+installing.
+
+If no download port can be obtained, the function raises an exception. Otherwise,
+on successful completion, it returns @racket[#t].
+}
+
+@section{Notes}
+
+The module forces HTTPS downloads by temporarily setting the current HTTPS
+protocol to @racket['secure] while opening the download port.
+
+The installed runtime is specific to the current operating system and machine
+architecture. The selected archive name has the form:
+
+@racketblock[
+(format "~a-~a.zip" (system-type 'os*) (system-type 'arch))
+]