fix windows CI, README improvements

Author: Andrew Kent

.github/ci.sh

@@ -38,12 +38,8 @@ retry() {
 }
 
 setup_dist_bins() {
-  if $IS_WIN; then
-    is_exe "dist/bin" "saw" && return
-  else
-    is_exe "dist/bin" "saw" && is_exe "dist/bin" "saw-remote-api" && return
-    extract_exe "saw-remote-api" "dist/bin"
-  fi
+  is_exe "dist/bin" "saw" && is_exe "dist/bin" "saw-remote-api" && return
+  extract_exe "saw-remote-api" "dist/bin"
   extract_exe "saw" "dist/bin"
   export PATH=$PWD/dist/bin:$PATH
   echo "$PWD/dist/bin" >> "$GITHUB_PATH"

.github/workflows/build.yml

@@ -113,7 +113,6 @@ jobs:
         run: |
           saw-remote-api/scripts/run_rpc_tests.sh
           saw-remote-api/scripts/check_docs.sh
-        if: runner.os != 'Windows'
 
       - uses: actions/setup-java@v1
         with:

saw-remote-api/python/README.md

@@ -4,7 +4,7 @@ In-development Python client for SAW.
 
 This SAW client depends on the [saw-remote-api](https://github.com/GaloisInc/saw-script/tree/master/saw-remote-api) server.
 
-## TL;DR Steps to running SAW Python scripts
+# TL;DR Steps to running SAW Python scripts
 
 1. Clone the repo 
 ```
@@ -47,16 +47,21 @@ $ poetry run python tests/saw/test_salsa20.py
 subprocesses when run via `unittest` even though they pass and successfully
 verify the goals. It's on our to-do list.)
 
-## Installation
+# Python Client Installation (via Poetry)
 
-# Python environment
+First, clone the repository and submodules.
 
-## Poetry
+```
+$ git clone https://github.com/GaloisInc/saw-script.git
+$ cd saw-script
+$ git submodule update --init
+```
 
-First, [install `poetry`](https://python-poetry.org/docs/#installation) and then
-run in the `saw-remote-api/python` directory:
+Then, use [`poetry`](https://python-poetry.org/docs/#installation) to install
+the python client from the `saw-remote-api/python` directory:
 
 ```
+$ cd saw-remote-api/python
 $ poetry install
 ```
 
@@ -89,9 +94,11 @@ and reset it, ensuring states from previous scrips have been cleared. E.g.,
 `saw.connect(reset_server=True)`.
 
 
-## Selecting a SAW Server
+## Acquiring a SAW Server
 
-## Server executables
+There are several ways a server executable can be obtained.
+
+### Server executables
 
 An executable of the server is included in the SAW release/nightly tarballs.
 
@@ -138,17 +145,17 @@ container.)
 ### Building from Source
 
 If this repository is checked out and the build directions are successfully run,
-`cabal v2-which saw-remote-api` will indicate where the server executable has
-been stored.
+`cabal v2-exec which saw-remote-api` should indicate where the server executable has
+been stored by `cabal`.
 
 Alternatively `cabal v2-install saw-remote-api` should install the server
 executable into the user's `~/.cabal/bin` directory (or similar), which (if
-configured properly) should then appear as `saw-remote-api` in a user's `PATH`,
+configured properly) should then appear as `saw-remote-api` in a user's `PATH`.
 
 
 # Running Python SAW verification scripts
 
-Once the server is setup and any path variables are setup as necessary, the
+Once the server is setup and any path variables are setup as desired, the
 Python (>= v3.8) client can be installed using
 [`poetry`](https://python-poetry.org/docs/#installation) as follows:
 
@@ -162,3 +169,33 @@ Then the tests or individual scripts can be run as follows:
 $ poetry run python -m unittest discover tests/saw
 $ poetry run python tests/saw/test_salsa20.py
 ```
+
+If leveraging environment variables is undesirable, the scripts themselves can
+specify a command to launch the server, e.g.:
+
+```
+saw.connect(COMMAND)
+```
+
+where `COMMAND` is a command to launch a new SAW server in socket mode.
+
+Or a server URL can be specified directly in the script, e.g.:
+
+```
+saw.connect(url=URL)
+```
+
+where `URL` is a URL for a running SAW server in HTTP mode.
+
+## Running Verification Scripts from a clean state
+
+To ensure any previous server state is cleared when running a SAW Python script
+against a persistent server (e.g., one running in HTTP mode in a different process),
+the `reset_server` keyword can be passed to `saw.connect()`. E.g.,
+
+```
+saw.connect(url="http://localhost:8080/", reset_server=True)
+```
+
+will connect to a SAW server running at `http://localhost:8080/` and will
+guarantee any previous state on the server is cleared.

saw-remote-api/scripts/run_rpc_tests.sh

@@ -13,18 +13,20 @@ function run_test {
 echo "Setting up python environment for remote server clients..."
 poetry install
 
+# Ask cabal where the server is, and if that does work... check
+# the places CI will place the executable as a backup
 export SAW_SERVER=$(cabal v2-exec which saw-remote-api)
 if [[ -x "$SAW_SERVER" ]]; then
   echo "using saw-remote-api at $SAW_SERVER"
-else
-  # try the dist/bin folder CI puts executables in
+elif [[ -x "$DIR/../../dist/bin/saw-remote-api" ]]; then
   export SAW_SERVER="$DIR/../../dist/bin/saw-remote-api"
-  if [[ -x "$SAW_SERVER" ]]; then
   echo "using saw-remote-api at $SAW_SERVER"
-  else
-    echo "cabal could not locate saw-remote-api via the which command"
-    exit 1
-  fi
+elif [[ -x "$DIR/../../dist/bin/saw-remote-api.exe" ]]; then
+  export SAW_SERVER="$DIR/../../dist/bin/saw-remote-api.exe"
+  echo "using saw-remote-api at $SAW_SERVER"
+else
+  echo "could not locate saw-remote-api executable"
+  exit 1
 fi
 
 echo "Running saw-remote-api tests..."