Bugfix: Place load-path statements at the beginning of loaddefs files.
[elinstall.git] / README.org
blob000a8cb4c85a7a95045f478c5fb194d8c4b1da1a
1 #+OPTIONS: creator:nil author:nil toc:nil inline-images:t H:4 todo:nil
2 #+TITLE: README for elinstall
3 #+BLOGLABELS:
5 * README for elinstall
6 ** What it is
8 An installer for elisp code. It sets up autoloads, load-path, etc.
10 ** Why use it
12 There are other package installers and there is "autoload.el", bundled
13 with emacs.  Why use elinstall?  Because:
15  * It works with my-site-start (which I highly recommend)
17  * It supports slash-style paths, like 
18    : (require 'emtest/testhelp/tagnames)
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)
23  * Unlike autoload.el, it's not focussed on building emacs, it's
24    focussed on installing elisp.
26  * Unlike some other installers, it works with canonical
27    loaddefs.el-style autoload files.
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".
34    But it also works well for packages.
36  * Since internally it works in articulated stages, it's easier to
37    hack and extend than autoload.el
38 ** Where to get it
40 It lives at http://repo.or.cz/w/elinstall.git]]
42 ** How to use it
44 *** For end users
46  * To install a single file (Unsupported yet)
48    : 
50  * To install a directory (Unsupported yet)
52    : 
54  * To install a directory tree (Unsupported yet)
55    : 
57  * For general, flexible install (Unsupported yet) 
58    :
59    
61 *** For package maintainers
63 Write a call like this:
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
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.
79 CAUTION: `elinstall-directory-true-name' is sensitive to where it's
80 called.  That's the point of it
82 ** How it works internally
84 It works in stages.  For the autoload functionality, I basically
85 pulled apart autoload.el and rearranged it into clean stages.
87  1. Figure out what actions to do.  
89  2. Organize the actions
91     * Segregate the actions by target (eg "loaddefs.el")
93     * Put certain types of actions later than others.
95  3. Do the actions for each target
97     * Create any autoloads (cleaning up old ones)
99     * Arrange for load-path to contain appropriate directories.
101     * Symlink loaddefs files into a site-start.d directory
103  4. Clean up
105     * Kill any buffers we made
106     * Record installed
108 ** Could use help on
110 Primarily, please use it your own way and thereby exercise the entry
111 points and paths that I don't normally use.
113 Then patch it to fix bugs, close holes, or make it more convenient.
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.
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.