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. Organize the actions
  81
  82     * Segregate the actions by target (eg "loaddefs.el")
  83
  84     * Put certain types of actions later than others.
  85
  86  3. Do the actions for each target
  87
  88     * Create any autoloads (cleaning up old ones)
  89
  90     * Arrange for load-path to contain appropriate directories.
  91
  92     * Symlink loaddefs files into a site-start.d directory
  93
  94  4. Clean up
  95
  96     * Kill any buffers we made
  97     * Record installed
  98
  99 ** Could use help on
 100
 101 Many things:
 102  * Making the other entry points more interactive
 103  * Implementing the other SPEC forms