mirror of
https://github.com/dimitri/el-get.git
synced 2024-09-29 13:08:51 +08:00
820 lines
28 KiB
Plaintext
820 lines
28 KiB
Plaintext
This is el-get.info, produced by makeinfo version 4.8 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.
|
||
|
||
* Menu:
|
||
|
||
* Recipe format::
|
||
* Dependencies::
|
||
* Byte Compilation::
|
||
* Autoloads::
|
||
* Build::
|
||
|
||
|
||
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.
|
||
|
||
Please refer to that documentation.
|
||
|
||
|
||
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, 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")))
|
||
|
||
|
||
|
||
Tag Table:
|
||
Node: Top762
|
||
Node: Introduction1227
|
||
Node: Acknowledgments2302
|
||
Node: Glossary3752
|
||
Ref: Glossary - Init4848
|
||
Ref: Glossary - Install5150
|
||
Ref: Glossary - Recipe6237
|
||
Ref: Glossary - Status6661
|
||
Ref: Glossary - Update6919
|
||
Node: Installing7157
|
||
Node: Install the developper version8030
|
||
Node: Skip Emacswiki recipes when installing8775
|
||
Node: Usage9611
|
||
Node: Setup11900
|
||
Node: Basic Setup12296
|
||
Node: The el-get function13535
|
||
Node: Distributed Setup14811
|
||
Node: Setup Customization16705
|
||
Node: User Init17851
|
||
Node: Before and After properties18538
|
||
Node: Initialization files20046
|
||
Node: Recipes20699
|
||
Node: Organizing recipes21174
|
||
Node: Getting more recipes22689
|
||
Node: Overriding package files23387
|
||
Node: Authoring Recipes23770
|
||
Node: Recipe format24201
|
||
Node: Dependencies24870
|
||
Node: Byte Compilation25216
|
||
Node: Autoloads25782
|
||
Node: Build26908
|
||
|
||
End Tag Table
|