doom-emacs/bin/doom

#!/usr/bin/env sh
:; # -*- mode: emacs-lisp; lexical-binding: t -*-
:; case "$EMACS" in *term*) EMACS=emacs ;; *) EMACS="${EMACS:-emacs}" ;; esac
:; emacs="$EMACS -q --no-site-file --no-x-resources --no-splash --batch"
:; tmpdir=`$emacs --eval '(princ (temporary-file-directory))' 2>/dev/null`
:; [ -z "$tmpdir" ] && { >&2 echo "Error: failed to run Emacs with command '$EMACS'"; >&2 echo; >&2 echo "Are you sure Emacs is installed and in your \$PATH?"; exit 1; }
:; export __DOOMPID="${__DOOMPID:-$$}"
:; export __DOOMSTEP="$((__DOOMSTEP+1))"
:; export __DOOMGEOM="${__DOOMGEOM:-`tput cols 2>/dev/null`x`tput lines 2>/dev/null`}"
:; export __DOOMGPIPE=${__DOOMGPIPE:-$__DOOMPIPE}
:; export __DOOMPIPE=; [ -t 0 ] || __DOOMPIPE="${__DOOMPIPE}0"; [ -t 1 ] || __DOOMPIPE="${__DOOMPIPE}1"
:; $emacs --load "$0" -- "$@" || exit=$?
:; [ "${exit:-0}" -eq 254 ] && { sh "${tmpdir}/doom.${__DOOMPID}.${__DOOMSTEP}.sh" "$0" "$@" && true; exit="$?"; }
:; exit $exit

;; This magical mess of a shebang is necessary for any script that relies on
;; Doom's CLI framework, because Emacs' tty libraries and capabilities are too
;; immature (borderline non-existent) at the time of writing (28.1). This
;; shebang sets out to accomplish these three goals:
;;
;; 1. To produce a more helpful error if Emacs isn't installed or broken. It
;;    must do so without assuming whether $EMACS is a shell command (e.g. 'snap
;;    run emacs') or an absolute path (to an emacs executable). I've avoided
;;    'command -v $EMACS' for this reason.
;;
;; 2. To allow this Emacs session to "exit into" a child process (since Elisp
;;    lacks an analogue for exec system calls) by calling an auto-generated and
;;    self-destructing "exit script" if the parent Emacs process exits with code
;;    254. It takes care to prevent nested child instances from clobbering the
;;    exit script.
;;
;; 3. To expose some information about the terminal and session:
;;    - $__DOOMGEOM holds the dimensions of the terminal (W . H).
;;    - $__DOOMPIPE indicates whether the script has been piped (in and/or out).
;;    - $__DOOMGPIPE indicates whether one of this process' parent has been
;;      piped to/from.
;;    - $__DOOMPID is a unique identifier for the parent script, so
;;      child processes can identify which persistent data files (like logs) it
;;      has access to.
;;    - $__DOOMSTEP counts how many levels deep we are in the dream (appending
;;      this to the exit script's filename avoids child processes clobbering the
;;      same exit script and causing read errors).
;;    - $TMPDIR (or $TEMP and $TMP on Windows) aren't guaranteed to have values,
;;      and mktemp isn't available on all systems, but you know what is? Emacs!
;;      So I use it to print `temporary-file-directory'. And it seconds as a
;;      quick sanity check for Emacs' existence (for goal #1).
;;
;; Other weird facts about this shebang line:
;;
;; - The :; hack exploits properties of : and ; in shell scripting and elisp to
;;   allow shell script and elisp to coexist in the same file without either's
;;   interpreter throwing foreign syntax errors:
;;
;;   - In elisp, ":" is a valid keyword symbol literal; it evaluates to itself
;;     and has no side-effect.
;;   - In the shell, ":" is a valid command that does nothing and ignores its
;;     arguments.
;;   - In elisp, ";" begins a comment. I.e. the interpreter ignores everything
;;     after it.
;;   - In the shell, ";" is a command separator.
;;
;;   Put together, plus a strategically placed exit call, the shell will read
;;   one part of this file and ignore the rest, while the elisp interpreter will
;;   do the opposite.
;; - I intentionally avoid loading site files, so lisp/doom-cli.el can load them
;;   by hand later. There, I can suppress and deal with unhelpful warnings (e.g.
;;   "package cl is deprecated"), "Loading X...DONE" spam, and any other
;;   disasterous side-effects.
;;
;;   But be careful not to use -Q! It implies --no-site-lisp, which omits the
;;   site-lisp directory from `load-path'.
;; - POSIX-compliancy is paramount: there's no guarantee what /bin/sh will be
;;   symlinked to in the esoteric OSes/distros Emacs users use.
;; - The user may have a noexec flag set on /tmp, so pass the exit script to
;;   /bin/sh rather than executing them directly.

;; Doom's core sets up everything we need; including `doom-*-dir' variables,
;; universal defaults, and autoloads for doom-*-initialize functions.
(condition-case e
    (let ((load-prefer-newer t))
      (load (expand-file-name
             "../early-init" (file-name-directory (file-truename load-file-name)))
            nil 'nomessage))
  ;; Prevent ugly backtraces for trivial errors
  (user-error (message "Error: %s" (cadr e))
              (kill-emacs 2)))

;; UX: Abort if the user is using 'doom' as root, unless ~/.emacs.d is owned by
;;   root, in which case we assume the user genuinely wants root to be their
;;   primary user account for Emacs.
(when (equal (user-real-uid) 0)
  (unless (= 0 (file-attribute-user-id (file-attributes user-emacs-directory)))
    (message
     (concat
      "Error: this script was executed as root, which is likely not what you want.\n"
      "It will cause file permissions errors later, when you run Doom as another\n"
      "user.\n\n"
      "If this really *is* what you want, then change the owner of your Emacs\n"
      "config to root:\n\n"
      ;; TODO Add cmd.exe/powershell commands
      "  chown root:root -R " (abbreviate-file-name user-emacs-directory) "\n\n"
      "Aborting..."))
    (kill-emacs 2)))


;;
;;; Entry point

(defcli! doom (&args _command)
  "A command line interface to Doom Emacs.

Includes package management, diagnostics, unit tests, and byte-compilation.

This tool also makes it trivial to launch Emacs out of a different folder or
with a different private module.

ENVIRONMENT VARIABLES:
  `$EMACS'
    The Emacs executable or command to use for any Emacs operations in this or
    other Doom CLI shell scripts (default: first emacs found in `$PATH').

  `$EMACSDIR'
    The location of your Doom Emacs installation (defaults to ~/.config/emacs or
    ~/.emacs.d; whichever is found first). This is *not* your private Doom
    configuration. The `--emacsdir' option also sets this variable.

  `$DOOMDIR'
    The location of your private configuration for Doom Emacs (defaults to
    ~/.config/doom or ~/.doom.d; whichever it finds first). This is *not* the
    place you've cloned doomemacs/doomemacs to. The `--doomdir' option also sets
    this variable.

  `$DOOMPAGER'
    The pager to invoke for large output (default: \"less +g\"). The `--pager'
    option also sets this variable.

  `$DOOMPROFILE'
    (Not implemented yet) Which Doom profile to activate (default: \"current\").

  `$DOOMPROFILESDIR'
    (Not implemented yet) Where to find or write generated Doom profiles
    (default: `$EMACSDIR'/profiles).

EXIT CODES:
  0        Successful run
  1        General internal error
  2        Error with Emacs/Doom install or execution context
  3        Unrecognized user input error
  4        Command not found, or is incorrect/deprecated
  5        Invalid, missing, or extra options/arguments
  6-49     Reserved for Doom
  50-200   Reserved for custom user codes
  254      Successful run (but then execute `doom-cli-restart-script')
  255      Uncaught internal errors

SEE ALSO:
  https://doomemacs.org               Homepage
  https://docs.doomemacs.org          Official documentation
  https://discourse.doomemacs.org     Discourse (discussion & support forum)
  https://doomemacs.org/discord       Discord chat server
  https://doomemacs.org/roadmap       Development roadmap
  https://git.doomemacs.org           Shortcut to Github org
  https://git.doomemacs.org/todo      Global issue tracker"
  :partial t)

(defcli! :before
    ((force?   ("-!" "--force")   "Suppress prompts by auto-accepting their consequences")
     (debug?   ("-D" "--debug")   "Enable verbose output")
     (doomdir  ("--doomdir" dir)  "Use Doom config living in `DIR' (e.g. ~/.doom.d)")
     (emacsdir ("--emacsdir" dir) "Use Doom install living in `DIR' (e.g. ~/.emacs.d)")
     (pager    ("--pager" cmd)    "Pager command to use for large output")
     (profile  ("--profile" name) "Use profile named NAME")
     (bench?   ("--benchmark")    "Always display the benchmark")
     &flags
     (color?   ("--color") "Whether or not to show ANSI color codes")
     &multiple
     (loads    ("-L" "--load" "--strict-load" file) "Load elisp `FILE' before executing `COMMAND'")
     (evals    ("-E" "--eval" form) "Evaluate `FORM' before executing commands")
     &input input
     &context context
     &args _)
  "OPTIONS:
  -E, -eval
    Can be used multiple times.

  -L, --load, --strict-load
    Can be used multiple times to load multiple files. Both -L and --load will
    silently fail on missing files, but --strict-load won't.

    Warning: files loaded this way load too late to define new commands. To
    define commands, do so from `$DOOMDIR'/cli.el, `$DOOMDIR'/init.el, or a
    .doomrc file in the current project tree."
  (when bench?
    (setq doom-cli-benchmark-threshold 'always))
  (when color?
    (setq doom-print-backend (if (eq color? :yes) 'ansi)))
  (when pager
    (setq doom-cli-pager pager))
  (when force?
    (setf (doom-cli-context-suppress-prompts-p context) t)
    (doom-log "User requested all prompts be suppressed"))
  ;; For these settings to take full effect, the script must be restarted:
  (when (or debug?
            profile
            emacsdir
            doomdir)
    (let (omit)
      (when debug?
        (setenv "DEBUG" "1")
        (setq init-file-debug t)
        (push "--debug" omit))
      (when profile
        (setenv "DOOMPROFILE" profile)
        (push "--profile=" omit))
      (when emacsdir
        (setenv "EMACSDIR" emacsdir)
        (push "--emacsdir=" omit))
      (when doomdir
        (setenv "DOOMDIR" doomdir)
        (push "--doomdir=" omit))
      (exit! :restart :omit omit)))
  ;; Load extra files and forms, as per given options.
  (dolist (file loads)
    (load (doom-path (cdr file))
          (not (equal (car file) "--strict-load"))
          (not init-file-debug) t))
  (dolist (form evals)
    (eval (read (cdr form)) t)))


;;
;;; Load user config + commands

;; Load $DOOMDIR/init.el, to read the user's `doom!' block and give users an
;; opportunity to customize the CLI environment, if they like. Otherwise, they
;; can do so in .doomrc or .doomproject.
(load! doom-module-init-file doom-user-dir t)

;; There are a lot of CLIs, and some have expensive initialization, so best we
;; load them lazily.
(let ((dir (doom-path doom-core-dir "cli")))
  ;; Library for generating autoloads files for Doom modules & packages.
  (load! "autoloads" dir)

  (defgroup!
    :prefix 'doom
    ;; Import this for implicit 'X help' commands for your script:
    (defalias! ((help h)) (:root :help))
    ;; And suggest its use when errors occur.
    (add-to-list 'doom-help-commands "%p h[elp] %c")

    (defgroup! "Config Management"
      :docs "Commands for maintaining your Doom Emacs configuration."
      (defautoload! ((sync s)))
      (defautoload! ((upgrade up)))
      (defautoload! (env))
      (defautoload! ((build b purge p rollback)) "packages")
      (defautoload! ((install i)))
      (defautoload! ((compile c)))
      (defautoload! (clean) "compile")

      ;; TODO Post-3.0 commands
      ;; (load! "gc" dir)
      ;; (load! "module" dir)
      ;; (load! "nuke" dir)
      ;; (load! "package" dir)
      ;; (load! "profile" dir)
      ;; (defobsolete! ((compile c)) (sync "--compile") "v3.0.0")
      ;; (defobsolete! ((build b))   (sync "--rebuild") "v3.0.0")
      )

    (defgroup! "Diagnostics"
      :docs "Commands for troubleshooting and debugging Doom."
      (defautoload! ((doctor doc)))
      (defautoload! (info))
      (defalias! ((version v)) (:root :version)))

    (defgroup! "Development"
      :docs "Commands for developing or launching Doom."
      (defautoload! (ci))
      (defautoload! (make))
      (defautoload! (run))

      ;; FIXME Test framework
      ;; (load! "test" dir)
      )

    (let ((cli-file "cli"))
      (defgroup! "Module commands"
        (dolist (key (hash-table-keys doom-modules))
          (when-let (path (plist-get (gethash key doom-modules) :path))
            (defgroup! :prefix (format "+%s" (cdr key))
              (load! cli-file path t)))))

      (doom-log "Loading $DOOMDIR/cli.el")
      (load! cli-file doom-user-dir t))

    ;; Allow per-project Doom settings in .doom files.
    (let (doomrc)
      (cond
       ((setq doomrc (getenv "DOOMRC"))
        (load! doomrc))
       ((setq doomrc (locate-dominating-file default-directory ".doomrc"))
        (load! ".doomrc" doomrc)))
      (when doomrc
        (doom-log "Loaded doomrc: %s" doomrc)))))


;;
;;; Let 'er rip

(run! "doom" (cdr (member "--" argv)))

;;; doom ends here, unless...