el-get-core.el 19.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
;;; el-get-core.el --- Manage the external elisp bits and pieces you depend upon
;;
;; Copyright (C) 2010-2011 Dimitri Fontaine
;;
;; Author: Dimitri Fontaine <dim@tapoueh.org>
;; URL: http://www.emacswiki.org/emacs/el-get
;; GIT: https://github.com/dimitri/el-get
;; Licence: WTFPL, grab your copy here: http://sam.zoy.org/wtfpl/
;;
;; This file is NOT part of GNU Emacs.
;;
;; Install
13
;;     Please see the README.md file from the same distribution
14 15 16 17 18 19 20 21 22 23 24 25 26

;;; Commentary:
;;
;; el-get-core provides basic el-get API, intended for developpers of el-get
;; and its methods.  See the methods directory for implementation of them.
;;

(require 'dired)
(require 'cl)            ; needed for `remove-duplicates'
(require 'simple)        ; needed for `apply-partially'
(require 'bytecomp)
(require 'autoload)

27 28 29
(declare-function el-get-package-def "el-get-recipes" (package))
(declare-function el-get-installation-failed "el-get" (package signal-data))

30 31 32 33 34 35 36 37 38 39 40
(defun el-get-print-to-string (object &optional pretty)
  "Return string representation of lisp object.

Unlike the Emacs builtin printing functions, this ignores
`print-level' and `print-length', ensuring that as much as
possible the returned string will be a complete representation of
the original object."
  (let (print-level print-length)
    (funcall (if pretty #'pp-to-string #'prin1-to-string)
             object)))

41 42 43
(defun el-get-verbose-message (format &rest arguments)
  (when el-get-verbose (apply 'message format arguments)))

44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
(defsubst el-get-plist-keys (plist)
  "Return a list of all keys in PLIST.

Duplicates are removed."
  (remove-duplicates
   (loop for (k _) on plist by #'cddr
         collect k)
   :test #'eq))

(defsubst el-get-keyword-name (keyword)
  "Return the name of KEYWORD.

This is equivalent to `symbol-name' but it only works on keywords
and it strips the leading colon.

This raises an error if KEYWORD is not a keyword."
  (or (keywordp keyword)
      (error "Not a keyword: %S" keyword))
  (substring (symbol-name keyword) 1))

64 65 66 67

;;
;; el-get-methods support, those are like backends.
;;
68 69 70 71 72
(defvar el-get-methods nil
  "Register methods that el-get can use to fetch and update a given package.

The methods list is a PLIST, each entry has a method name
property which value is another PLIST, which must contain values
73 74 75
for :install, :install-hook, :update, :remove, :remove-hook
and :checksum properties. Those should be the elisp functions to
call for doing the named package action in the given method.")
76

77 78 79 80
(defun el-get-method-defined-p (name)
  "Returns t if NAME is a known el-get install method backend, nil otherwise."
  (and (el-get-method name :install) t))

81
(defun* el-get-register-method (name &key install update remove
82 83
                                     install-hook update-hook remove-hook
                                     compute-checksum guess-website)
84
  "Register the method for backend NAME, with given functions"
85 86 87 88 89 90 91 92
  (let (method-def)
    (loop for required-arg in '(install update remove)
          unless (symbol-value required-arg)
          do (error "Missing required argument: :%s" required-arg)
          do (setq method-def
                   (plist-put method-def
                              (intern (format ":%s" required-arg))
                              (symbol-value required-arg))))
93
    (loop for optional-arg in '(install-hook update-hook remove-hook
Ryan C. Thompson's avatar
Ryan C. Thompson committed
94 95 96 97 98 99
                                             compute-checksum guess-website)
          if (symbol-value optional-arg)
          do (setq method-def
                   (plist-put method-def
                              (intern (format ":%s" optional-arg))
                              (symbol-value optional-arg))))
100
    (setq el-get-methods (plist-put el-get-methods name method-def))))
101

102 103 104
(put 'el-get-register-method 'lisp-indent-function
     (get 'prog1 'lisp-indent-function))

105
(defun* el-get-register-derived-method (name derived-from-name
106
                                             &rest keys &key &allow-other-keys)
107 108 109 110 111 112
  "Register the method for backend NAME.

Defaults for all optional arguments are taken from
already-defined method DERIVED-FROM-NAME."
  (unless (el-get-method-defined-p derived-from-name)
    (error "Cannot derive new el-get method from unknown method %s" derived-from-name))
113
  (apply #'el-get-register-method name (append keys (plist-get el-get-methods derived-from-name))))
114

115 116 117
(put 'el-get-register-derived-method 'lisp-indent-function
     (get 'prog2 'lisp-indent-function))

118 119 120
(defun el-get-register-method-alias (name old-name)
  "Register NAME as an alias for install method OLD-NAME."
  (el-get-register-derived-method name old-name))
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141


;;
;; "Fuzzy" data structure handling
;;
;; In el-get-sources, single elements are often allowed instead of a
;; list, and strings and symbols are often interchangeable.
;; Presumably it's easier for users who don't use the customization
;; interface to write such structures as raw elisp.
;;
;;;  "Fuzzy" data structure conversion utilities
(defun el-get-as-string (symbol-or-string)
  "If STRING-OR-SYMBOL is already a string, return it.  Otherwise
convert it to a string and return that."
  (if (stringp symbol-or-string) symbol-or-string
    (symbol-name symbol-or-string)))

(defun el-get-as-symbol (string-or-symbol)
  "If STRING-OR-SYMBOL is already a symbol, return it.  Otherwise
convert it to a symbol and return that."
  (if (symbolp string-or-symbol) string-or-symbol
Ryan C. Thompson's avatar
Ryan C. Thompson committed
142
    (intern string-or-symbol)))
143 144 145 146 147

(defun el-get-as-list (element-or-list)
  "If ELEMENT-OR-LIST is already a list, return it.  Otherwise
returning a list that contains it (and only it)."
  (if (listp element-or-list) element-or-list
Ryan C. Thompson's avatar
Ryan C. Thompson committed
148
    (list element-or-list)))
149

150 151 152 153 154 155
(defun el-get-list-of-strings-p (obj)
  (or (null obj)
      (and (consp obj)
           (stringp (car obj))
           (el-get-list-of-strings-p (cdr obj)))))

156 157 158
(defun el-get-source-name (source)
  "Return the package name (stringp) given an `el-get-sources'
entry."
159
  (if (and source (listp source))
160 161 162
      (format "%s" (or (plist-get source :name)
                       (error "Source does not have a :name property: %S" source)))
    (symbol-name source)))
163

164 165 166 167

;;
;; Common support bits
;;
168
(defun el-get-rmdir (package url post-remove-fun)
169
  "Just rm -rf the package directory. If it is a symlink, delete it."
170 171 172
  (let* ((edir (expand-file-name el-get-dir))
         (pdir (expand-file-name "." (el-get-package-directory package))))
    ;; check that we're all set
173 174 175
    (when (or (string= edir pdir)    ; package is "", or such like
              ;; error if pdir is not a subdirectory of el-get-dir
              (not (string= edir (substring pdir 0 (length edir)))))
176 177
      (error "el-get-rmdir: directory '%s' of package '%s' is not inside `el-get-dir' ('%s')."
             pdir package el-get-dir))
178 179 180 181 182
    (cond ((file-symlink-p pdir)
           (delete-file pdir))
          ((file-directory-p pdir)
           (delete-directory pdir 'recursive))
          ((file-exists-p pdir)
183
           (delete-file pdir)))
184
    (when post-remove-fun
Ryan C. Thompson's avatar
Ryan C. Thompson committed
185
      (funcall post-remove-fun package))))
186 187 188 189 190 191 192 193


;;
;; Some tools
;;
(defun el-get-duplicates (list)
  "Return duplicates found in list."
  (loop with dups and once
Ryan C. Thompson's avatar
Ryan C. Thompson committed
194 195 196 197
        for elt in list
        if (member elt once) collect elt into dups
        else collect elt into once
        finally return dups))
198 199 200 201 202 203 204 205 206 207 208 209 210 211

(defun el-get-flatten (arg)
  "Return a version of ARG as a one-level list

 (el-get-flatten 'x) => '(x)
 (el-get-flatten '(a (b c (d)) e)) => '(a b c d e)"
  (if (listp arg)
      (apply 'append (mapcar 'el-get-flatten arg))
    (list arg)))

(defun el-get-load-path (package)
  "Return the list of absolute directory names to be added to
`load-path' by the named PACKAGE."
  (let* ((source   (el-get-package-def package))
Ryan C. Thompson's avatar
Ryan C. Thompson committed
212
         (el-path  (if (plist-member source :load-path)
213 214
                       (el-get-flatten (plist-get source :load-path))
                     '(".")))
215 216 217 218 219 220
         (pkg-dir (el-get-package-directory package)))
    (mapcar (lambda (p) (expand-file-name p pkg-dir)) el-path)))

(defun el-get-method (method-name action)
  "Return the function to call for doing action (e.g. install) in
given method."
221 222 223
  (let* ((method  (if (keywordp method-name) method-name
                    (intern (concat ":" (format "%s" method-name)))))
         (actions (plist-get el-get-methods method)))
Ryan C. Thompson's avatar
Ryan C. Thompson committed
224 225
    (assert actions nil
            "Unknown recipe type: %s" method)
226 227 228 229 230 231 232 233 234 235
    (plist-get actions action)))

(defun el-get-check-init ()
  "Check that we can run el-get."
  (unless (file-directory-p el-get-dir)
    (make-directory el-get-dir)))

(defun el-get-package-directory (package)
  "Return the absolute directory name of the named PACKAGE."
  (file-name-as-directory
236
   (expand-file-name (el-get-as-string package)
Ryan C. Thompson's avatar
Ryan C. Thompson committed
237
                     (expand-file-name el-get-dir))))
238 239 240 241 242

(defun el-get-add-path-to-list (package list path)
  "(add-to-list LIST PATH) checking for path existence within
given package directory."
  (let* ((pdir     (el-get-package-directory package))
Ryan C. Thompson's avatar
Ryan C. Thompson committed
243
         (fullpath (expand-file-name (or path ".") pdir)))
244 245
    (unless (file-directory-p fullpath)
      (error "el-get could not find directory `%s' for package %s, at %s"
Ryan C. Thompson's avatar
Ryan C. Thompson committed
246
             path package fullpath))
247 248 249 250 251 252 253 254
    (add-to-list list fullpath)))

(defun el-get-package-exists-p (package)
  "Return true only when the given package name is either a
directory or a symlink in el-get-dir."
  (let ((pdir (el-get-package-directory package)))
    ;; seems overkill as file-directory-p will always be true
    (or (file-directory-p pdir)
Ryan C. Thompson's avatar
Ryan C. Thompson committed
255
        (file-symlink-p   pdir))))
256

257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279

;;
;; el-get-reload API functions
;;
(defun el-get-package-files (package)
  "Return a list of files loaded from PACKAGE's directory."
  (loop with pdir = (file-truename (el-get-package-directory package))
        with regexp = (format "^%s" (regexp-quote (file-name-as-directory (expand-file-name pdir))))
        for (f . nil) in load-history
        when (and (stringp f) (string-match-p regexp (file-truename f)))
        collect (if (string-match-p "\\.elc?$" f)
                    (file-name-sans-extension f)
                  f)))

(defun el-get-package-features (package)
  "Return a list of features provided by files in PACKAGE."
  (loop with pdir = (file-truename (el-get-package-directory package))
        with regexp = (format "^%s" (regexp-quote (file-name-as-directory (expand-file-name pdir))))
        for (f . l) in load-history
        when (and (stringp f) (string-match-p regexp (file-truename f)))
        nconc (loop for i in l
                    when (and (consp i) (eq (car i) 'provide))
                    collect (cdr i))))
280

281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373

;;
;; call-process-list utility
;;
(defun el-get-start-process-list-sentinel (proc change)
  "When proc has exited and was successful, chain next command."
  (when (eq (process-status proc) 'exit)
    (condition-case err
        (let ((status  (process-exit-status proc))
              (cname   (process-get proc :command-name))
              (cbuf    (process-get proc :buffer-name))
              (message (process-get proc :message))
              (errorm  (process-get proc :error))
              (package (process-get proc :el-get-package))
              (final-f (process-get proc :el-get-final-func))
              (next    (process-get proc :el-get-start-process-list))
              (el-get-sources (process-get proc :el-get-sources)))
          (if (not (eq 0 status))
              (progn
                (when (process-buffer proc)
                  (set-window-buffer (selected-window) cbuf))
                (error "el-get: %s %s" cname errorm))
            (message "el-get: %s" message))

          (when cbuf (kill-buffer cbuf))
          (if next
              (el-get-start-process-list package next final-f)
            (when (functionp final-f)
              (funcall final-f package))))
      ((debug error)
       (el-get-installation-failed (process-get proc :el-get-package) err)))))

(defvar el-get-default-process-sync nil
  "Non-nil value asks `el-get-start-process-list' to run current
process synchronously. Can be overridden by :sync property in
commands argument of `el-get-start-process-list'")

(defun el-get-start-process-list (package commands final-func)
  "Run each command one after the other, in order, stopping at
first error.

Commands should be a list of plists with at least the following
properties:

:default-directory

   default-directory from where to start the command

:command-name

   Name of the command to start, gives the name of the Emacs subprocess.

:buffer-name

   Name of the buffer associated with the command.

:process-filter

   Function to use as a process filter.

:shell

   When set to a non-nil value, use start-process-shell-command
   rather than the default start-process.

:program

   The program to start

:args

   The list of arguments for the program to start

:message

   The message to send upon success

:error

   The error to send upon failure

:sync

   When set to non-nil value, run synchronously.

:stdin

   Standard input to use for the process.  A lisp value is
   expected, it will get `prin1-to-string' then either saved to a
   file for a synchronous process or sent with
   `process-send-string' for an asynchronous one.

Any other property will get put into the process object.
374 375 376

Any element of commands that is nil will simply be ignored. This
makes it easier to conditionally splice a command into the list.
377
"
378 379 380 381
  ;; Skip nil elements of commands. This makes it easier for methods
  ;; to conditionally splice commands into the list.
  (while (and commands (null (car commands)))
    (setq commands (cdr commands)))
382 383
  (condition-case err
      (if commands
Ryan C. Thompson's avatar
Ryan C. Thompson committed
384 385 386 387 388 389 390 391
          (let* ((c       (car commands))
                 (next    (cdr commands))
                 (cdir    (plist-get c :default-directory))
                 (cname   (plist-get c :command-name))
                 (cbuf    (plist-get c :buffer-name))
                 (killed  (when (get-buffer cbuf) (kill-buffer cbuf)))
                 (filter  (plist-get c :process-filter))
                 (shell   (plist-get c :shell))
392 393 394
                 (program (if shell
                              (shell-quote-argument (plist-get c :program))
                            (plist-get c :program)))
Ryan C. Thompson's avatar
Ryan C. Thompson committed
395 396 397 398
                 (args    (if shell
                              (mapcar #'shell-quote-argument (plist-get c :args))
                            (plist-get c :args)))
                 (sync    (el-get-plist-get-with-default c :sync
399
                            el-get-default-process-sync))
Ryan C. Thompson's avatar
Ryan C. Thompson committed
400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453
                 (stdin   (plist-get c :stdin))
                 (default-directory (if cdir
                                        (file-name-as-directory
                                         (expand-file-name cdir))
                                      default-directory)))
            (unless program (error "el-get: :program argument cannot be nil"))
            (if sync
                (progn
                  (el-get-verbose-message "Running commands synchronously: %S" commands)
                  (let* ((startf (if shell #'call-process-shell-command #'call-process))
                         (infile (when stdin (make-temp-file "el-get")))
                         (dummy  (when infile
                                   (with-temp-file infile
                                     (insert (el-get-print-to-string stdin)))))
                         (dummy  (message "el-get is waiting for %S to complete" cname))
                         (status (apply startf program infile cbuf t args))
                         (message (plist-get c :message))
                         (errorm  (plist-get c :error)))
                    (when el-get-verbose
                      (message "%S" (with-current-buffer cbuf (buffer-string))))
                    (if (eq 0 status)
                        (message "el-get: %s" message)
                      (set-window-buffer (selected-window) cbuf)
                      (error "el-get: %s %s" cname errorm))
                    (when infile (delete-file infile))
                    (when cbuf (kill-buffer cbuf))
                    (if next
                        ;; Prevent stack overflow on very long command
                        ;; lists. This allows
                        ;; `el-get-start-process-list' (but not other
                        ;; functions) to recurse indefinitely.
                        (let ((max-specpdl-size (+ 100 max-specpdl-size)))
                          (el-get-start-process-list package next final-func))
                      (when (functionp final-func)
                        (funcall final-func package)))))
              ;; async case
              (el-get-verbose-message "Running commands asynchronously: %S" commands)
              (let* ((startf (if shell #'start-process-shell-command #'start-process))
                     (process-connection-type nil) ; pipe, don't pretend we're a pty
                     (proc (apply startf cname cbuf program args)))
                ;; add the properties to the process, then set the sentinel
                (mapc (lambda (x) (process-put proc x (plist-get c x))) c)
                (process-put proc :el-get-sources el-get-sources)
                (process-put proc :el-get-package package)
                (process-put proc :el-get-final-func final-func)
                (process-put proc :el-get-start-process-list next)
                (when stdin
                  (process-send-string proc (el-get-print-to-string stdin))
                  (process-send-eof proc))
                (set-process-sentinel proc 'el-get-start-process-list-sentinel)
                (when filter (set-process-filter proc filter)))))
        ;; no commands, still run the final-func
        (when (functionp final-func)
          (funcall final-func package)))
454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474
    ((debug error)
     (el-get-installation-failed package err))))

;;
;; get an executable given its command name, with friendly error message
;;
(defun el-get-executable-find (name)
  "Return the absolute path of the command to execute, and errors
out if that can not be found.

This function will first look for existing function named
\"el-get-NAME-executable\" and call that. This function, if it
exists, must handle error cases.

Then, it will look for existing variable named \"el-get-NAME\"
and error if that's not nil and not an existing file name.

Baring variable named \"el-get-NAME\", it will call
`executable-find' on NAME and use the output of that, or error
out if it's nil."
  (let ((fname (intern (format "el-get-%s-executable" name)))
Ryan C. Thompson's avatar
Ryan C. Thompson committed
475
        (vname (intern (format "el-get-%s" name))))
476 477 478 479 480 481 482 483
    (cond
     ((fboundp fname)
      (funcall fname))

     ;; vname is bound here, we want to check for the variable named vname
     ;; (bound-and-true-p vname) won't cut it
     ((ignore-errors (symbol-value vname))
      (let ((command (symbol-value vname)))
Ryan C. Thompson's avatar
Ryan C. Thompson committed
484 485 486 487 488 489 490
        (unless (and (file-exists-p command)
                     (file-executable-p command))
          (error
           (concat "The variable `%s' points to \"%s\", "
                   "which is not an executable file name on your system.")
           name command))
        command))
491 492 493

     (t
      (let ((command (executable-find name)))
Ryan C. Thompson's avatar
Ryan C. Thompson committed
494 495 496 497 498
        (unless command
          (error
           "The command named '%s' can not be found with `executable-find'"
           name))
        command)))))
499

500 501 502 503 504 505 506 507 508 509 510 511
(defun el-get-plist-get-with-default (plist prop def)
  "Same as (plist-get PLIST PROP), but falls back to DEF.

Specifically, if (plist-member PLIST PROP) is nil, then returns
DEF instead. Note that having a property set to nil is not the
same as having it unset."
  (if (plist-member plist prop)
      (plist-get plist prop)
    def))
(put 'el-get-plist-get-with-default 'lisp-indent-function
     (get 'prog2 'lisp-indent-function))

512
(provide 'el-get-core)