emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
doomemacs/core/cli/upgrade.el
Henrik Lissner 6c0b7e1530
refactor!(cli): rewrite CLI framework libraries 
BREAKING CHANGE: this changes Doom's CLI framework in subtle ways, which
is listed in greater detail below. If you've never extended Doom's CLI,
then this won't affect you, but otherwise it'd be recommended you read
on below.

This commit focuses on the CLI framework itself and backports some
foundational changes to its DSL and how it resolves command line
arguments to CLIs, validates input, displays documentation, and persists
state across sessions -- and more. This is done in preparation for the
final stretch towarding completing the CLI rewrite (see #4273).

This is also an effort to generalize Doom's CLI (both its framework and
bin/doom), to increase it versatility and make it a viable dev tool for
other Doom projects (on our Github org) and beyond.

However, there is a *lot* to cover so I'll try to be brief:

- Refactor: generalize Doom's CLI framework by moving all bin/doom
  specific configuration/commands out of core-cli into bin/doom. This
  makes it easier to use bin/doom as a project-agnostic development
  tool (or for users to write their own).
- Refactor: change the namespace for CLI variables/functions from
  doom-cli-X to doom-X.
- Fix: subcommands being mistaken as arguments. "doom make index" will
  resolve to (defcli! (doom make index)) if it exists,
  otherwise (defcli! (doom make)) with "index" as an argument. Before
  this, it would resolve to the latter no matter what. &rest can
  override this; with (defcli! (doom make) (&rest args)), (defcli! (doom
  make index)) will never be invoked.
- Refactor!: redesign our output library (was core/autoload/output.el,
  is now core/autoload/print.el), and how our CLI framework buffers and
  logs output, and now merges logs across (exit! ...) restarts.
- Feat: add support for :before and :after pseudo commands. E.g.

    (defcli! (:before doom help) () ...)
    (defcli! (:after doom sync) () ...)

  Caveat: unlike advice, only one of each can be defined per-command.
- Feat: option arguments now have rudimentary type validation (see
  `doom-cli-option-arg-types`). E.g.

    (defcli! (doom foo) ((foo ("--foo" num))) ...)

  If NUM is not a numeric, it will throw a validation error.

  Any type that isn't in `doom-cli-option-arg-types` will be treated as a
  wildcard string type. `num` can also be replaced with a specification,
  e.g. "HOST[:PORT]", and can be formatted by using symbol quotes:
  "`HOST'[:`PORT']".
- Feat: it is no longer required that options *immediately* follow the command
  that defines them (but it must be somewhere after it, not before). E.g.
    With:
      (defcli! (:before doom foo) ((foo ("--foo"))) ...)
      (defcli! (doom foo baz) () ...)
    Before:
      FAIL: doom --foo foo baz
      GOOD: doom foo --foo baz
      FAIL: doom foo baz --foo
    After:
      FAIL: doom --foo foo baz
      GOOD: doom foo --foo baz
      GOOD: doom foo baz --foo
- Refactor: CLI session state is now kept in a doom-cli-context struct (which
  can be bound to a CLI-local variable with &context in the arglist):

    (defcli! (doom sync) (&context context)
      (print! "Command: " (doom-cli-context-command context)))

  These contexts are persisted across sessions (when restarted). This is
  necessary to support seamless script restarting (i.e. execve
  emulation) in post-3.0.
- Feat: Doom's CLI framework now understands "--". Everything after it will be
  treated as regular arguments, instead of sub-commands or options.
- Refactor!: the semantics of &rest for CLIs has changed. It used to be "all
  extra literal, non-option arguments". It now means *all* unprocessed
  arguments, and its use will suppress "unrecognized option" errors, and
  tells the framework not to process any further subcommands. Use &args
  if you just want "all literal arguments following this command".
- Feat: add new auxiliary keywords for CLI arglists: &context, &multiple,
  &flags, &args, &stdin, &whole, and &cli.
  - &context SYM: binds the currently running context to SYM (a
    `doom-cli-context` struct). Helpful for introspection or passing
    along state when calling subcommands by hand (with `call!`).
  - &stdin SYM: SYM will be bound to a string containing any input piped
    into the running script, or nil if none. Use
    `doom-cli-context-pipe-p` to detect whether the script has been
    piped into or out of.
  - &multiple OPTIONS...: allows all following OPTIONS to be repeated. E.g. "foo
    -x a -x b -x c" will pass (list ("-x" . "a") ("-x" . "b") ("-x" .
    "c")) as -x's value.
  - &flags OPTIONS...: All options after "&flags" get an implicit --no-* switch
    and cannot accept arguments. Will be set to :yes or :no depending on which flag is
    provided, and nil if the flag isn't provided. Otherwise, a default
    value can be specified in that options' arglist. E.g.

      (defcli! (doom foo) (&flags (foo ("--foo" :no))) ...)

    When called, this command sets FOO to :yes if --foo, :no if --no-foo, and
    defaults to :no otherwise.
  - &args SYM: this replaces what &rest used to be; it binds to SYM a
    list of all unprocessed (non-option) arguments.
  - &rest SYM: now binds SYM to a list of all unprocessed arguments, including
    options. This also suppresses "unrecognized option" errors, but will render
    any sub-commands inaccessible. E.g.

      (defcli! (doom make) (&rest rest) ...)
      ;; These are now inaccessible!
      (defcli! (doom make foo) (&rest rest) ...)
      (defcli! (doom make bar) (&rest rest) ...)
  - &cli SYM: binds SYM to the currently running `doom-cli` struct. Can also be
    obtained via `(doom-cli-get (doom-cli-context-command context))`. Possibly
    useful for introspection.
- feat: add defobsolete! macro for quickly defining obsolete commands.
- feat: add defalias! macro for quickly defining alias commands.
- feat: add defautoload! macro for defining an autoloaded command (won't
  be loaded until it is called for).
- refactor!: rename defcligroup! to defgroup! for consistency.
- fix: CLIs will now recursively inherit plist properties from parent
  defcli-group!'s (but will stack :prefix).
- refactor!: remove obsolete 'doom update':
- refactor!: further generalize 'doom ci'
  - In an effort to generalize 'doom ci' (so other Doom--or
    non-doom--projects can use it), all its subcommands have been
    changed to operate on the current working directory's repo instead
    of $EMACSDIR.
  - Doom-specific CI configuration was moved to .github/ci.el.
  - All 'doom ci' commands will now preload one of \$CURRENT_REPO_ROOT/ci.el or
    \$DOOMDIR/ci.el before executing.
- refactor!: changed 'doom env'
  - 'doom env {-c,--clear}' is now 'doom env {clear,c}'
  - -r/--reject and -a/--allow may now be specified multiple times
- refactor!: rewrote CLI help framework and error handling to be more
  sophisticated and detailed.
- feat: can now initiate $PAGER on output with (exit! :pager) (or use
  :pager? to only invoke pager is output is longer than the terminal is
  tall).
- refactor!: changed semantics+conventions for global bin/doom options
  - Single-character global options are now uppercased, to distinguish them from
    local options:
    - -d (for debug mode) is now -D
    - -y (to suppress prompts) is now -!
    - -l (to load elisp) is now -L
    - -h (short for --help) is now -?
  - Replace --yes/-y switches with --force/-!
  - -L/--load FILE: now silently ignores file errors.
  - Add --strict-load FILE: does the same as -L/--load, but throws an error if
    FILE does not exist/is unreadable.
  - Add -E/--eval FORM: evaluates arbitrary lisp before commands are processed.
  - -L/--load, --strict-load, and -E/--eval can now be used multiple times in
    one command.
  - Add --pager COMMAND to specify an explicit pager. Will also obey
    $DOOMPAGER envvar. Does not obey $PAGER.
- Fix #3746: which was likely caused by the generated post-script overwriting
  the old mid-execution. By salting the postscript filenames (with both an
  overarching session ID and a step counter).
- Docs: document websites, environment variables, and exit codes in
  'doom --help'
- Feat: add imenu support for def{cli,alias,obsolete}!

Ref: #4273
Fix: #3746
Fix: #3844
2022-06-18 23:53:12 +02:00

164 lines
7.3 KiB
EmacsLisp
Raw Blame History

;;; core/cli/upgrade.el -*- lexical-binding: t; -*-
;;; Commentary:
;;; Code:
(load! "packages")
;;
;;; Variables
(defvar doom-upgrade-url "https://github.com/doomemacs/doomemacs"
"The git repo url for Doom Emacs.")
(defvar doom-upgrade-remote "_upgrade"
"The name to use as our staging remote.")
;;
;;; Commands
(defcli! ((upgrade up))
((packages? ("-p" "--packages") "Only upgrade packages, not Doom")
&context context)
"Updates Doom and packages.
This requires that ~/.emacs.d is a git repo, and is the equivalent of the
following shell commands:
cd ~/.emacs.d
git pull --rebase
doom clean
doom sync -u"
(let* ((force? (doom-cli-context-suppress-prompts-p context))
(sync-cmd `("doom" "sync" "-u")))
(cond
(packages-only?
(doom-cli-call sync-cmd)
(print! (success "Finished upgrading Doom Emacs")))
((doom-cli-upgrade force? force?)
;; Reload Doom's CLI & libraries, in case there were any upstream changes.
;; Major changes will still break, however
(print! (item "Reloading Doom Emacs"))
(exit! "doom" "upgrade" "-p" (if force? "--force")))
((print! "Doom is up-to-date!")
(doom-cli-call sync-cmd)))))
;;
;;; Helpers
(defun doom-cli-upgrade (&optional auto-accept-p force-p)
"Upgrade Doom to the latest version non-destructively."
(let ((default-directory doom-emacs-dir)
process-file-side-effects)
(print! (start "Preparing to upgrade Doom Emacs and its packages..."))
(let* (;; git name-rev may return BRANCH~X for detached HEADs and fully
;; qualified refs in some other cases, so an effort to strip out all
;; but the branch name is necessary. git symbolic-ref (or
;; `vc-git--symbolic-ref') won't work; it can't deal with submodules.
(branch (replace-regexp-in-string
"^\\(?:[^/]+/[^/]+/\\)?\\(.+\\)\\(?:~[0-9]+\\)?$" "\\1"
(cdr (doom-call-process "git" "name-rev" "--name-only" "HEAD"))))
(target-remote (format "%s_%s" doom-repo-remote branch)))
(unless branch
(error (if (file-exists-p! ".git" doom-emacs-dir)
"Couldn't find Doom's .git directory. Was Doom cloned properly?"
"Couldn't detect what branch you're on. Is Doom detached?")))
;; We assume that a dirty .emacs.d is intentional and abort
(when-let (dirty (doom-upgrade--working-tree-dirty-p default-directory))
(if (not force-p)
(user-error "%s\n\n%s\n\n %s"
(format "Refusing to upgrade because %S has been modified."
(abbreviate-file-name doom-emacs-dir))
"Either stash/undo your changes or run 'doom upgrade -f' to discard local changes."
(string-join dirty "\n"))
(print! (item "You have local modifications in Doom's source. Discarding them..."))
(doom-call-process "git" "reset" "--hard" (format "origin/%s" branch))
(doom-call-process "git" "clean" "-ffd")))
(doom-call-process "git" "remote" "remove" doom-repo-remote)
(unwind-protect
(let (result)
(or (zerop (car (doom-call-process "git" "remote" "add" doom-repo-remote doom-repo-url)))
(error "Failed to add %s to remotes" doom-repo-remote))
(or (zerop (car (setq result (doom-call-process "git" "fetch" "--force" "--tags" doom-repo-remote (format "%s:%s" branch target-remote)))))
(error "Failed to fetch from upstream"))
(let ((this-rev (cdr (doom-call-process "git" "rev-parse" "HEAD")))
(new-rev (cdr (doom-call-process "git" "rev-parse" target-remote))))
(cond
((and (null this-rev)
(null new-rev))
(error "Failed to get revisions for %s" target-remote))
((equal this-rev new-rev)
(print! (success "Doom is already up-to-date!"))
nil)
((print! (item "A new version of Doom Emacs is available!\n\n Old revision: %s (%s)\n New revision: %s (%s)\n"
(substring this-rev 0 10)
(cdr (doom-call-process "git" "log" "-1" "--format=%cr" "HEAD"))
(substring new-rev 0 10)
(cdr (doom-call-process "git" "log" "-1" "--format=%cr" target-remote))))
(let ((diff-url
(format "%s/compare/%s...%s"
doom-repo-url
this-rev
new-rev)))
(print! "Link to diff: %s" diff-url)
(when (and (not auto-accept-p)
(y-or-n-p "View the comparison diff in your browser?"))
(print! (item "Opened github in your browser."))
(browse-url diff-url)))
(if (not (or auto-accept-p
(y-or-n-p "Proceed with upgrade?")))
(ignore (print! (error "Aborted")))
(print! (start "Upgrading Doom Emacs..."))
(print-group!
(doom-clean-byte-compiled-files)
(let ((straight-recipe (doom-upgrade--get-straight-recipe)))
(or (and (zerop (car (doom-call-process "git" "reset" "--hard" target-remote)))
(equal (cdr (doom-call-process "git" "rev-parse" "HEAD")) new-rev))
(error "Failed to check out %s" (substring new-rev 0 10)))
;; HACK It's messy to use straight to upgrade straight, due
;; to the potential for backwards incompatibility, so we
;; staticly check if Doom's `package!' declaration for
;; straight has changed. If it has, delete straight so
;; 'doom upgrade's second stage will install the new
;; version for us.
;;
;; Clumsy, but a better solution is in the works.
(unless (equal straight-recipe (doom-upgrade--get-straight-recipe))
(print! (item "Preparing straight for an update"))
(delete-directory (doom-path straight-base-dir "straight/repos/straight.el")
'recursive)))
(print! (item "%s") (cdr result))
t))))))
(ignore-errors
(doom-call-process "git" "branch" "-D" target-remote)
(doom-call-process "git" "remote" "remove" doom-repo-remote))))))
(defun doom-upgrade--working-tree-dirty-p (dir)
(cl-destructuring-bind (success . stdout)
(doom-call-process "git" "status" "--porcelain" "-uno")
(if (= 0 success)
(split-string stdout "\n" t)
(error "Failed to check working tree in %s" dir))))
(defun doom-upgrade--get-straight-recipe ()
(with-temp-buffer
(insert-file-contents (doom-path doom-core-dir "packages.el"))
(when (re-search-forward "(package! straight" nil t)
(goto-char (match-beginning 0))
(let ((sexp (sexp-at-point)))
(plist-put sexp :recipe
(eval (plist-get sexp :recipe)
t))))))
;;; upgrade.el ends here
Reference in a new issue View git blame Copy permalink