Improve explanation wrt Minimal Racket; closes #744

As the main entry use a "shim" module with minimal imports, that
dynamic-require's everything else under an exn handler that looks for
exn:fail:syntax:missing-module. Report that to the front end, which
uses a new buffer to surface a message and advice for end user --
which is much better than something flashing by the in the echo area
and then only being viewable if user opens the *Messages* buffer.

While we have the hood open, do something similar for the error
regarding not having a sufficiently new version of Racket.

Author: greghendershott

racket-cmd.el

@@ -1,6 +1,6 @@
 ;;; racket-cmd.el -*- lexical-binding: t; -*-
 
-;; Copyright (c) 2013-2022 by Greg Hendershott.
+;; Copyright (c) 2013-2022, 2025 by Greg Hendershott.
 ;; Portions Copyright (C) 1985-1986, 1999-2013 Free Software Foundation, Inc.
 
 ;; Author: Greg Hendershott
@@ -75,6 +75,7 @@ Before doing anything runs the hook `racket-stop-back-end-hook'."
   ;; Avoid excess processes/buffers like "racket-process<1>".
   (when (racket--cmd-open-p)
     (racket--cmd-close))
+  (racket--kill-startup-error-buffer)
   ;; Give the process buffer the current values of some vars; see
   ;; <https://github.com/purcell/envrc/issues/22>.
   (cl-letf* (((default-value 'process-environment) process-environment)
@@ -93,7 +94,7 @@ Before doing anything runs the hook `racket-stop-back-end-hook'."
                     :sentinel #'ignore))
            (local-p (racket--back-end-local-p back-end))
            (main-dot-rkt (expand-file-name
-                          "main.rkt"
+                          "shim.rkt"
                           (if local-p
                               racket--rkt-source-dir
                             (racket--ensure-updated-back-end-on-remote))))
@@ -214,6 +215,8 @@ Although mostly these are 1:1 responses to command requests, some
 like \"logger\", \"debug-break\", and \"hash-lang\" are
 notifications."
   (pcase response
+    (`(startup-error ,kind ,data)
+     (run-at-time 0.001 nil #'racket--on-startup-error kind data))
     (`(logger ,str)
      (run-at-time 0.001 nil #'racket--logger-on-notify back-end str))
     (`(debug-break . ,response)
@@ -362,6 +365,48 @@ in a specific namespace."
                        (error "Unknown response to command %S from %S to %S:\n%S"
                               command-sexpr buf name v)))))))
 
+;;; Back end startup error buffer
+
+(defconst racket--startup-error-buffer-name
+  "*Racket Mode back end startup failure*")
+
+(defun racket--kill-startup-error-buffer ()
+  (let ((buf (get-buffer racket--startup-error-buffer-name)))
+    (when (buffer-live-p buf)
+      (kill-buffer buf))))
+
+(defun racket--on-startup-error (kind data)
+  (let ((buf (get-buffer-create racket--startup-error-buffer-name)))
+    (with-current-buffer buf
+      (unless (eq major-mode 'special-mode)
+        (special-mode))
+      (visual-line-mode 1)
+      (let ((buffer-read-only nil))
+        (erase-buffer)
+        (pop-to-buffer buf)
+        (pcase kind
+          ('missing-module
+           (let ((url "https://racket-mode.com/#Minimal-Racket-1"))
+             (insert "The Racket Mode back end could not start because it was unable to load the module "
+                     ?' data ?' "."
+                     "\n\n"
+                     "This could be because you did not install the full \"main distribution\" of Racket, but instead installed only \"Minimal Racket\" (the default when using homebrew)."
+                     "\n\n"
+                     "In that case, you will need either to install the full main distribution, or, manually install certain additional Racket packages."
+                     "\n\n"
+                     "Please see ")
+             (save-excursion ;leave point at start of link, for handy RET
+               (insert-button url
+                              'url url
+                              'face 'link
+                              'follow-link t
+                              'action (lambda (button)
+                                        (when-let (url (button-get button 'url))
+                                          (browse-url url))))
+               (insert "."))))
+          (_
+           (insert data)))))))
+
 (provide 'racket-cmd)
 
 ;; racket-cmd.el ends here

racket/main.rkt

@@ -1,4 +1,4 @@
-;; Copyright (c) 2013-2022 by Greg Hendershott.
+;; Copyright (c) 2013-2025 by Greg Hendershott.
 ;; SPDX-License-Identifier: GPL-3.0-or-later.
 
 #lang racket/base
@@ -11,13 +11,22 @@
          "command-server.rkt"
          (only-in "image.rkt" set-use-svg?!))
 
+(provide main)
+
+;;;(require does-not-exist) ;;TESTING
+
 (define (assert-racket-version minimum-version)
   (define actual-version (version))
   (unless (version<=? minimum-version actual-version)
-    (error '|Racket Mode back end| "Need Racket ~a or newer but ~a is ~a"
-           minimum-version
-           (find-executable-path (find-system-path 'exec-file))
-           actual-version)))
+    ;; Write a "notification" for the Emacs front end and exit.
+    (writeln `(startup-error
+               other
+               ,(format "Racket Mode needs Racket ~a or newer but ~a is ~a."
+                        minimum-version
+                        (find-executable-path (find-system-path 'exec-file))
+                        actual-version)))
+    (flush-output)
+    (exit 14)))
 
 (define (macos-sequoia-or-newer?)
   (and (eq? 'macosx (system-type 'os))
@@ -30,7 +39,7 @@
                   (and (valid-version? ver)
                        (version<=? "15.0" ver))))))))
 
-(module+ main
+(define (main)
   (assert-racket-version (if (macos-sequoia-or-newer?)
                              "8.14.0.4" ;issue #722
                              "6.12"))   ;general requirement

racket/shim.rkt

@@ -0,0 +1,29 @@
+;; Copyright (c) 2025 by Greg Hendershott.
+;; SPDX-License-Identifier: GPL-3.0-or-later.
+
+#lang racket/base
+
+;; A "shim" that handles module import errors when starting the back
+;; end.
+;;
+;; Motivation: Supply more-helpful information in case people are
+;; using Minimal Racket; #744.
+
+;; Limit imports to those in Minimal Racket:
+(require racket/runtime-path)
+
+(define-runtime-path main.rkt "main.rkt")
+
+;; Write a "notification" for the Emacs front end and exit.
+(define (missing-module e)
+  (writeln `(startup-error
+             missing-module
+             ,(format "~a" (exn:fail:syntax:missing-module-path e))))
+  (flush-output)
+  (exit 13))
+
+(module+ main
+  (define main
+    (with-handlers ([exn:fail:syntax:missing-module? missing-module])
+      (dynamic-require main.rkt 'main)))
+  (main))