README.asciidoc 15 KB
Newer Older
1 2
= el-get

3 4 5 6 7
Short Story: el-get allows you to install and manage +elisp+ code for
Emacs. It supports lots of differents types of sources and is able to
'install' them, 'update' them and 'remove' them, but more importantly it
will 'init' them for you.

8 9 10 11 12
That means it will +require+ the 'features' you need, +load+ the
necessary files, set the 'Info' paths so that +C-h i+ shows the new
documentation you now depend on, and finally call your own
+:post-init+ function for you to setup the extension. Or call it a
package.
13

14 15 16 17 18 19
== Status and Version Numbers

Current +el-get+ status is stable, ready for daily use and packed with extra
features that make life easier.  There are some more things we could do, as
always, but they will be about smoothing things further.

20
=== Latest released version
21

22
+el-get+ version 3.1 is available, with a boatload of features, including
23 24 25 26 27 28
autoloads support, byte-compiling in an external "clean room" Emacs
instance, custom support, lazy initialisation support (defering all init
functions to +eval-after-load+), and multi repositories +ELPA+ support.

=== Version numbering

29
Version String are now inspired by how Emacs itself numbers its versions.
30 31
First is the major version number, then a dot, then the minor version
number.  The minor version number is 0 when still developping the next major
32
version.  So 3.0 is a developer release while 3.1 will be the next stable
33 34
release.

35
Please note that this versioning policy has been picked while backing
36 37
1.2~dev, so 1.0 was a "stable" release in fact.  Ah, history.

38 39 40 41 42
In addition to the version, you can also get the exact git revision by
running M-x +el-get-self-checksum+. You should provide this checksum
when seeking support or reporting a bug, so that the developers will
know exactly which version you are using.

43 44
== How to Install it?

45
Here's the 'lazy installer':
46 47 48 49

--------------------------------------
;; So the idea is that you copy/paste this code into your *scratch* buffer,
;; hit C-j, and you have a working el-get.
50
(url-retrieve
51
 "https://raw.github.com/dimitri/el-get/master/el-get-install.el"
52 53 54
 (lambda (s)
   (end-of-buffer)
   (eval-print-last-sexp)))
55 56
--------------------------------------

57 58 59 60 61
You have to type +C-j+ with the cursor at the end of the last line, but
still on the line. 'C-j runs the command eval-print-last-sexp', so it will
evaluate the code you're looking at, and that will +git clone el-get+ at the
'right place'.

62
Note that you can add this elisp code into your emacs init file directly, as
63 64 65 66 67 68 69 70 71
the installer code will detect if +el-get+ is already installed.  Notice
that doing so directly will require internet access to start emacs.  You can
avoid this with the following snippet instead:

--------------------------------------
(add-to-list 'load-path "~/.emacs.d/el-get/el-get")

(unless (require 'el-get nil t)
  (url-retrieve
72
   "https://raw.github.com/dimitri/el-get/master/el-get-install.el"
73 74 75 76
   (lambda (s)
     (end-of-buffer)
     (eval-print-last-sexp))))
--------------------------------------
77 78 79

See next section for details about how to setup you emacs so that it's able
to benefit from +el-get+ automatically.
80

81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
== How to install the developer version (master branch)?

The 'lazy installer' uses the default +el-get-install.el+ file which targets
the +2.stable+ branch.  To install el-get directly on the +master+ branch,
summon the +el-get-master-branch+ variable into existence:

--------------------------------------
;; So the idea is that you copy/paste this code into your *scratch* buffer,
;; hit C-j, and you have a working developper edition of el-get.
(url-retrieve
 "https://raw.github.com/dimitri/el-get/master/el-get-install.el"
 (lambda (s)
   (let (el-get-master-branch)
     (end-of-buffer)
     (eval-print-last-sexp))))
--------------------------------------

98 99 100 101 102 103 104 105 106 107 108
== Basic usage

Now that +el-get+ is installed, simply use +M-x el-get-install+ and pick
whatever package you need.  Arrange to have +el-get+ part of your setup, so
that at next emacs startup the installed packages are initialized.  Here's
how to:

--------------------------------------
(add-to-list 'load-path "~/.emacs.d/el-get/el-get")

(unless (require 'el-get nil t)
109 110 111 112 113
  (with-current-buffer
      (url-retrieve-synchronously
       "https://raw.github.com/dimitri/el-get/master/el-get-install.el")
    (end-of-buffer)
    (eval-print-last-sexp)))
114 115 116 117 118 119 120

(el-get 'sync)
--------------------------------------

That's the basic setup.

== Advanced setup with local recipes
121 122 123 124 125 126 127 128

Of course, my emacs setup is managed in a private git repository. Some
people on +#emacs+ are using +git submodules+ (or was it straight import)
for managing external repositories in there, but all I can say is that I
frown on this idea. I want an easy canonical list of packages I depend on to
run emacs, and I want this documentation to be usable as-is. Enters el-get!

--------------------------------------
129 130 131
(add-to-list 'load-path "~/.emacs.d/el-get/el-get")
(require 'el-get)

132
;; local sources
133
(setq el-get-sources
134
      '((:name magit
135 136
	       :after (lambda () (global-set-key (kbd "C-x C-z") 'magit-status)))

137
	(:name asciidoc
138 139 140 141 142 143 144 145 146
	       :type elpa
	       :after (lambda ()
			(autoload 'doc-mode "doc-mode" nil t)
			(add-to-list 'auto-mode-alist '("\\.adoc$" . doc-mode))
			(add-hook 'doc-mode-hook '(lambda ()
						    (turn-on-auto-fill)
						    (require 'asciidoc)))))

	(:name lisppaste        :type elpa)
147 148
        (:name emacs-goodies-el :type apt-get)))

149
(setq my-packages
150 151
      (append
       '(cssh el-get switch-window vkill google-maps nxhtml xcscope yasnippet)
152
       (mapcar 'el-get-source-name el-get-sources)))
153 154

(el-get 'sync my-packages)
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
--------------------------------------

So now you have a pretty good documentation of the packages you want
installed, where to get them, and how to install them. For the advanced
methods (such as elpa or apt-get), you basically just need the package
name. When relying on a bare git repository, you need to give some more
information, such as the URL to clone and the build steps if any. Then also
what features to require and maybe where to find the texinfo documentation
of the package, for automatic inclusion into your local Info menu.

The good news is that not only you now have a solid readable description of
all that in a central place, but this very description is all (el-get) needs
to do its magic. This command will check that each and every package is
installed on your system (in el-get-dir) and if that's not the case, it will
actually install it. Then, it will init the packages: that means caring
about the load-path, the Info-directory-list (and dir texinfo menu building)
the loading of the emacs-lisp files, and finally it will require the
features.

== How to use it?

176
You see that +el-get-sources+ example up there? It finishes with a single
177 178 179
+(el-get)+ call. That's it. It will 'install' new +sources+ on the list and
only 'init' already installed ones.

180 181
The status of each package is tracked into +~/.emacs.d/el-get/.status.el+
(by default) and can get the values +required+, +installed+ or +removed+.
182

183 184 185 186 187 188
=== Sync or async?

Most often you want +el-get-install+ and +el-get-build+ to stay out of the
way and be 'asynchronous', so that you can continue using Emacs while your
new package is getting ready. But imagine you're starting up Emacs after a
+git pull+ on the other computer (after a commute, say), and there's some
189
newer packages for this instance to consider installing.
190 191 192

Now you want a synchronous install, right?

193 194 195
So, by default +(el-get)+ is asynchronous, but you can ask for it to be
sync, or to still be asynchronous but to wait until it finished before to
give control back:
196 197

  (el-get 'sync)
198
  (el-get 'wait)
199 200 201

You even get a progress report!

202 203
=== Sources

204
See the documentation of the +el-get-sources+ variable for details.  Please
205 206
note that +el-get-sources+ is another source location for recipes, adding to
your +el-get-recipe-path+.
207

208 209
Note that you can also give a mix of +packages+ symbols, +inline recipes+
and +source lists+ to +el-get+ as arguments, and completely bypass the
210
+el-get-sources+ variable.
211

212
  (el-get 'sync 'package 'name 'list-of-packages-names-or-symbol)
213

214 215 216 217
It is still recommended to +(setq el-get-sources '(list of packages))+ then
use +(el-get 'sync)+, so that commands such as +el-get-update+ know which
packages to update.

218 219 220 221
=== Recipes

Some sources are contributed to +el-get+ directly, so that you only have to
put in the +el-get-sources+ the name of the package you want to
222
install.
223 224 225 226 227 228 229 230 231 232 233 234 235 236

Should you need some local specific setup, you can do that by providing a
partial sources missing the +:type+ property: your local properties will get
merged into the recipes one.

Also, the variable +el-get-recipe-path+ allows you to maintain local recipes
in case you either dislike the default one or are crafting some new one not
commited to the main repository yet. But please do consider sending them
over!

We do not intend to provide recipes for advanced types such as +apt-get+ and
+elpa+ because there's so little to win here, and maintaining a package list
would take too much time.

237 238 239
=== Package setup

The package setup can either go into the +:after+ function, or in a file
240 241
named +init-package.el+ in +el-get-user-package-directory+.  Any such named
file will get automatically loaded by +el-get+ at +init+ time, if it exists.
242

243 244
=== Build Commands

245 246 247 248
Avoid using +make install+, which will usually move files into a
"system location."  In our case, you probably just want your package
+foo+ to be all installed into +~/.emacs.d/el-get/foo+, right? So, no
+make install+.
249

250 251 252 253 254 255 256
=== Byte Compiling

+el-get+ will 'byte compile' the elisp for the package when its source
definition includes a +:compile+ property set to the list of files to byte
compile (or to a single file), or all the +.el+ files found in the package
when there's no +:build+ command.

257 258 259 260 261 262
=== Hooks

+el-get+ offers a variety of specific hooks (read the source), and two
general purposes hooks facilities: +el-get-post-install-hooks+ and
+el-get-post-update-hooks+, called with the package name as argument.

263 264 265 266
=== Some more commands?

Yes, ok.

267 268 269 270 271 272 273 274 275 276
M-x el-get-list-packages::

    Opens a buffer listing all known packages (those for which you have a
    recipe).  The listing includes the package name, its status (one of
    "available", "installed", "removed" or "required") and the package
    description.  The description is a free form text and has not been
    provided for all recipes.  Please also note that
    +el-get-emacswiki-refresh+ will create recipes omitting the description
    as of now.

277 278 279 280 281 282 283
M-x el-get-describe::

    Prompt for a package name, with completion, then open an +*Help*+ window
    with details about the selected package.  Those include current status,
    website, description, installation method, full recipe, and buttons to
    easily install, update or remove the package.

Dimitri Fontaine's avatar
Dimitri Fontaine committed
284 285 286 287 288 289 290 291 292 293
M-x el-get-install::
+
Will prompt for a package name, with completion, then install it.  It will
only propose packages that are not already +installed+.  Any package that
you have a recipe for is a candidate.
+
Please note that when installing a package that is not in your
+el-get-sources+ or your +el-get+ call means that it will not be initialized
for you automatically at emacs startup.  You get a +WARNING+ message when
that's the case.
294

295 296
M-x el-get-cd::

297 298
    Will prompt for an +installed+ package name, with completion, then open
    its directory with dired.
299 300 301

M-x el-get-update::

302 303
    Will prompt for an installed package name, with completion, then update
    it. This will run the +build+ commands and +init+ the package again.
304

305 306 307 308
M-x el-get-self-update::

    Update only one package, +el-get+ itself.

309 310 311 312 313 314 315
M-x el-get-update-all::

    Will update all packages used in +el-get-sources+. Beware that using
    this function can lead to hours of settings review: more often than not
    updating a package requires some adjustments to your setup.  Updating
    all of them at once will require reviewing almost all your setup.

316 317 318 319
M-x el-get-reload::

    Reload the given package files.  Happens automatically at update time too.

320 321
M-x el-get-remove::

322 323 324 325 326
    Will prompt for an +installed+ package name, with completion, then
    remove it. Depending on the +type+ of the package, this often means
    simply deleting the directory where the source package lies. Sometime we
    have to use external tools instead (+apt-get+, e.g.). No effort is made
    to unload the features.
327

328 329 330 331 332 333
M-x el-get-reinstall::

    This is just a shortcut for +el-get-remove+ followed by +el-get-install+
    of the same package. It is primarily useful when a package has changed
    types, so the normal +el-get-update+ process will not work correctly.

334 335 336 337 338
M-x el-get-find-recipe-file::

    Will prompt for the name of a package, with completion, then +find-file+
    its +recipe+ file.

339 340 341 342 343 344
M-x el-get-make-recipes::

    Will prompt for an existing directory where to output all your 'new'
    recipe files: one file for each entry in +el-get-sources+ that is not
    just a +symbol+ and that is not found anywhere in +el-get-recipe-path+.

345 346 347 348 349 350 351
M-x el-get-checksum::

    Will prompt for the name of an installed package, with complement, then
    compute its checksum if the package type supports that feature.  The
    checksum is added to the kill-ring so that you're ready to yank it into
    your +el-get-sources+ :checksum property if you want to.

352 353 354 355 356 357 358 359
M-x el-get-emacswiki-refresh::

    Will launch a subprocess that connects to EmacsWiki and fetch from there
    the list of elisp scripts hosted.  Then produce a recipe file per
    script, and store that in the given directory, which default to
    +~/.emacs.d/el-get/el-get/recipes/emacswiki/+ if you didn't change
    +el-get-dir+.

360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375
=== Useful functions

el-get-package-types-alist (statuses &rest types)::

    Return an alist of package names that are of given types. Only consider
    packages whose status is `member' of STATUSES, which defaults to
    installed, required and removed.

  ELISP> (el-get-package-types-alist "installed" 'cvs 'emacswiki)
  ((emacs-w3m . cvs)
   (rect-mark . emacswiki)
   (icomplete+ . emacswiki)
   (php-mode-improved . emacswiki)
   (rainbow-delimiters . emacswiki)
   (goto-last-change . emacswiki)
   (emacs-goodies-el . cvs))
376

377 378 379 380 381 382 383 384 385
el-get-extra-packages (&rest packages)::

      Return installed or required packages that are not in given package
      list.

  ELISP> (el-get-extra-packages dim-packages)
  ((verbiste "installed")
   (package "installed"))

386 387 388 389
== Extending it

Please see the documentation for the +el-get-methods+ and provide a patch!

390
Adding +bzr+ support for example was only about writing 2 functions, mostly
391
using copy paste. Here's the patch: https://github.com/dimitri/el-get/commit/63e9018102bdeb7b6d9136db231adcd983087217#L0R437
392

393 394
== Upgrade Notes

Dimitri Fontaine's avatar
Dimitri Fontaine committed
395
=== Upgrading to 3.1
396

Dimitri Fontaine's avatar
Dimitri Fontaine committed
397 398 399
A change has been included so that +el-get-sources+ is now only another
source for recipes, and +(el-get '...)+ will now only install and initialize
known "required" and "installed" packages.
400

401 402 403 404 405 406
The documentation has been updated to detail the new setup.

If you have packages that have been installed in the past but you no longer
want in your setup, here's how to get them out of the way:

  M-: (el-get-save-package-status "package-name-here" "removed")
407

Dimitri Fontaine's avatar
Dimitri Fontaine committed
408
Please review documentation section 'Advanced setup with local recipes'.