1 [![Build Status](https://travis-ci.org/rocky/emacs-load-relative.png)](https://travis-ci.org/rocky/emacs-load-relative)
3 # Emacs multi-file develop/run-from-of-source routines
5 The rational behind module is to be able to write small Emacs
6 functions or modules in a larger multi-file Emacs package and
7 facilitate running from the source tree without having to "install"
8 the code or fiddle with evil *load-path*'s . See my [NYC Lisp talk](https://github.com/rocky/emacs-load-relative/wiki/NYC-Lisp-talk) for more background on this.
13 * [\__FILE__](https://github.com/rocky/emacs-load-relative#file)
14 * [load-relative](https://github.com/rocky/emacs-load-relative#load-relative)
15 * [require-relative](https://github.com/rocky/emacs-load-relative#require-relative-require-relative-list)
16 * [provide-me](https://github.com/rocky/emacs-load-relative#provide-me)
18 The latest version is at http://github.com/rocky/emacs-load-relative
22 \__FILE__ returns the file name that that the calling program is
23 running. If you are *eval*'ing a buffer then the file name of that
24 buffer is used. The name was selected to be analogous to the name used
27 For an common example of using this, see [How to Insert Demo Code into an Emacs Lisp Module](https://github.com/rocky/emacs-load-relative/wiki/How-to-Insert-Demo-Code-into-an-Emacs-Lisp-Module).
31 *load-relative* loads an Emacs Lisp file relative to another
32 (presumably currently running) Emacs Lisp file. For example suppose
33 you have Emacs Lisp files `foo.el` and `bar.el` in the same directory.
34 To load Emacs Lisp file `bar.el` from inside Emacs lisp file `foo.el`:
37 (require 'load-relative)
41 That *load-relative* line could above have also been written as:
44 (load-relative "./baz")
50 (load-relative "baz.el") # if you want to exclude any byte-compiled files
53 ## require-relative, require-relative-list
55 Use *require-relative* if you want to *require* the file instead of
59 (require-relative "baz")
65 (require-relative "./baz")
68 The above not only does a *require* on `'baz`, but makes sure you get
69 that from the same file as you would have if you had issued
72 Use *require-relative-list* when you have a list of files you want to
73 *require*. To *require-relative* them in one shot:
76 (require-relative-list '("dbgr-init" "dbgr-fringe"))
81 The macro *provide-me* saves you the trouble of adding a symbol
82 after *provide*, by using the file basename (without directory or file
83 extension) as the name of the thing you want to provide. Using this
84 forces the *provide* names to be the same as the filename, but I
85 consider that a good thing.
87 *provide-me* also takes an optional string which will be prepended to the provide name. This is useful if you have a multi-file package and want the files to bue prefaced with the name of the package.
89 Assume your package *foo* and contains simply file `foo.el`. Then
96 inside that file is the same thing as writing:
102 Now suppose `foo.el` is part of a larger package called *bar*. Then if
109 this is the same as writing:
116 ## find-file-noselect-relative
118 The function *find-file-noselect-relative* provides a way of accessing
119 resources which are located relative to the currently running Emacs lisp file.
120 This is probably most useful when running Emacs as a scripting engine for
121 batch processing or with tests cases.
124 (find-file-noselect-relative "README.md")
127 ## with-relative-file
129 The macro *with-relative-file* runs in a buffer with the contents of the given
133 (with-relative-file "README.md"