mirror of
https://github.com/dimitri/el-get.git
synced 2024-09-29 13:08:51 +08:00
15bd4cfa61
* Add el-get-check-recipe command * Add a script test/check-recipe.el * Mention recipe checker in the document * Add warnings to el-get-check-recipe * Use @command instead of @code * make el-get.info * Use more expressive name than el-get-check-recipe-1
1055 lines
38 KiB
Plaintext
1055 lines
38 KiB
Plaintext
This is el-get.info, produced by makeinfo version 4.13 from el-get.texi.
|
||
|
||
INFO-DIR-SECTION Emacs
|
||
START-INFO-DIR-ENTRY
|
||
* El-Get: (el-get). Using el-get to manage your Emacs Extensions.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
Copyright (C) 2010, 2011, 2012 Dimitri Fontaine.
|
||
|
||
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
|
||
Version 2, December 2004
|
||
|
||
Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
|
||
|
||
Everyone is permitted to copy and distribute verbatim or modified
|
||
copies of this license document, and changing it is allowed as long
|
||
as the name is changed.
|
||
|
||
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE TERMS AND
|
||
CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
||
|
||
0. You just DO WHAT THE FUCK YOU WANT TO.
|
||
|
||
|
||
File: el-get.info, Node: Top, Next: Introduction, Up: (dir)
|
||
|
||
El-Get User Manual
|
||
******************
|
||
|
||
El-Get is an Emacs Extension manager that allows you to install, update
|
||
and remove external Emacs Lisp extensions. More importantly, El-Get
|
||
will care about initializing installed extensions for you at Emacs
|
||
Startup.
|
||
|
||
* Menu:
|
||
|
||
* Introduction::
|
||
* Acknowledgments::
|
||
* Glossary::
|
||
* Installing::
|
||
* Usage::
|
||
* Setup::
|
||
* User Init::
|
||
* Recipes::
|
||
* Authoring Recipes::
|
||
|
||
|
||
File: el-get.info, Node: Introduction, Next: Acknowledgments, Prev: Top, Up: Top
|
||
|
||
1 Introduction
|
||
**************
|
||
|
||
El-Get allows you to install and manage Emacs Lisp code for Emacs. It
|
||
supports lots of differents types of sources and is able to install
|
||
them, update them and remove them, and more importantly it will init
|
||
them for you.
|
||
|
||
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.
|
||
|
||
El-Get Version String (`M-x el-get-version') are now inspired by how
|
||
Emacs itself numbers its versions. 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 version. So 3.0 is a developer
|
||
release while 3.1 is a stable release.
|
||
|
||
Please note that this versioning policy has been picked while backing
|
||
1.2~dev, so 1.0 was a "stable" release in fact. Ah, history.
|
||
|
||
|
||
File: el-get.info, Node: Acknowledgments, Next: Glossary, Prev: Introduction, Up: Top
|
||
|
||
2 Acknowledgments
|
||
*****************
|
||
|
||
Dimitri Fontaine started the whole project and still manages the
|
||
releases, and sometimes even contribute code and documentation.
|
||
|
||
Julien Danjou has been a contributor since very early days, about the
|
||
first beta tester of the idea, before we really knew how much to
|
||
achieve.
|
||
|
||
Ryan C. Thompson joined and commented some issues, began contributing
|
||
and quickly became top-level and most active contributor to the
|
||
project, getting a commit bit and some management duties. He manages
|
||
tests and issues on github as much as he can spares time to El-Get.
|
||
|
||
Dave Abrahams contributed lots of code and efforts to make things
|
||
right™. He's still using El-Get, but decided to retire from the project.
|
||
|
||
Lots of people (more than we can list here) did contribute to El-Get
|
||
either recipes, bug fixes or ideas to implement, often with code. That
|
||
builds up an awesome community, thanks guys!
|
||
|
||
dim ~/dev/emacs/el-get git --no-pager shortlog -n -s | wc -l
|
||
137
|
||
dim ~/dev/emacs/el-get git --no-pager shortlog -n -s | head -10
|
||
734 Dimitri Fontaine
|
||
336 Ryan C. Thompson
|
||
114 Julien Danjou
|
||
110 Dave Abrahams
|
||
73 Ryan Thompson
|
||
72 Sébastien Gross
|
||
42 Takafumi Arakaki
|
||
27 Alex Ott
|
||
25 Yakkala Yagnesh Raghava
|
||
21 Rüdiger Sonderfeld
|
||
|
||
|
||
File: el-get.info, Node: Glossary, Next: Installing, Prev: Acknowledgments, Up: Top
|
||
|
||
3 Glossary
|
||
**********
|
||
|
||
Autoload
|
||
Delay loading a package definition until its first use.
|
||
|
||
Build
|
||
Action that happens at *Note Glossary - Install::, and *Note
|
||
Glossary - Update::. Packages might skip any `build' step
|
||
entirely. When given, the build step allows to run system level
|
||
tools (think `make'), often to produce to derivative files.
|
||
|
||
Byte-Compile
|
||
Action to compile Emacs Lisp files so that loading them is faster.
|
||
El-Get is able to automatically manage that step at install and
|
||
update time so that init time is faster, see *Note Glossary -
|
||
Init::.
|
||
|
||
Dependency
|
||
Any El-Get package can depend on some others. At install time,
|
||
El-Get will make sure all dependant packages are installed first.
|
||
At init time, same thing will happen. Dependency management is
|
||
solved with a topological sort so that if you install a package
|
||
`a' that depends on a package `b' that depends on a package `c',
|
||
El-Get will install `c' then `b' then `a'.
|
||
|
||
Init
|
||
When you start Emacs you want your packages to get setup and ready
|
||
to serve whatever usage you have of this advanced Operating
|
||
System. El-Get calls this setup step the `init' and will care
|
||
about initializing your packages automatically given a *Note
|
||
Glossary - Recipe::.
|
||
|
||
Install
|
||
El-Get install a package by fetching its sources as described in
|
||
the package recipe, then running the build steps if the recipe
|
||
contains such.
|
||
|
||
Method
|
||
An El-Get method is a backend code providing facilities to fetch,
|
||
install, update and remove external code. El-Get currently
|
||
implements methods that targets `apt-get', `brew', `builtin',
|
||
`bzr', `cvs', `darcs', `elpa', `emacsmirror', `emacswiki', `fink',
|
||
`fossil', `git' and `git-svn', `github' `github-tar' and
|
||
`github-zip', `hg', `http' `http-tar' and `http-zip', `pacman' and
|
||
`svn'.
|
||
|
||
Notification
|
||
El-Get notifies its user when a package is done installing,
|
||
updating or removing. It knows how to use several system level
|
||
notification facilities, such as `DBUS' or `growl'.
|
||
|
||
Package
|
||
A package is what El-Get manages for you. It's a set of Emacs Lisp
|
||
files (possible a set of a single file, possibly with some Info
|
||
documentation and build scripts, etc) that El-Get knows how to
|
||
fetch and install, update and remove, and init at Emacs Startup.
|
||
|
||
Recipe
|
||
An El-Get recipe describes a package in terms that allow El-Get to
|
||
provide its features against that package. It's easy enough to
|
||
write recipes, and fun to share them!
|
||
|
||
Remove
|
||
El-Get removes a package by simple removing the directory where the
|
||
package is installed. If you want the features of the package to
|
||
get unloaded, most often the easier way to do that is to restart
|
||
Emacs.
|
||
|
||
Status
|
||
One of `available', `installed', `required' or `removed'. When
|
||
El-Get is asked to install a package, the status is set to
|
||
`required' before to fetch and build it, so that in case of error
|
||
the system knows to try installing again.
|
||
|
||
Update
|
||
El-Get updates a package in different ways, depending on the
|
||
package type and the associated method. In some cases it's not
|
||
possible to update a package, like when it switched from `svn' to
|
||
`git' for example.
|
||
|
||
|
||
|
||
File: el-get.info, Node: Installing, Next: Usage, Prev: Glossary, Up: Top
|
||
|
||
4 Installing
|
||
************
|
||
|
||
El-Get comes with a `*scratch*'-installer. Ideally you would install
|
||
El-Get with El-Get itself, but I couldn't figure out how to do that, so
|
||
instead you have to copy and paste the following code into your
|
||
`*scratch*' buffer and evaluate it:
|
||
|
||
;; So the idea is that you copy/paste this code into your *scratch* buffer,
|
||
;; hit C-j, and you have a working el-get.
|
||
(url-retrieve
|
||
"https://raw.github.com/dimitri/el-get/master/el-get-install.el"
|
||
(lambda (s)
|
||
(goto-char (point-max))
|
||
(eval-print-last-sexp)))
|
||
|
||
To evaluate that code, you place the point at the end of the text
|
||
block (just after the last closing paren) and you type `C-j'.
|
||
|
||
* Menu:
|
||
|
||
* Install the developper version::
|
||
* Skip Emacswiki recipes when installing::
|
||
|
||
|
||
File: el-get.info, Node: Install the developper version, Next: Skip Emacswiki recipes when installing, Up: Installing
|
||
|
||
4.1 Developper version
|
||
======================
|
||
|
||
The lazy installer uses the default `el-get-install.el' file which
|
||
targets the `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)
|
||
(goto-char (point-max))
|
||
(eval-print-last-sexp))))
|
||
|
||
|
||
File: el-get.info, Node: Skip Emacswiki recipes when installing, Prev: Install the developper version, Up: Installing
|
||
|
||
4.2 Skip Emacswiki recipes when installing
|
||
==========================================
|
||
|
||
The installer will fetch from emacswiki all the recipe available there
|
||
and install a local copy of those in your system automatically. Should
|
||
you want to disable that feature, the following snippet is showing how
|
||
to:
|
||
|
||
;; So the idea is that you copy/paste this code into your *scratch* buffer,
|
||
;; hit C-j, and you have a working el-get (without emacswiki automatic
|
||
;; recipes).
|
||
(url-retrieve
|
||
"https://raw.github.com/dimitri/el-get/master/el-get-install.el"
|
||
(lambda (s)
|
||
(let (el-get-install-skip-emacswiki-recipes)
|
||
(goto-char (point-max))
|
||
(eval-print-last-sexp))))
|
||
|
||
|
||
File: el-get.info, Node: Usage, Next: Setup, Prev: Installing, Up: Top
|
||
|
||
5 Usage
|
||
*******
|
||
|
||
Now that El-Get is installed, simply use `M-x el-get-install' and pick
|
||
whatever package you need.
|
||
|
||
Here's a list of commands provided by El-Get:
|
||
|
||
`el-get-list-packages'
|
||
List all available packages with their names, *Note Glossary -
|
||
Status::, and description. Name and description are taken from the
|
||
recipe file of the package.
|
||
|
||
You can find which recipe file is used for a given package using
|
||
`el-get-find-recipe-file' or `el-get-describe'.
|
||
|
||
`el-get-describe'
|
||
Offers a full text description of a package with buttons to
|
||
install, remove and update, and with the recipe content.
|
||
|
||
`el-get-find-recipe-file'
|
||
Find the recipe file for given recipe, prompted.
|
||
|
||
`el-get-install'
|
||
Install given package, as prompted.
|
||
|
||
`el-get-init'
|
||
Initialize given package, as prompted. If some user code is setup
|
||
to be run at initialisation, it will get run by this command. See
|
||
*Note User Init::.
|
||
|
||
`el-get-update'
|
||
Update a given package, as prompted. In some cases a straight
|
||
update is not possible (recipe switched from CVS to git is a common
|
||
reason). El-Get will try and detect such cases and do
|
||
`el-get-remove' then `el-get-install' if necessary.
|
||
|
||
Please realise that updating packages might break your current
|
||
package setup and that you will have to revisit your setup
|
||
accordingly.
|
||
|
||
`el-get-remove'
|
||
Remove given package, as prompted.
|
||
|
||
`el-get-self-update'
|
||
Update El-Get itself, and force that update to be synchronous. That
|
||
allows to make sure you're not updating El-Get code while trying to
|
||
update or install some other package at the same time.
|
||
|
||
`el-get-update-all'
|
||
Will update all packages that have the `installed' status in your
|
||
status file. Before the update you will be prompted for
|
||
confirmation that you wish to proceed.
|
||
|
||
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.
|
||
|
||
`el-get-reload'
|
||
Reload the given package files. Happens automatically at update
|
||
time too.
|
||
|
||
|
||
|
||
File: el-get.info, Node: Setup, Next: User Init, Prev: Usage, Up: Top
|
||
|
||
6 Setup
|
||
*******
|
||
|
||
El-Get setup can be very simple or arbitrarily complex. This chapter
|
||
explains how to do the very basic setup, which allow for using `M-x
|
||
el-get-install' and friends, then how to get a more involved setup.
|
||
|
||
* Menu:
|
||
|
||
* Basic Setup::
|
||
* The el-get function::
|
||
* Distributed Setup::
|
||
* Setup Customization::
|
||
|
||
|
||
File: el-get.info, Node: Basic Setup, Next: The el-get function, Up: Setup
|
||
|
||
6.1 Basic Setup
|
||
===============
|
||
|
||
You can then arrange to have El-Get part of your setup, so that at next
|
||
emacs startup the installed packages are initialized.
|
||
|
||
(add-to-list 'load-path "~/.emacs.d/el-get/el-get")
|
||
|
||
(unless (require 'el-get nil t)
|
||
(with-current-buffer
|
||
(url-retrieve-synchronously
|
||
"https://raw.github.com/dimitri/el-get/master/el-get-install.el")
|
||
(goto-char (point-max))
|
||
(eval-print-last-sexp)))
|
||
|
||
(el-get 'sync)
|
||
|
||
The `el-get' 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 or eval the package `autoloads'.
|
||
|
||
This usage is pretty simple to setup and use, but fails to cater with
|
||
more complex setups involving multiple deployments (home and work
|
||
laptop would be a classic example). El-Get fully supports that
|
||
distributed setup, though, and this chapter explain how.
|
||
|
||
|
||
File: el-get.info, Node: The el-get function, Next: Distributed Setup, Prev: Basic Setup, Up: Setup
|
||
|
||
6.2 The el-get function
|
||
=======================
|
||
|
||
Ensure that packages have been downloaded once and init them as needed.
|
||
|
||
This will not update the sources by using `apt-get install' or `git
|
||
pull', but it will ensure that:
|
||
|
||
* the packages have been installed
|
||
|
||
* load-path is set so their elisp files can be found
|
||
|
||
* Info-directory-list is set so their info files can be found
|
||
|
||
* Autoloads have been prepared and evaluated for each package
|
||
|
||
* Any post-installation setup (e.g. `(require 'feature)') happens
|
||
|
||
|
||
When SYNC is `nil' (the default), all installations run
|
||
concurrently, in the background.
|
||
|
||
When SYNC is `sync', each package will be installed synchronously,
|
||
and any error will stop it all.
|
||
|
||
Please note that the `el-get-init' part of `el-get' is always done
|
||
synchronously. There's `byte-compile' support though, and the packages
|
||
you use are welcome to use `autoload' too. You can also force your
|
||
setup to be loaded lazily with the `el-get-is-lazy' variable.
|
||
|
||
`PACKAGES' is expected to be a list of packages you want to install
|
||
or init. When `PACKAGES' is omited (the default), the list of already
|
||
installed packages is considered.
|
||
|
||
|
||
File: el-get.info, Node: Distributed Setup, Next: Setup Customization, Prev: The el-get function, Up: Setup
|
||
|
||
6.3 Distributed Setup
|
||
=====================
|
||
|
||
When you are sharing your emacs setup between several machines (work
|
||
and home destops, laptop, etc); it's usual to manage your `.emacs.d'
|
||
setup in a distributed repository (such as `git'). El-Get then provides
|
||
an easy canonical list of packages you depend on to run emacs, and this
|
||
documentation is usable as-is.
|
||
|
||
(add-to-list 'load-path "~/.emacs.d/el-get/el-get")
|
||
(require 'el-get)
|
||
|
||
;; local sources
|
||
(setq el-get-sources
|
||
'((:name magit
|
||
:after (global-set-key (kbd "C-x C-z") 'magit-status))
|
||
|
||
(:name asciidoc
|
||
:type elpa
|
||
:after (progn
|
||
(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)
|
||
|
||
(:name emacs-goodies-el :type apt-get)))
|
||
|
||
(setq my-packages
|
||
(append
|
||
'(cssh el-get switch-window vkill google-maps nxhtml xcscope yasnippet)
|
||
(mapcar 'el-get-source-name el-get-sources)))
|
||
|
||
(el-get 'sync my-packages)
|
||
|
||
Please note that when you unreference a package from `my-packages',
|
||
it remains locally installed.
|
||
|
||
Going one step further with the idea of a canonical list, el-get
|
||
provides the command `el-get-cleanup', which will remove all packages
|
||
absent from `my-packages'. This allows, in effect, to put under version
|
||
control only the user init file, instead of the whole `.emacs.d'
|
||
directory, and still enjoy a truly portable emacs configuration.
|
||
|
||
In the code example above, replace the last line with the following:
|
||
|
||
(el-get-cleanup my-packages)
|
||
(el-get 'sync my-packages)
|
||
|
||
|
||
File: el-get.info, Node: Setup Customization, Prev: Distributed Setup, Up: Setup
|
||
|
||
6.4 Setup Customization
|
||
=======================
|
||
|
||
Even though the defaults that are provided by El-Get provide all that
|
||
you need to get it working, there may be a reason to manually define
|
||
certain settings, particularly for portability.
|
||
|
||
`el-get-dir'
|
||
Path where packages are installed. Defaults to
|
||
`~/.emacs.d/el-get/'.
|
||
|
||
`el-get-install-dir'
|
||
Path for the `el-get' package. Defaults to
|
||
`~/.emacs.d/el-get/el-get'.
|
||
|
||
`el-get-install-branch'
|
||
If this is set, El-Get will be installed using the target
|
||
`branch'. This takes precedence over setting
|
||
`el-get-master-branch' in the installation settings, see *Note
|
||
Installing::.
|
||
|
||
`el-get-git-install-url'
|
||
Use this to specify your own fork of El-Get for installation.
|
||
|
||
`el-get-recipe-path-elpa'
|
||
This directory stores a local list of ELPA recipes.
|
||
`~/.emacs.d/el-get/el-get/recipes/elpa'
|
||
|
||
`el-get-recipe-path-emacswiki'
|
||
As above for ELPA, this directory stores a local list of emacswiki
|
||
recipes. Defaults to `~/.emacs.d/el-get/el-get/recipes/emacswiki/'.
|
||
|
||
|
||
|
||
File: el-get.info, Node: User Init, Next: Recipes, Prev: Setup, Up: Top
|
||
|
||
7 User Init
|
||
***********
|
||
|
||
The main task performed by El-Get is package initialization at Emacs
|
||
startup. It will care about all of them, their dependencies, and call
|
||
code provided by the recipe author. You can add your own setup code and
|
||
register it in a way that El-Get will evaluate it at the right time.
|
||
|
||
The package setup can either go into the `:after' property, or in a
|
||
file named `init-package.el' in `el-get-user-package-directory'. Any
|
||
such named file will get automatically loaded by El-Get at package init
|
||
time, if it exists.
|
||
|
||
* Menu:
|
||
|
||
* Before and After properties ::
|
||
* Initialization files::
|
||
|
||
|
||
File: el-get.info, Node: Before and After properties, Next: Initialization files, Up: User Init
|
||
|
||
7.1 Before and After properties
|
||
===============================
|
||
|
||
The `:before' and `:after' properties are evaluated by El-Get in the
|
||
package initialization sequence.
|
||
|
||
`:before'
|
||
This should be a lisp form to evaluate after both the
|
||
`Info-directory-list' and the `load-path' variables have been
|
||
taken care of, but before loading the package or any further
|
||
action from `el-get-init'. It will be run with the variable
|
||
`default-directory' set to the package directory.
|
||
|
||
`:after'
|
||
This should be a lisp form to evaluate after loading the package.
|
||
This function is registered for `eval-after-load' against the
|
||
recipe library by `el-get-init' once the `:load' and `:features'
|
||
have been setup. It will be run with the variable
|
||
`default-directory' set to the package directory.
|
||
|
||
|
||
Here's a couple of examples of package recipes that are using
|
||
`:before' and `:after' properties:
|
||
|
||
(:name asciidoc
|
||
: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 anything
|
||
:features anything-config
|
||
:before (global-set-key (kbd "M-s a") 'dim:anything-occur)
|
||
:after (setq w3m-command nil))
|
||
|
||
|
||
File: el-get.info, Node: Initialization files, Prev: Before and After properties, Up: User Init
|
||
|
||
7.2 Initialization files
|
||
========================
|
||
|
||
El-Get will see if a file named `init-package.el' exists in the
|
||
directory pointed at by the `el-get-user-package-directory' variable.
|
||
When this variable is not nil and if such a file does exist in the
|
||
directory, then El-Get will load the user init file for PACKAGE.
|
||
|
||
The initialization file is loaded at the same time as the `:after'
|
||
property would have be run, and just before it if you provide both.
|
||
|
||
El-Get automatically byte compiles the init file as needed and load
|
||
the compiled version.
|
||
|
||
|
||
File: el-get.info, Node: Recipes, Next: Authoring Recipes, Prev: User Init, Up: Top
|
||
|
||
8 Recipes
|
||
*********
|
||
|
||
All of El-Get behavior is controled with recipes that you can share,
|
||
download, update and author. This chapter explain how to manage your
|
||
recipes and how to author them and ship them.
|
||
|
||
Recipes are a list of properties, which are documented in the
|
||
variable EL-GET-SOURCES.
|
||
|
||
* Menu:
|
||
|
||
* Organizing recipes::
|
||
* Getting more recipes::
|
||
* Overriding package files::
|
||
|
||
|
||
File: el-get.info, Node: Organizing recipes, Next: Getting more recipes, Up: Recipes
|
||
|
||
8.1 Organizing recipes
|
||
======================
|
||
|
||
El-Get needs to find a package recipe to be able to install or update
|
||
it. After that the recipe content is saved in the status file and
|
||
cached, so that you can still start Emacs even if you remove the recipe
|
||
file.
|
||
|
||
The variable `el-get-recipe-path' is a list of directory paths where
|
||
to look for recipe files, in order. The recipe for a package `example'
|
||
must be named `example.rcp'. The first file named that way in the
|
||
`el-get-recipe-path' variable is used as the recipe.
|
||
|
||
To check which recipe is used for a given package, use either the
|
||
`M-x el-get-describe' or `M-x el-get-find-recipe-file' command.
|
||
|
||
This organisation with several path allow you to setup El-Get to use
|
||
its own recipes, recipes automatically created from online resources
|
||
(such as Emacswiki), and your own local recipes.
|
||
|
||
As it's easy for El-Get to use your own recipes in the exact same way
|
||
than it uses its own recipes, it allows you to share them very easily.
|
||
Send the file to a friend and have it store it at the right place.
|
||
|
||
It's also possible to setup `el-get-sources' with recipe
|
||
information. As long as the `type' property is not filled in
|
||
`el-get-sources', El-Get will first find the recipe as usual and then
|
||
merge the recipe content with the recipe skeleton provided by the
|
||
matching `el-get-sources' stanza.
|
||
|
||
El-Get also supports full User Init files, see *Note User Init::.
|
||
|
||
|
||
File: el-get.info, Node: Getting more recipes, Next: Overriding package files, Prev: Organizing recipes, Up: Recipes
|
||
|
||
8.2 Getting more recipes
|
||
========================
|
||
|
||
The command `M-x el-get-emacswiki-refresh' downloads the list of Emacs
|
||
Lisp files available at EmacsWiki. El-Get is able to automatically
|
||
install any such file at the right place in `el-get-dir'. The
|
||
integration of an automatically generated recipe is often not enough,
|
||
you often have to add some initialisation code. See *Note User Init::.
|
||
|
||
The command `el-get-elpa-build-local-recipes' downloads the list of
|
||
Emacs Lisp Packages from the ELPA archives you have setup, and make
|
||
them automatically available for El-Get.
|
||
|
||
|
||
File: el-get.info, Node: Overriding package files, Prev: Getting more recipes, Up: Recipes
|
||
|
||
8.3 Overriding package files
|
||
============================
|
||
|
||
El-Get manages the files associated with a package. You can browse
|
||
those files using the `el-get-cd' function. It's possible to hack on
|
||
those files, be aware that doing so might break your setup capability
|
||
to handle upgrades.
|
||
|
||
|
||
File: el-get.info, Node: Authoring Recipes, Prev: Recipes, Up: Top
|
||
|
||
9 Authoring Recipes
|
||
*******************
|
||
|
||
Authoring recipes is often very easy. El-Get goal is to adapt to any
|
||
Emacs Lisp code and distribution you can find out there in the wild, so
|
||
the list of features supported is quite large. Simple cases are very
|
||
simple, though.
|
||
|
||
If you want to submit recipes as pull request, please make sure to
|
||
run recipe checker (*note Recipe checker::) and paste the result in the
|
||
pull request comment.
|
||
|
||
* Menu:
|
||
|
||
* Recipe format::
|
||
* Dependencies::
|
||
* Byte Compilation::
|
||
* Autoloads::
|
||
* Build::
|
||
* Recipe checker::
|
||
|
||
|
||
File: el-get.info, Node: Recipe format, Next: Dependencies, Up: Authoring Recipes
|
||
|
||
9.1 Recipe format
|
||
=================
|
||
|
||
The recipe for the hypothetical package named `el-get-example' must be
|
||
provided in a file named `el-get-example.rcp'. This file will be
|
||
searched for as described in *Note Organizing recipes::. The variable
|
||
`el-get-sources' is also considered as a recipe source, as detailed in
|
||
*Note Organizing recipes::.
|
||
|
||
A recipe file contains a lisp property list. Accepted properties are
|
||
described in the documentation for the variable `el-get-sources', and
|
||
their possible values are described at the same place.
|
||
|
||
If your property list is missing the `:type' property, then it's
|
||
merged with the recipe one, so that you can override any definition
|
||
provided by `el-get' recipes locally.
|
||
|
||
`:name'
|
||
The name of the package. It can be different from the name of the
|
||
directory where the package is stored (after a `git clone' for
|
||
example), in which case a symlink will be created.
|
||
|
||
`:depends'
|
||
A single package name, or a list of package names, on which the
|
||
package depends. All of a packages dependencies will be installed
|
||
before the package is installed.
|
||
|
||
`:builtin'
|
||
Emacs major version (see EMACS-MAJOR-VERSION) from which Emacs
|
||
includes the recipe as a builtin. For example, `package.el' (the
|
||
implementation of ELPA) is part fo Emacs24 but needs an external
|
||
recipe for previous major versions.
|
||
|
||
`:pkgname'
|
||
The name of the package for the underlying package management
|
||
system (apt-get, fink or pacman, also supported by github and
|
||
emacsmirror), which can be different from the Emacs package name.
|
||
|
||
`:type'
|
||
The type of the package, currently el-get offers support for
|
||
apt-get, elpa, git, github, emacsmirror, git-svn, bzr svn, cvs,
|
||
darcs, fink, ftp, emacswiki, http-tar, pacman, hg and http. You
|
||
can easily support your own types here, see EL-GET-METHODS.
|
||
|
||
`:branch'
|
||
Which branch to fetch when using git (and by extension, github and
|
||
emacsmirror, which are derived form git). Also supported in the
|
||
installer in el-get-install.
|
||
|
||
`:url'
|
||
Where to fetch the package, only meaningful for git and http types.
|
||
|
||
`:username, :pkgname'
|
||
For the github type, these specify the user name and repo name to
|
||
clone from Github. For example, for el-get, the user name would be
|
||
`"dimitri"' , and the repo name would be `"el-get"' . As described
|
||
above, the `:pkgname' property is only required if the repo name
|
||
on Github differs from the Emacs package name. Note that the
|
||
emacsmirror type is just like the github type with `:username' set
|
||
to `"emacsmirror"' .
|
||
|
||
`:build'
|
||
Your build recipe, a list. A build command C whose `car' is a
|
||
symbol (see `symbolp') will be replaced by (eval C).
|
||
|
||
Then, each element of the recipe will be interpreted as a command:
|
||
|
||
If the element is a list of string, the first element of the list
|
||
must be the program to call, and each following element a different
|
||
argument to the call. No whitespace parsing is done.
|
||
|
||
Otherwise, if it is a list, any list sub-elements will be
|
||
recursively "flattened" (see `el-get-flatten'). The resulting
|
||
strings will be interpreted as individual shell arguments,
|
||
appropriately quoted.
|
||
|
||
`:build/system-type'
|
||
Your specific build recipe for a given SYSTEM-TYPE gets there and
|
||
looks like `:build'.
|
||
|
||
`:load-path'
|
||
A directory or a list of directories you want El-Get to add to your
|
||
LOAD-PATH. Those directories are relative to where the package
|
||
gets installed.
|
||
|
||
`:compile'
|
||
Allow to restrict what to byte-compile: by default, El-Get will
|
||
compile all elisp files in the `:load-path' directories, unless a
|
||
`:build' command exists for the package source. Given a `:compile'
|
||
property, El-Get will only byte-compile those given files,
|
||
directories or filename-regexpes in the property value. This
|
||
property can be a `listp' or a `stringp' if you want to compile
|
||
only one of those.
|
||
|
||
`:info'
|
||
This string allows you to setup a directory where to find a
|
||
`package.info' file, or a `path/to/whatever.info' file. It will
|
||
even run `ginstall-info' for you to create the `dir' entry so that
|
||
`C-h i' will be able to list the newly installed documentation.
|
||
Note that you might need to kill (`C-x k' ) your info buffer then
|
||
`C-h i' again to be able to see the new menu entry.
|
||
|
||
`:load'
|
||
List of files to load, or a single file to load after having
|
||
installed the source but before `require'ing its features.
|
||
|
||
`:features'
|
||
List of features el-get will `require' for you.
|
||
|
||
`:autoloads'
|
||
Control whether El-Get should generate autoloads for this package.
|
||
Setting this to `nil' prevents El-Get from generating autoloads
|
||
for the package. Default is `t'. Setting this to a string or a
|
||
list of string will load the named autoload files.
|
||
|
||
`:library'
|
||
When using `:after' but not using `:features' , `:library' allows
|
||
to set the library against which to register the `:after' function
|
||
against `eval-after-load'. It defaults to either `:pkgname' or
|
||
`:package' , in this order. See also `el-get-eval-after-load' .
|
||
|
||
`:options'
|
||
Currently used by http-tar and cvs support. When using http-tar,
|
||
it allows you to give the tar options you want to use. Typically
|
||
would be `"xzf"' , but you might want to choose `"xjf"' for
|
||
handling `.tar.bz' files e.g.
|
||
|
||
When using CVS, when it's set to `"login"', El-Get will first
|
||
issue a `cvs login' against the server, asking you interactively
|
||
(in the minibuffer) any password you might to enter, and only then
|
||
it will run the `cvs checkout' command.
|
||
|
||
`:module'
|
||
Currently only used by the cvs support, allow you to configure the
|
||
module you want to checkout in the given URL.
|
||
|
||
`:repo'
|
||
Only used by the elpa support, a cons cell with the form `(NAME .
|
||
URL)' , as in PACKAGE-ARCHIVES . If the package source only
|
||
specifies a URL, the URL will be used for NAME as well.
|
||
|
||
`:prepare'
|
||
This should be a lisp form to evaluate after both the
|
||
INFO-DIRECTORY-LIST and the LOAD-PATH variables have been taken
|
||
care of, but before loading the package or any further action from
|
||
`el-get-init' . It will be run with DEFAULT-DIRECTORY set to the
|
||
package directory.
|
||
|
||
`:before'
|
||
This exactly like `:prepare' property, but is reserved for user
|
||
customizations in EL-GET-SOURCES . Recipe files should not use
|
||
this property. It will be run just after :prepare.
|
||
|
||
`:post-init'
|
||
This should be a lisp form to evaluate after loading the package.
|
||
Intended for use from recipes. This function is registered for
|
||
`eval-after-load' against the recipe library by `el-get-init' once
|
||
the `:load' and `:features' have been setup. Like `:prepare' , it
|
||
will be run with DEFAULT-DIRECTORY set to the package directory.
|
||
|
||
`:after'
|
||
This exactly like the `:post-init' property, but is reserved for
|
||
user customizations in EL-GET-SOURCES. Recipe files should not
|
||
use this property. It will be run just after `:post-init' and
|
||
after any per-package user-init-file (see
|
||
EL-GET-USER-PACKAGE-DIRECTORY).
|
||
|
||
`:lazy'
|
||
Default to `nil' . Allows to override EL-GET-IS-LAZY per package.
|
||
|
||
`:localname'
|
||
Currently only used by both `http' and `ftp' supports, allows to
|
||
specify the target name of the downloaded file.
|
||
|
||
This option is useful if the package should be retrieved using a
|
||
presentation interface (such as as web SCM tool).
|
||
|
||
For example, destination should be set to `package.el' if the
|
||
package url has the following scheme:
|
||
|
||
"http://www.example.com/show-as-text?file=path/package.el"
|
||
|
||
`:website'
|
||
The website of the project.
|
||
|
||
`:description'
|
||
A short description of the project.
|
||
|
||
`:checksum'
|
||
Some methods in El-Get download files that are not so trusted
|
||
(e.g. anyone is allowed to modify emacswiki anytime). For these
|
||
cases you can set up a checksum value for a package, so you will
|
||
notice if El-Get tries to install a version that you haven't seen
|
||
before. The installation will simply fail and you will see the
|
||
good and bad checksum values in `*Messages*'. To get the checksum
|
||
value for a package initially, install the package while
|
||
EL-GET-VERBOSE is on.
|
||
|
||
Checksum calculation is currently supported by these methods with
|
||
the following meaning:
|
||
|
||
http, ftp and emacswiki with the SHA1 of the downloaded file
|
||
|
||
git in which it is an alias for `:checkout' (see below)
|
||
|
||
`:checkout'
|
||
A git refspec (branch, tag, commit hash) that should be checked out
|
||
after cloning the git repository. If provided, this overrides any
|
||
value for the `:branch' property. Unlike the `:branch' property,
|
||
this can be any valid argument to git checkout, including a tag
|
||
name or a commit hash. The intended use of this property is to
|
||
"lock" a repository at a particular revision, regardless of what
|
||
happens to the repo upstream.
|
||
|
||
Currently this property only has meaning for git type recipes.
|
||
Other VCS-based methods may implement support in the future.
|
||
|
||
`:shallow'
|
||
If set to t in a git recipe, `git-clone' will be run with `--depth
|
||
1' , which will create a so-called shallow clone by not
|
||
downloading all the history of the repository. The default is
|
||
controlled by the variable EL-GET-GIT-SHALLOW-CLONE, which is
|
||
`nil' by default.
|
||
|
||
`:submodule'
|
||
If set to `nil' in a git recipe, submodules will not be updated.
|
||
|
||
|
||
|
||
File: el-get.info, Node: Dependencies, Next: Byte Compilation, Prev: Recipe format, Up: Authoring Recipes
|
||
|
||
9.2 Dependencies
|
||
================
|
||
|
||
When a recipe provides a `:depends' property, El-Get makes sure that
|
||
the given list of packages is installed and initialized before the
|
||
package for the current recipe is installed and initialized.
|
||
|
||
|
||
File: el-get.info, Node: Byte Compilation, Next: Autoloads, Prev: Dependencies, Up: Authoring Recipes
|
||
|
||
9.3 Byte Compilation
|
||
====================
|
||
|
||
By default, El-Get will recursively byte-compile the directory where
|
||
the package is installed, that is each and any file called
|
||
`something.el'. Some packages include non Emacs Lisp directories, and
|
||
sometime test files that are not meant to pass byte compilation without
|
||
errors or warnings. It is possible to setup your recipe to either only
|
||
target some files of the package, or to bypass byte compiling entirely.
|
||
|
||
|
||
File: el-get.info, Node: Autoloads, Next: Build, Prev: Byte Compilation, Up: Authoring Recipes
|
||
|
||
9.4 Autoloads
|
||
=============
|
||
|
||
Think about providing `autoloads' for your recipe if some are
|
||
available. You can provide them yourself too, for packages that should
|
||
have support for autoloads but ship without them.
|
||
|
||
The `:prepare' property of a recipe is the right place where to put
|
||
added autoloads, as shown in this example:
|
||
|
||
(:name undo-tree
|
||
:description "Treat undo history as a tree"
|
||
:type git
|
||
:url "http://www.dr-qubit.org/git/undo-tree.git"
|
||
:prepare (progn
|
||
(autoload 'undo-tree-mode "undo-tree.el"
|
||
"Undo tree mode; see undo-tree.el for details" t)
|
||
(autoload 'global-undo-tree-mode "undo-tree.el"
|
||
"Global undo tree mode" t)))
|
||
|
||
The `:prepare' property of a recipe is considered the same as the
|
||
`:before' one, just evaluated after it. `:prepare' is meant for recipe
|
||
authors whereas `:before' is meant for user customisations. See *Note
|
||
Before and After properties::.
|
||
|
||
|
||
File: el-get.info, Node: Build, Next: Recipe checker, Prev: Autoloads, Up: Authoring Recipes
|
||
|
||
9.5 Build
|
||
=========
|
||
|
||
The `:build' property of the recipe allows for OS integration at build
|
||
time. Build happens after the package has been fetched, and allows to
|
||
run commands such as `make'.
|
||
|
||
The variable `el-get-emacs' contains the complete path where to find
|
||
the current Emacs executable you're running, as that's something build
|
||
commands often need.
|
||
|
||
As shell interpolation can get hairy, El-Get offers you to setup your
|
||
build commands as Emacs Lisp list. See the magit recipe for an example:
|
||
|
||
(:name magit
|
||
:website "https://github.com/magit/magit#readme"
|
||
:description "It's Magit! An Emacs mode for Git."
|
||
:type github
|
||
:pkgname "magit/magit"
|
||
:info "."
|
||
:autoloads ("50magit")
|
||
:build (("make" "all"))
|
||
:build/darwin `(,(concat "make EMACS=" el-get-emacs " all")))
|
||
|
||
|
||
File: el-get.info, Node: Recipe checker, Prev: Build, Up: Authoring Recipes
|
||
|
||
9.6 Recipe checker
|
||
==================
|
||
|
||
There are two ways to run recipe checker. One is to run it as an Emacs
|
||
command. Run `el-get-check-recipe' in the buffer opening the recipe to
|
||
be checked. You can also use a script to run the checker. This is
|
||
convenient if you want to check multiple recipes at once.
|
||
|
||
test/check-recipe.el PATH/TO/RECIPE.rcp ANOTHER/RECIPE.rcp ...
|
||
|
||
MS Windows user may need to call the script like this:
|
||
|
||
emacs -batch -Q -l test/check-recipe.el PATH/TO/RECIPE.rcp ...
|
||
|
||
|
||
|
||
Tag Table:
|
||
Node: Top763
|
||
Node: Introduction1228
|
||
Node: Acknowledgments2303
|
||
Node: Glossary3753
|
||
Ref: Glossary - Init4849
|
||
Ref: Glossary - Install5151
|
||
Ref: Glossary - Recipe6238
|
||
Ref: Glossary - Status6662
|
||
Ref: Glossary - Update6920
|
||
Node: Installing7158
|
||
Node: Install the developper version8031
|
||
Node: Skip Emacswiki recipes when installing8776
|
||
Node: Usage9612
|
||
Node: Setup11901
|
||
Node: Basic Setup12297
|
||
Node: The el-get function13536
|
||
Node: Distributed Setup14812
|
||
Node: Setup Customization16706
|
||
Node: User Init17852
|
||
Node: Before and After properties18539
|
||
Node: Initialization files20047
|
||
Node: Recipes20700
|
||
Node: Organizing recipes21175
|
||
Node: Getting more recipes22690
|
||
Node: Overriding package files23388
|
||
Node: Authoring Recipes23771
|
||
Node: Recipe format24386
|
||
Node: Dependencies34045
|
||
Node: Byte Compilation34391
|
||
Node: Autoloads34957
|
||
Node: Build36083
|
||
Node: Recipe checker37055
|
||
|
||
End Tag Table
|