README.org

   1 #+OPTIONS: creator:nil author:nil toc:nil inline-images:t H:4 todo:nil
   2 #+TITLE: README for elinstall
   3 #+BLOGLABELS:
   4
   5 * README for elinstall
   6
   7 ** Why use it
   8
   9 There are other package installers and there is "autoload.el", bundled
  10 with emacs.  Why use elinstall?  Because:
  11
  12  * It works with my-site-start (which I highly recommend)
  13
  14  * It supports slash-style paths, like
  15    : (require 'emtest/testhelp/tagnames)
  16
  17  * Unlike autoload.el, it can also set up load-path and
  18    Info-default-directory-list (that's like load-path for info files)
  19
  20  * Unlike some other installers, it works with canonical
  21    loaddefs.el-style autoload files.
  22
  23  * Unlike other installers, what you install doesn't have to be
  24    pre-packaged, and there are no restrictions on what means you can
  25    use to get the elisp files - elinstall doesn't care, it obeys the
  26    motto "do one thing well".
  27
  28    But it also works well for packages.
  29
  30  * Because internally it works in articulated stages, it's easier to
  31    hack and extend than autoload.el
  32
  33 ** How to use it
  34
  35 *** For end users
  36
  37  * To install a single file (Unsupported yet)
  38
  39    :
  40
  41  * To install a directory (Unsupported yet)
  42
  43    :
  44
  45  * To install a directory tree (Unsupported yet)
  46    :
  47
  48  * For general, flexible install (Unsupported yet)
  49    :
  50
  51
  52 *** For package maintainers
  53
  54 Write a call like this:
  55
  56 #+BEGIN_src emacs-lisp
  57 (elinstall
  58    "project-buffer-mode"
  59    (elinstall-directory-true-name)
  60    '(def-file "project-buffer-loaddefs.el"
  61        (all
  62           (dir "./")
  63           (dir "plugins/")
  64           (dir "extensions/"))))
  65 #+END_src
  66
  67 It can actually be executed every time, because elinstall checks for
  68 already-installed packages.
  69
  70 CAUTION: `elinstall-directory-true-name' is sensitive to where it's
  71 called.  That's the point of it
  72
  73 ** How it works internally
  74
  75 It works in stages.  For the autoload functionality, I basically
  76 pulled apart autoload.el and rearranged it into clean stages.
  77
  78  1. Figure out what actions to do.
  79
  80  2. Segregate the actions by target (eg "loaddefs.el")
  81
  82  3. Do the actions for each target
  83
  84     * Create any autoloads (cleaning up old ones)
  85
  86     * Arrange for load-path to contain appropriate directories.
  87
  88     * Symlink loaddefs files into a site-start.d directory
  89
  90  5. Clean up
  91
  92     * Kill any buffers we made
  93     * Record installed
  94
  95 ** Could use help on
  96
  97 Many things:
  98  * Making the other entry points more interactive
  99  * Implementing the other SPEC forms