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 ** What it is
   7
   8 An installer for elisp code. It sets up autoloads, load-path, etc.
   9
  10 ** Why use it
  11
  12 There are other package installers and there is "autoload.el", bundled
  13 with emacs.  Why use elinstall?  Because:
  14
  15  * It works with my-site-start (which I highly recommend)
  16
  17  * It supports slash-style paths, like
  18    : (require 'emtest/testhelp/tagnames)
  19
  20  * Unlike autoload.el, it can also set up load-path and
  21    Info-default-directory-list (that's like load-path for info files)
  22
  23  * Unlike autoload.el, it's not focussed on building emacs, it's
  24    focussed on installing elisp.
  25
  26  * Unlike some other installers, it works with canonical
  27    loaddefs.el-style autoload files.
  28
  29  * Unlike other installers, what you install doesn't have to be
  30    pre-packaged, and there are no restrictions on what means you can
  31    use to get the elisp files - elinstall doesn't care, it obeys the
  32    motto "do one thing well".
  33
  34    But it also works well for packages.
  35
  36  * Since internally it works in articulated stages, it's easier to
  37    hack and extend than autoload.el
  38 ** Where to get it
  39
  40 It lives at http://repo.or.cz/w/elinstall.git]]
  41
  42 ** How to use it
  43
  44 *** For end users
  45
  46  * To install a single file (Unsupported yet)
  47
  48    :
  49
  50  * To install a directory (Unsupported yet)
  51
  52    :
  53
  54  * To install a directory tree (Unsupported yet)
  55    :
  56
  57  * For general, flexible install (Unsupported yet)
  58    :
  59
  60
  61 *** For package maintainers
  62
  63 Write a call like this:
  64
  65 #+BEGIN_src emacs-lisp
  66 (elinstall
  67    "project-buffer-mode"
  68    (elinstall-directory-true-name)
  69    '(all
  70           (dir "./")
  71           (dir "plugins/")
  72           (dir "extensions/")))
  73 #+END_src
  74
  75 You don't have to check whether it's already been installed, because
  76 elinstall remembers which packages it has installed and doesn't
  77 install them again.
  78
  79 CAUTION: `elinstall-directory-true-name' is sensitive to where it's
  80 called.  That's the point of it
  81
  82 ** How it works internally
  83
  84 It works in stages.  For the autoload functionality, I basically
  85 pulled apart autoload.el and rearranged it into clean stages.
  86
  87  1. Figure out what actions to do.
  88
  89  2. Organize the actions
  90
  91     * Segregate the actions by target (eg "loaddefs.el")
  92
  93     * Put certain types of actions later than others.
  94
  95  3. Do the actions for each target
  96
  97     * Create any autoloads (cleaning up old ones)
  98
  99     * Arrange for load-path to contain appropriate directories.
 100
 101     * Symlink loaddefs files into a site-start.d directory
 102
 103  4. Clean up
 104
 105     * Kill any buffers we made
 106     * Record installed
 107
 108 ** Could use help on
 109
 110 Primarily, please use it your own way and thereby exercise the entry
 111 points and paths that I don't normally use.
 112
 113 Then patch it to fix bugs, close holes, or make it more convenient.
 114
 115 Then either push the changes to ssh://repo.or.cz/srv/git/elinstall.git
 116 or send me a patch against the latest version.
 117
 118 If you like, you can also flesh out one or more of the weaker points.
 119 I've marked them all with "$$" in the source.