Reorganize scripts/ directory

scripts/build_debian-buster.sh

@@ -1,12 +1,9 @@
 #!/usr/bin/env bash
-
-# Ubuntu 20 (Groovy) / Debian Buster: end-2-end build
 #
-#     - this script should run to completion on a clean install of the
-#       OSes and produce a ready-to-use osc build
+# `build_debian-buster.sh`: performs an end-to-end build of OpenSim Creator
+# on Debian platforms
 #
-#     - run this from the repo root (opensim-creator) dir
-
+#     usage (must be ran in repository root): `bash build_debian-buster.sh`
 
 # error out of this script if it fails for any reason
 set -xeuo pipefail

scripts/build_emscripten.sh

@@ -1,4 +1,10 @@
 #!/usr/bin/env bash
+#
+# `build_emscripten.sh`: performs an end-to-end build of the `hellotriangle` demo
+# of OpenSim Creator using the Emscripten SDK (`emmake`, `emcc`, etc.) toolchain
+# to build a wasm version of the binary
+#
+#     usage (must be ran in repository root): `bash build_emscripten.sh`
 
 set -xeuo pipefail
 

scripts/build_linux_debugging.sh

@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
-
-# build OSC with all the necessary debugging bells and whistles
-# that are used during a release
+#
+# `build_linux_debugging.sh`: performs an end-to-end build of OpenSim Creator with
+# as many debugging options enabled as possible. This is usaully used to verify a
+# release, or lint the source code
+#
+#     usage (must be ran in repository root): `bash build_linux_debugging.sh`
 
 set -xeuo pipefail
 OSC_BUILD_CONCURRENCY=$(nproc)

scripts/build_linux_valgrind-compat.sh

@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
 
-# throwaway script for building and OSC that's compatible with valgrind
-# debugging on Ubuntu20
+# `build_linux_valgrind-compat`: performs an end-to-end build of OpenSim Creator
+# with build flags that make it valgrind-compatible. This is handy for debugging
+# things like memory accesses, segfaults, etc.
+#
+#     usage (must be ran in repository root): `bash build_linux_valgrind-compat.sh`
 
 set -xeuo pipefail
 

scripts/build_mac.sh

@@ -1,11 +1,9 @@
 #!/usr/bin/env bash
 
-# Mac Catalina: end-2-end build
+# `build_mac`: performs an end-to-end build of OpenSim Creator on the
+# mac platform
 #
-#     - this script should run to completion on a relatively clean
-#       Catalina (OSX 10.5) machine with xcode, CMake, etc. installed
-#
-#     - run this from the repo root (opensim-creator) dir
+#     usage (must be ran in repository root): `bash build_mac.sh`
 
 
 # error out of this script if it fails for any reason

scripts/build_windows.py

@@ -1,3 +1,10 @@
+#!/usr/bin/env python3
+
+# `build_windows`: performs an end-to-end build of OpenSim Creator on
+# the Windows platform
+#
+#     usage (run it from the root of the repository): `python3 build_windows.py`
+
 import argparse
 import logging
 import multiprocessing

scripts/bump_zenodo_details.py

@@ -1,3 +1,12 @@
+#!/usr/bin/env python3
+#
+# `bump_zenodo_details`: automatically updates relevant source files in
+# the repository (e.g. the README, CITATION.cff) to point at the latest
+# Zenodo release
+#
+#     usage: `python bump_zenodo_details.py` (follow the prompts)
+#            `git diff` (ensure it made sane changes)
+
 import datetime
 import re
 import subprocess

scripts/env_libasan.sh

@@ -1,4 +1,7 @@
-# usage (unix only): `source env_libasan.sh`
+# `env_libasan.sh`: sets up an environment for running libASAN-enabled
+# binaries with aggressive flags
+#
+#     usage (unix only): `source env_libasan.sh`
 
 # - these are libASAN options that I use when debugging OSC
 # - it assumes you have compiled OSC with libASAN, e.g.:

scripts/env_wsl2.sh

@@ -1,6 +1,6 @@
-# usage (unix only): `source env_wsl2.sh`
-
-# environment variables that can be handy in Windows 11's WSL2
+# `env_wsl2.sh`: sets up a WSL2 environment to use WSL2 optimally
+#
+#     usage (WSL2 unix terminal only): `source env_wsl2.sh`
 
 # force OSC to render via Mesa (see env_mesa_debugging.sh)
 # LIBGL_ALWAYS_SOFTWARE=1

scripts/format_sources.py

@@ -1,6 +1,13 @@
 #!/usr/bin/env python3
 
-# recursively adds trailing newline to any files missing one in the given dir
+# `format_sources`: applies basic text formatting to any files found in the
+# given (command-line argument) directories
+#
+# formatting steps:
+#
+# - ensures files have a trailing newline
+# - ensures files have stripped whitespace (i.e. no trailing whitespace)
+# - ensures files don't use tabs (it's a race war, or something)
 
 import argparse
 import os

scripts/generate_icon_files.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
 
-# this is a script for generating icon files that Mac (icns) and Windows (ico)
-# use
+# `generate_icon_files`: generates icon files from images that are compatible with
+# Mac's (icns) and Windows' (ico) icon systems
 #
-# guide:
+# usage:
 #
 # - open raw icon SVG in editor (e.g. inkscape)
 # - save the raw icon SVG as a high (e.g. 1024x1024) resolution PNG file (e.g. logoBIG.png)
@@ -20,7 +20,7 @@
 
 import argparse
 import os
-from PIL import Image  # pip install Pillow
+from PIL import Image  # `pip install Pillow`
 
 def convert(input_filename, output_filename):
     assert os.path.exists(input_filename)

scripts/get_osc_github_download_counts.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 
-# run this to get the download counters for osc on GitHub
+# `get_osc_github_download_counts`: print the GitHub download counters for
+# all releases of OpenSim Creator to the standard output
 
 import datetime
 import itertools

scripts/hellotriangle.html

@@ -120,7 +120,7 @@
     <span id='controls'>
       <span><input type="checkbox" id="resize">Resize canvas</span>
       <span><input type="checkbox" id="pointerLock" checked>Lock/hide mouse pointer &nbsp;&nbsp;&nbsp;</span>
-      <span><input type="button" value="Fullscreen" onclick="Module.requestFullscreen(document.getElementById('pointerLock').checked, 
+      <span><input type="button" value="Fullscreen" onclick="Module.requestFullscreen(document.getElementById('pointerLock').checked,
                                                                                 document.getElementById('resize').checked)">
       </span>
     </span>

scripts/mac_suppressions.supp

@@ -1,4 +1,8 @@
-# usage: ASAN_OPTIONS=detect_leaks=1 LSAN_OPTIONS=suppressions=suppressions.supp ./osc-build/tests/TestOpenSimCreator/TestOpenSimCreator
+# `mac_suppressions.supp`: a list of known leaks/issues in the binaries
+#  that are spuriously detected by libASAN
+#
+#     usage: ASAN_OPTIONS=detect_leaks=1 LSAN_OPTIONS=suppressions=suppressions.supp ./osc-build/tests/TestOpenSimCreator/TestOpenSimCreator
+
 leak:SDL
 leak:NS
 leak:dyld4
@@ -8,4 +12,3 @@ leak:HIView
 leak:glDrawElementsInstanced
 leak:glDrawElementsBaseVertex
 leak:CUICoreThemeRenderer
-