feat(install): install system-wide under /usr/local with preflight checks

- abort early with a clear error if mvn is missing or the available
  JDK is older than 21 (handles legacy 1.8 version scheme)
- hardcode the prefix to /usr/local so all users get the jar,
  launcher and desktop entry; drop CRT_BASIC_PREFIX and the per-user
  ~/.local default; require sudo and fail fast before building
- hide the .desktop entry from the app menu (NoDisplay) while keeping
  the text/x-basic "Open With" association
- document dependencies, install layout and window mouse-grab
  behavior in index.org; refresh crtbasic.png

diff --git a/Documentation/crtbasic.png b/Documentation/crtbasic.png
index 710568a..7c03076 100644 (file)
Binary files a/Documentation/crtbasic.png and b/Documentation/crtbasic.png differ

diff --git a/Documentation/index.org b/Documentation/index.org
index b1abd37..15b84da 100644 (file)
--- a/Documentation/index.org
+++ b/Documentation/index.org
@@ -20,23 +20,49 @@
 *CRT Basic* is an interpreter for the BASIC programming language,
 written in pure Java. It runs classic =.bas= programs.
 
-You can find [[https://www3.svjatoslav.eu/projects/qbasicapps/][here collection of example BASIC programs]] that can be
-executed by *CRT Basic*.
+When started from commandline, it opens new graphical window where you
+will see program output. When window is resized, it scales virtual
+display with program output. When you click on the window, it will
+grab mouse cursor and will redirect mouse movement and button presses
+to the running BASIC program.
+
+Press *CTRL + F10* to release mouse cursor.
+
+You can find [[https://www3.svjatoslav.eu/projects/qbasicapps/][here collection of example BASIC programs]] that are
+compatible with *CRT Basic*.
 
 * Quick start
 :PROPERTIES:
 :CUSTOM_ID: quick-start
 :END:
 
-The interpreter requires Java JDK 21 or newer.
+To compile and install CRT Basic you need following dependencies:
 
-#+BEGIN_SRC sh
-  cd /path/to/crtbasic
-  ./install.sh                          # installs to ~/.local (CRT_BASIC_PREFIX to override)
+- Java JDK 21 or newer (set =JAVA_HOME= if it is not the default =java=)
+- Apache Maven (=mvn= on =PATH=)
 
-  crtbasic program.bas                  # interactive window
+Installation procedure:
+#+BEGIN_SRC sh
+  cd /path/to/crtbasic/project
+  sudo ./install.sh                     # installs system-wide under /usr/local
 #+END_SRC
 
+The installer builds the jar with Maven and installs it under
+=/usr/local=, so every user on the machine gets it:
+
+| File                                             | Purpose                                                       |
+|--------------------------------------------------+---------------------------------------------------------------|
+| =/usr/local/share/crtbasic/crt-basic.jar=        | the interpreter itself                                        |
+| =/usr/local/bin/crtbasic=                        | launcher script: =exec java -jar ... "$@"=                    |
+| =/usr/local/share/applications/crtbasic.desktop= | "Open With" entry for =.bas= files (hidden from the app menu) |
+
+No =PATH= setup is needed: =/usr/local/bin= is on the default =PATH=
+for all users.
+
+Now you can run BASIC programs like this:
+#+BEGIN_SRC sh
+  crtbasic my-program.bas
+#+END_SRC
 
 * Architecture at a glance
 :PROPERTIES:

diff --git a/install.sh b/install.sh
index 6a61c95..6d0fb03 100755 (executable)
--- a/install.sh
+++ b/install.sh
@@ -1,14 +1,50 @@
 #!/bin/sh
 # CRT Basic installer: builds the jar and installs a `crtbasic` command.
 #
-# Default install location is per-user (~/.local); override with:
-#   CRT_BASIC_PREFIX=/usr/local ./install.sh        (needs write permission)
-#
-# After install, ensure $CRT_BASIC_PREFIX/bin is on your PATH.
+# Installs system-wide under /usr/local (jar in /usr/local/share/crtbasic,
+# launcher in /usr/local/bin, desktop entry in /usr/local/share/applications)
+# so every user gets it. Run with sudo. /usr/local/bin is on the default
+# PATH, so no PATH setup is needed.
 
 set -e
 
-PREFIX="${CRT_BASIC_PREFIX:-$HOME/.local}"
+fail() { echo "error: $*" >&2; exit 1; }
+
+# --- Dependency checks (abort early with a clear message) --------------
+
+command -v mvn >/dev/null 2>&1 \
+    || fail "Apache Maven (mvn) not found on PATH. Install Maven and retry."
+
+JAVA_BIN=""
+if [ -n "$JAVA_HOME" ] && [ -x "$JAVA_HOME/bin/java" ]; then
+    JAVA_BIN="$JAVA_HOME/bin/java"
+else
+    JAVA_BIN="$(command -v java || true)"
+fi
+[ -n "$JAVA_BIN" ] \
+    || fail "java not found. Install JDK 21 or newer, or set JAVA_HOME."
+
+JAVA_VER="$("$JAVA_BIN" -version 2>&1 \
+    | sed -n 's/.*version "\([^"]*\)".*/\1/p' | head -n 1)"
+[ -n "$JAVA_VER" ] \
+    || fail "could not parse version from '$JAVA_BIN -version'."
+
+JAVA_MAJOR="${JAVA_VER%%.*}"
+# Legacy scheme: 1.8.0_XXX means major version 8
+if [ "$JAVA_MAJOR" = "1" ]; then
+    JAVA_MAJOR="$(echo "$JAVA_VER" | cut -d. -f2)"
+fi
+case "$JAVA_MAJOR" in
+    ''|*[!0-9]*) fail "unparsable java version string: '$JAVA_VER'" ;;
+esac
+[ "$JAVA_MAJOR" -ge 21 ] \
+    || fail "JDK 21 or newer required (found $JAVA_VER at $JAVA_BIN)."
+
+echo "Using java $JAVA_VER ($JAVA_BIN)"
+
+PREFIX=/usr/local
+[ -w "$PREFIX" ] || fail "cannot write to $PREFIX — run this installer with sudo."
+
 PROJECT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
 echo "Building CRT Basic..."
@@ -31,8 +67,10 @@ exec java -jar "$PREFIX/share/crtbasic/crt-basic.jar" "\$@"
 EOF
 chmod +x "$PREFIX/bin/crtbasic"
 
-# Desktop integration: appear in "Open With" for .bas files (text/x-basic).
-APPS_DIR="$HOME/.local/share/applications"
+# Desktop integration: "Open With" for .bas files (text/x-basic).
+# NoDisplay=true keeps it out of the app menu — it only makes sense
+# launched with a file, never on its own.
+APPS_DIR="$PREFIX/share/applications"
 mkdir -p "$APPS_DIR"
 cat > "$APPS_DIR/crtbasic.desktop" <<EOF
 [Desktop Entry]
@@ -43,10 +81,8 @@ GenericName=BASIC Interpreter
 Comment=Run BASIC programs on a virtual VGA
 Exec=$PREFIX/bin/crtbasic %f
 Terminal=false
-Categories=Development;IDE;
+NoDisplay=true
 MimeType=text/x-basic;
-Keywords=basic;dos;interpreter;
-StartupNotify=true
 EOF
 chmod 644 "$APPS_DIR/crtbasic.desktop"
 update-desktop-database "$APPS_DIR" 2>/dev/null || true