Homepage: http://www.emacswiki.org/emacs/DELPS
Author: Jari Aalto
Updated:
Distributed Emacs Lisp Package System (DELPS)
Preface 2009
This utility was initially designed to be used from command line:
# Or run the provided Makefile: "make ui"
emacs --batch -Q -l /path/to/epackage.el -f epackage-batch-ui-menu
Emacs has been around for decades now. Many new version have
come and gone. And yet there are wealth of useful extensions
available e.g. at which enhance
standard Emacs. The typical procedure to add a new extension
to Emacs has been:
o Find an extension at places like
http://dir.gmane.org/gmane.emacs.sources or
http://www.emacswiki.org
o Download and save *.el file(s) along `load-path'
o Read the installation information. Usually embedded in comments
at the beginning of *.el file(s).
o Modify the Emacs startup file `~/.emacs'
to arrange loading the extension to one's liking.
That's quite a bit of work for each extension; reaching
thousands out there. Not to mention keeping up to date. Many
Linux distributions offer package managers to download and
install programs. E.g. Debian has command *apt-get/aptitude*
[1], Redhat uses *rpm* [2], Suse uses *yast* [3]. So why not
make one for Emacs as well.
The DELPS concept has been designed around two ideas: it
borrows the Debian style package management and it uses
version control for distributing packages.
Each Emacs extension is wrapped into a specific format which
basically follows the Debian [4] packaging style where a
separate control directory named `epackage/' is used for all
the packaging details: activation, autoloads and installation
etc. In addition, each package is imported in and deployed
using Git Distributed Version Control System (DVCS). A
specific *Sources* *List* file(s) list the available Git
repositories from where users can download packages. Once a
package has been downloaded, subsequent downloads are very
efficient because, due to benefits of version control, only
deltas are transferred.
If you're a Emacs user, all these details do not concern you.
From `M-x' `epackage' management view you can the packages.
There are several ways how to install: an *autoload* install
(no Emacs setup changes), *enable* install (hooks, intractive
commands), or *activation* install (the activation code can
change Emacs environment). Later you can upgrade packages. To
refresh list of packages, ask to "get" new *Sources* *List*
that holds information about Git repositories.
If you're a developer who would like to make an extension
available for others, you need to be familiar with the `Git'
distributed version control system.
The epackage system can co-exist with any other packaging
system like ELPA [4]. User's standard Emacs startup files,
like `~/.emacs' are not modified with this system.
[1] http://en.wikipedia.org/wiki/Advanced_Packaging_Tool
[2] http://en.wikipedia.org/wiki/RPM_Package_Manager
[3] http://en.wikipedia.org/wiki/YaST See also
http://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified
[4] http://www.debian.org/doc/developers-reference/best-pkging-practices.html#bpp-debian-control
[5] http://www.emacswiki.org/emacs/ELPA
Epackage - the DVCS packaging format
The epackages are in the form of distributed[1] Git[2]
version control repositories. The traditional packaging
methods, like ELPA[3], rely on archives like *.tar.gz. In
contrast, the DVCS approach offers interesting features over
the traditional archive distribution approach:
o Efficient downloads; fast, only deltas are transferred.
o Helping package authors made easy; have you found an error?
Have a spare time to fix it? Generate diff straight from the
version control repository.
o Select any version; pick latest or
downgrade to a older version with ease.
o Contains history of package in one place. No more scattered
pieces around Internet.
o Encourages social collaboration; more easier interacting
with the upstream e.g. through http://github.com
push/pull.
Each extension is prepared for distribution as follows: an
upstream code is imported into a Git repository, the epackage
system is installed on top of upstream code in a separate
directory, the whole git repository is made available online
and information about the availability of new package is
recorded to a separate *Sources* *List* file. The packaging
work can be done by anyone who wants to set up a repository.
It doesn't necesarily need to be done by the original Emacs
extension author (upstream) who may not be familiar with the
`Git' distributed version control system. For more
information about packaging, refer to section "The DELPS
framework".
[1] DVCS = Distributed Version Control System
http://en.wikipedia.org/wiki/Distributed_revision_control
[2] http://git-scm.org
[3] http://www.emacswiki.org/emacs/ELPA
User commands
[IDEA ONLY. NOT YET IMPLEMENTED; Use makefile: "make ui"]
Command `M-x' `epackage' (LIFE HAPPENED, NEVER GOT
IMPLEMENTED) is alias for function `epackage-manager'. It
builds buffer where packages can be browsed, fetched, built
and installed. The view contains:
[mode indicators]
name section status v:VERSION package-description
1 2 3 4 5
Mode indicators are:
o compile - byte compile package on install phase.
o activate|enable - Auto-enable or activate on install phase
See "status" for more explanation.
The fields are:
o 1 - Unique package name. No two package can have the same name.
o 2 - Package classification. `M-x' `finder-list-keywords'
o 3 - status: (A)activated (E)nabled (I)installed etc.
o 4 - Version number. Only known once package has been downloaded.
o 5 - Short package description
In this view, some of the commands are (see mode help `C-h' `m'):
o _a_, Install activate configuration for package.
modifies Emacs environment.
o _A_, Deactivate. Uninstall activate configuration for package.
o b, Generate boot loader.
o B, Byte compile boot loader.
o _c_, Clean package's configuration files (whole uninstall).
o _d_, Download package.
o D, run `dired' on package installation directory.
as for new wish list features, report bugs etc.
o g, Get. Update package sources list.
o _e_, Enable standard configuration for package.
o _E_, Disable standard configuration for package.
o l, (l)ist: available, installed, downloaded, enabled,
activated, autoloaded and not-installed packages.
o m, mark package (for command install or remove).
o _o_, Install autoload configuration for package.
o _r_, Remove; delete package physically from local disk.
o s, sort command. Change listing by several criterias.
o u, upgrade package to newer version.
o U, upgrade all packages
o v, view command. E.g (a)activation file, (i)info file.
o q, quit. Run `bury-buffer'.
o x, execute marked (install, purge, remove).
Planned:
o edit package's *info* file.
o email upstream to report a bug in the extension.
o email epackage maintainer to report a packaging bug.
You can e.g. send a requests to update contents of the
'info' file as needed.
Building the initial list of available packages takes some
time at startup. The package state is shown with following
status indicators:
o *(A)ctivated*. The package has been downloaded and code to
immediately activate the package is in use. This setting
changes user's Emacs environment as defined by the
packager. The changes typically include modifying hooks to
activate the package e.g. by file extension, adding key
bindings to access new commands etc. You might want to
use (v)iew command to see what exactly happens.
o *(E)enabled*. One step down from Activated state. Interactive
functions and variables are provided in latent `autoload'
state for user to call with `M-x' . User
configuration is not modified in any way. Some basic
setup changes like modifying `auto-mode-alist' to activate
modes for certain new file extensions may be provided.
o *(a)utoloaded*. The package has been downloaded and code to
to provide autoloads to access package functions as been
installed. User can call features with `M-x' .
If you want full
control over package setup, set package to autoload state
and use `~/.emacs' Emacs startup file to fully configure
the extension.
o *(D)ownloaded*. Package has been fetched to local disk,
but that is all. No setup whatsoever. Useful for complete
control and DIY setups.
o (u)unmaintained. The package has been flagged as unmaintained.
o (b)uggy. The package has been flagged to have problems if used.
o (c)ompiled. Package has been byte compiled.
o (e)macs core. Package has been included in core Emacs.
o (x)emacs core. Package has been already included in core XEmacs.
About Configuration
Private repositories
Private installed package repositories, or other sources, can
be defined in variable `epackage--sources-file-list'. The
list of files included in there will be combined variable
with `epackage--url-sources-list'. The order of the entries
matter: the packages are read first-served basis. An example:
(setq epackage--sources-file-list ;; This is the default
'("~/.emacs.d/epackage-local.lst"))
Say the *epackage-local.lst* lists package =foo= and file
pointed by `epackage--url-sources-list' also contains package
=foo=. Because the files will be combined,
*epackage-local.lst* will take precedence; its package =foo=
will be used for download. Run `M-x'
`epackage-sources-list-build' after any changes either to this
variable or contents of the files it points to.
Automatic install of packages
The basic operation mode is to do one action at a time to give
user a full control. In daily use it may be desireable to byte
compile package after they have been downloaded. For that, use:
(require 'epackage)
(add-to-list 'epackage--download-action-list 'compile)
The DELPS framework
Quick links for developers:
o https://github.com/jaalto/project--emacs-epackage-sources-list
o https://github.com/jaalto/project--emacs-epackage-template
The DELPS system was inspired by the Debian packaging
management. There are two primary actors: (1) the epackage
maintainer and (2) the upstream. These two can be the
same person or two separate persons. In the picture below:
o _A_ = An Emacs user who wants to install new software
o (Y)ellow pages = The sources list file that contains
information about available epackages around the globe.
o _E_ = The epackage. Maintained by a person who has found an
interesting utility and wrapped it in epackage format. He
is the maintainer of epackaged software. He keeps
track of new releases and makes new epackages periodically
available. If the initial packager looses interest,
someone else can continue his work. He supplies the *URL*
to the yellow pages to notify about availability of epackage.
o _U_ = Upstream. Person or team who wrote Emacs Lisp extension,
the code or utility than enhances Emacs.
In order to find a package, the yellow pages is consulted. It
is seeded and updated by the epackage maintainer that wish to
make his work available. The user A does not need to know any
details of this process; like in Debian, he installs an
epackage and periodically asks for upgrades.
o The location of Yellow Pages is fixed (%).
o The location of E's (epackage maintainer) and U's (upstream)
can be anywhere (*).
o The E and U can be the same person (the upstream).
% * *
A Y E U
=============================================
| | | keep eye on |
| fetch | * ------------> |
* --------> | | <----------- |
| <-------- * | epackage new |
| upgrade | add epackage | releases |
| | location | |
| | <------------ * |
| | (url) | |
| | |
| install "X" | |
* ------------------------> | |
| <------------------------ | |
| DVCS repo download | |
| | |
| upgrade "X" | |
* ------------------------> | |
| <------------------------ * |
| download DVCS "delta" | |
| | |
| report epackage bug | |
* ------------------------> | |
| report program bug | |
* ----------------------------------------> |
| | |
=============================================
Local directory layout
The packages are installed under root `epackage--root-directory',
which defaults to `~/.emacs.d' respectively. The components below
the root directory are organized as follows:
epackage/ Under epackage--root-directory
|
+-- 00coonf/
| epackage-loader.el For user. One big boot file.
| epackage-load-path.el Internal. Used during byte-compile.
| sources.lst Internal. Package sources.
|
+-- 10install/ Extension "install" files
| *-.el autoloads, install, activate...
|
+--packages/ Git DVCS repositories
|
+-- 00sources/ Yellow pages: list of available packages
+-- package/ Downloaded PACKAGE
+-- ...
Epackage specification
The Git repository branches used are:
o *master*, required. The published package.
Branched off from *upstream*. Adds directory
`epackage/' where the packaging information resides.
o *patches*, optional. Patches to *upstream* code, if any.
This branch is merged to *master*.
o *upstream*, required. The original unmodified upstream code.
Releases are tagged with label
"upstream/YYYY-MM-DD[--VERSION]". An
example: `upstream/2009-12-31--0.3-devel'.
The YYYY-MM-DD is the date of upstream release or best
guess like if only year is known, use YYYY-01-01. The
options part "--VERSION" is the official version of
extension; if known. Not all extensions include version
information. The ISO 8601 date is needed so that the
release date is immediately available e.g. for post
processing and so that the tags sort nicely by date.
The same in pictures. The `master' contains merges from
`patches' and `upstream' branches:
patches o - o (modifications; merged to master)
/
upstream * ---- o
\ \ (merge)
master o ---- o - => contains epackage/ directory
The packaging method borrows concept from Debian where a
separate control directory is used for packaging information.
The control directory name `epackage/' is not configurable.
The layout of an epackaged Emacs extension looks like following:
|
|
+- .git/ Version control branches
|
+-- epackage/
info required: The information file
lisp optional: Location of Emacs Lisp files
ignore optional: regexp to ignore Emacs Lisp files
PACKAGE-epackage-0loaddefs.el optional: extracted ###autoload statements
PACKAGE-epackage-autoloads.el optional: autoload statements (manual)
PACKAGE-epackage-clean.el optional: Code to run "make clean" equivalent
PACKAGE-epackage-compile.el optional: Code to byte compile the extension
PACKAGE-epackage-configure.el optional: Code to run ./configure
PACKAGE-epackage-examples.el optional: Customization examples
PACKAGE-epackage-install.el required: Code to make the extension available. Not required fo lib-* packages.
PACKAGE-epackage-uninstall.el optional: Code to remove the extension
PACKAGE-epackage-xactivate.el optional: Code to activate the extension
All these configuration files are combined in a single loader
file. Loading a single file is faster than spending time in
loading small file along `load-path'. The alphabetic order
makes it possible to combine the install parts safely
together:
ls |
egrep -vi '00|clean|compile|configure|examples|uninstall' |
xargs cat > PACKAGE-00-loader.el
The *-0loaddefs.el
This file contains extracted `###autoload' definitions. The file
is usually automatically generated. The file does not modify
user's environment. If extension does not contains any
`###autoload' definitions, the manually crafted `*-install.el'
file can be used as a substitute. In case of missing
`##autoload' stanzas, you're encouraged to contact upstream
with a possible patch. The "zero" at the start of the name is
to help proper sorting ordering of files. Mnemonic: "if you
load this file, you can start calling extension's features".
The file ends in:
(provide 'PACKAGE-epackage-0loaddefs)
The *-autoloads.el
This file contains manually written `autoload' statements.
This file acts as a backup if there is no `###autoload'
definitions. Its purpose it to publish prospective functions
(interactive or not) that might be called from programs or by
the user. Mnemonic: "if you load this file, you can write lisp
code to call the functions, or you can call extension's
interactive functions via `M-x'". The file ends in:
(provide 'PACKAGE-epackage-autoloads)
The *-clean.el
This file contains command(s) to remove files that can be
generated. This file is very rarely neeed. It may be useful with
bigger packages that come with a `Makefile' or `./configure'
script. Mnemonic: "Same as if you would run 'make clean'".
Exception: the byte compiled files do not need deleting. They are
deleted prior calling this file.
The *-compile.el
This file contains commands to byte compile the extension. The
file is run at the root directory of the extension with
`load-path' set to include all the relevant directories.
Evaluating the file must byte compile all that is needed.
Possible variables and functions defined here must have
`PACKAGE-epackage-*' prefix to keep the Emacs name space clean.
*Exception:* packages that only have a single "*.el" file do
not need to define this file. There is no `provide' statement
in this file. An example for a simple extension consisting of
two files:
(dolist (file '("foo-lib.el" "foo.el"))
(byte-compile-file file))
The *-configure.el
This file contains command to configure the extension's build
system. This file is very rarely neeed. It may be useful with
bigger packages that come with a `Makefile' or `./configure'
script. Mnemonic: "Same as if you would invoke ./configure".
This file is only necessary if the *.el files cannot be used
"as is" to install the package. The `./configure' may e.g.
write loaddefs or autoloads or assemble package in a way that
produces an installable extension.
The *-examples.el
This file contains anything the upstream may have explained in
the comments, or interesting snippets various users have found
useful to customize the extension. It provides a showcase, or
scratch book, to present anything that might be useful to be
put into `~/.emacs' startup file. Mnemonic: "Look examples in
this file for ideas how to make more out of the extension".
This file is not intended to be loadable and it must not
contain any `provide' statements. All functions and private
variables written must start with prefix `my-PACKAGE-* so
that they can be easily be copied to user's own setup.
It is recommend that any attempt to load this file generates
an error. Add something like this to the beginning of file to
remind that it is user's responsibility to copy the relevant
code:
;; Prevent loading this file. Study the examples.
(error "PACKAGE-epackage-examples.el is not a config file")
The *-install.el (required; unless package name is lib-*)
This file publishes user variables and interactive `M-x'
functions in *autoload* state. It may make conservative
changes to Emacs environment: those of modifying
`auto-mode-alist' or setting up hooks. The *-install* in name
refers to standard installation, or availability for that
matter, of interactive functions. *Note:* try to avoid
`require' or `load' commands as much as possible. That helps
keeping Emacs startup fast and lean. Mnemonic: "if you load
this file, the extension is up and ready to be used in your
Emacs. You can start calling extension's functions or load new
files that activate the extension's features". The file ends
in:
(provide 'PACKAGE-epackage-install)
Note: If package name starts with =lib-=, this file is not
required. Libraries that are used for building other extensions
are not requied to provide any install files. The autoloads
publish available functions.
Note: If the upsream has arranged to "###autoload" proper
variables and functions, there is already loaddefs file which
you can take advantage of. The loaddefs file is always
preloaded during boot. In simplest case, if there is nothing
more to install that providing callable M-x functions (no hook
setu up etc.), the content of the file would be:
(require 'PACKAGE-epackage-0loaddefs)
(provide 'PACKAGE-epackage-install)
The *-uninstall.el
This file does the opposite of `*-install.el' and
`*-activate.el' It runs commands to remove the extension as if
it has never been loaded. Due to the nature of Emacs, it is
not really practical to completely try to uninstall the
package. The actual symbols (defined functions and variables)
are not removed. The uninstallation usually covers undoing
changes to *-hook, *-function and `auto-mode-alist' and to
similar variables. To shake free from extension completely,
restart Emacs after uninstall a epackage. The file ends in:
(provide 'PACKAGE-epackage-uninstall)
The *-xactivate.el
This file does the same as *-install.el, but it can do more.
Instead of being conservative, it can modify current
environment by adding more custom functions to hooks or
arrange key bindings so that when pressed, a feature is loaded
and activated. It may also loop through `buffer-list' to
activate features in existing buffers immediately. It is best
that any custom settings, like variables and prefix keys, are
defined in `~/.emacs' *before* this file gets loaded. As with
`*-install.el', try to avoid any `require' or `load' commands
and stick to `autoload'. To keep Emacs namespace clean, name
all custom variables or functions as `PACKAGE-epackage-*'.
Mnemonic: "If you load this file, the bells and whistles are
turned on". The "x" at the start of the name is to help proper
sorting ordering of configuration files. The file layoyt:
;; Description:
;;
(provide 'PACKAGE-ekg-xactivate)
The 'ignore' file
List of Emacs regular expression entries on their own lines to
ignore files in upstream package. The epackage-devel-*
functions examine the packaging structure and can create files
like `*-0autoloads.el'. If this file exists, it is read and
files matches are ignored. The regexp(s) matches path relative
to the package root directory. An example:
;; Comments on their own lines start with a semicolon
one.el\|two.el
tree.el
The 'format' file
Type of Git repository. The type is indicated in the first line
of the file. Valid value in this file is "upstream".
This file is used to mark repositories of different origin. In
a normal case, where a packager downloads code, creates Git
repository, add `/epackage', and puts it available -- the
*format* file is not needed. But if upstream and packager is
the same person and would like to use same repository for both
the development and epackage distribution, the layout must be
indicated separately because of branch differences.
The standard Epackage has following Git branches. Branch that
is used for distribution (contains epackage/ directory) is
marked wit asterisk:
* master REQUIRED
upstream REQUIRED
[patches] OPTIONAL
Compared to upstream development, there may be only on branch:
* master
The "master" is effectively the latest development which may
not be best for direct distribution. Many divide development
into separate lines:
* master (when "devel" is stable, it is merged here)
devel
If you compare to the Epackage layout, the upstream is missing
required branch "upstream". This `format' file is there to
notify that in this repository the "upstream" branch is
expected to be missing. It also notifies that in this
repository the tag names do not have =upstream/= prefix.
The 'lisp' file
This file contains Emacs Lisp file directories relative to the
root of package. Empty lines and standalone comments on their
own lines starting with semicolon(;) are ignored. Comments
must not be placed at the directory lines. If all the Emacs
Lisp files are in the package's root directory, this file not
needed. The file is used internally to find out if the package
has been byte compiled or not.
The 'info' file
A RFC 2822 (email) formatted file, which contains information
about the extension. The header field names are not case
insensitive; but if you use the default *get.sh*, it expects
the Vcs-* field to be case-sensitive. Continued lines must be
indented with only 1 space. Required fields are marked with
asterisk (*). In the long description part, new paragraphs are
separated by a single dot(.) character on their own line. The
layout of the `info' somewhat mirrors concepts of `control' file in
Debian packaging system which is explained in
.
*Package:
*Section:
License:
Licence-Text:
*Depends: emacs (>= 23)
Recommends:
Status: [ ...]
Archive:
Compat: [ ]
*Maintainer: First Last
Bugs: [ URL ]
*Upstream: First Last
Upstream-Bugs: [ URL ]
Vcs-Type:
Vcs-Url:
Vcs-Browser:
Vcs-Args:
Vcs-User:
Vcs-Password:
Homepage:
Wiki: http://www.emacswiki.org/emacs/
X--: [anything]
Commentary:
Info:
*Description:
[]
.
[]
An example:
Package: test-package
Section: extensions
License: GPL-2+
Depends: emacs (>= 23)
Status: unmaintained
Maintainer: Joe Average
Upstream: John doe
Vcs-Type: http
Vcs-Url: http://www.emacswiki.org/emacs/download/test-package.el
Homepage: http://example.com
Wiki: http://www.emacswiki.org/emacs/TheTestPackage
Commentary: test-package.el
Info: doc/test-package.info
X-Development:
YYYY-MM-DD upstream email confirmad.
Description: test package with various functions
Main command [C-u] M-x test-package runs various tests on
the current lisp code. With a prefix argument, shows also
notes and minor details.
.
Note: 2010-12-03 the code hasn't been updated since 2004.
Details of the info file fields
Notes: Use one space to indent a continued field. Limit
maximum line length to 80 characters. In Emacs, see variable
`fill-column' and set it to a little less, like 75. The *info*
file must be saved as UTF-8 in case it contains non-ASCII
characters.
Archive
Value of archive repository where package is also available.
The known values are "ELPA/GNU" ,
"ELPA/Marmalade" , "MELPA"
. The purpose of
this field is to list other package repositories where this
package is available via some package manager. It is not used
for "dumb archives" like although
it technically could be accessed with el-get.el; which is not
a package manager in itself but only a download script.
Bugs
URL to report epackaging issues of current extension. The URL can
be an email address or a link to an issue tracker. In case the
field is empty or missing, the `Maintainer' field is used.
Epackaging issues that are candidate for reporting: request to
update to the newest upstream release, suggestions for updating
*Description* or other fields, broken URLs in the *Description*
or other fields etc.
See *Upstream-Bugs* or *Upstream* for reporting Emacs extension
usage problems.
Commentary
This field contains a path, relative to epackage root
directory, to a single Emacs Lisp file which contains
documentation suitable for `M-x' `finder-commentary'. In order
to find documentation, this field must exist even for
packages that contain single Emacs Lisp file. Extension
developers should study core Emacs *lisp-mnt.el* and function
`lm-commentary'. The documentation read from file is enclosed
in between tags:
;;; Commentary:
;;; Change Log:
Compat
The compatibility level used in the package. The format may
change in time and this field indicates which layout was used. If
the value is missing or is empty, the latest is assumed. Usually
an epackage maintainer should follow the latest format to prevent
installation problems. See section "Epackage Compatibility
Levels" for more information.
Note: yhis field should be left empty. It is part of the
specification, but hopefully never needed.
Conflicts
List of packages that must be removed before install can be
done. This field follows the guidelines of
.
Description (required)
The first line of this field is a concise description that
fits on maximum line length of 80 characters; word
"Description: " included. The long description should explain
the essential M-x commands to use the package. The details of
the extension are explained in the following paragraphs which
are separated from each other with a single dot(.) on their
own lines. The paragraphs are indented by one space.
Guidelines:
o For modes, start short description with
"major mode for ..." or "minor mode for..."
o For libraries, start short description with
"library of ..."
o For client communication, start short description with
"client for ..."
o If extension is related to a specific operating system,
add this information in to the first line. E.g. add word
"Cygwin" or "(ms)" to mark "Microsoft" OS. The details of
Operating system integration can be explained in the long
description part.
o Don't use word "Emacs" on the first line. It's redundant.
Examples:
Package: cygwin-mount
Description: Add Cygwin mount point support (ms)
Package: lib-xml-rpm
Description: library of remote procedure calls over HTTP
Depends (required)
List of dependencies in all lowercase: Emacs flavor and
external packages required. Listing packages that are included
in core Emacs would be unnecessary and slow down parsing. The
Emacs flavor can have an optional version information enclosed
in parenthesis using comparison operators ">=", "<=" and
logical "!". A between range is not defined. The logical *or*
operator works only between Emacs flavors and is indicated
with vertical bar "|".
In case an extension works only in imited versions of Emacs,
this information should be written to the end of `Description'
(which see). Old packages that are not updated to work for
latest Emacs releases are candidate for removal from the
official Epackage Sources List. Examples:
Depends: foo
Depends: emacs (>= 23) | xemacs (>= 20), foo
To mark that package does not work in XEmacs, use "!". The
version parameter is ignored with logical *not* but
the parenthesis are still required:
Depends: emacs (>= 23), xemacs (!), foo
_Limitations_: The *vertical* *bar*, OR-operator(|), is not
really used. It is only respected on the Emacs flavor part.
Using OR-operator anywhere else causes treating the elments as
if written "exension | extension" => "extension, extension".
The *version* *information* is a no-op anewhere else than
Emacs flavor check. This kind of fine grained package
dependencies has never been in use with Emacs Lisp extensions.
There is no support for version numbers in Emacs Lisp commands
`provide', `require', `load', `load-file' and `load-library'.
Extensions typically check the available features with
`boundp' and `fboundp' to see if they have the required
environment. So don't write:
Depends: emacs (>= 23), xemacs (!), foo (>= 0.9)
|
Ignored. Has no effect
See also section "Development notes: depends".
Homepage
URL to the project's homepage. Examples include
http://www.sourceforge.com, http://launchpad.net,
http://github.com, http://bitbucket.com etc.
management; only links.
Resist using volatile homepage URLs that may change. Encourage
garage upstream developers to set up their software at some
project hosting site which would encourage collaboration and provide
infrastructure e.g. for issue tracking. For more information, see
.
Info
location of info files relative to the package root directory.
Wildcard `*' can be used in case of mult-part info files. An
examples:
Info: doc/*.info
License
The valid License abbreviations must follow official Linux
foundations list , or if it contains
additional text to an existing licence, it must be labelled
"Custom". See field *License-Text*.
In case the software is dual licenced, or there is different
license for documentation, it would be good to explain these
in additial extra field:
X-License-Comment: code GPL-2+, documentation GFDL
License-Text
In case "License: Custom" the full license text should be
included here. In case the License is known to The Linux
Foundation SPDX database, URL to that database is enough. Do not
point to any other web page, as these may be changed, removed or
updated without a notice. An example:
License: Custom
License-Text: http://spdx.org/licenses/Ruby
X-License-Comment: Ruby license is dual: GPL or custom text
Maintainer (required)
The epackage maintainer. Contains the name and address of the
person who maintains ad hosts the epackage Git repository. If the
upstream is also the epackage maintainer, the content of this
field is identical to *Upstream* field.
Package (required)
The name of the package in all lowercase satisfying regexp
"[a-z][a-z0-9-]+". Usually base name of the extension file or
the canonical known name in case of bigger packages like
"gnus". An example "html-helper-mode.el" => package name is
"html-helper-mode". No two packages can have the same name.
Please notify upstream if about package name problems.
Guidelines:
o Length of package name is not limited.
o Add `*-mode', In case of minor or major modes. Always
add this suffix even if extension name does not
explicitly say so. An example "python.el" => name package
"python-mode". This helps searching for mode package.
o If extension is a library (e.g. xml-rpc.el), start
package name with `lib-*'. This way user
who is browsing the list of packages can ignore or complete
these on minibuffer prompts easily.
Note: There may be exotically named extensions like "crypt++",
but the *epackage* name must not contains special characters.
In package name, spell out the used letters: "crypt-plusplus".
Consider contacting upstream to discuss about possible name
change.
Recommends
List of packages which the extension can support or take
advantage of. E.g. this field would list package B if A can
take advantage of package B. However it is not a requirement
to install B for package A to work. This field is must *not*
be used to announce related packages. That information can be
mentioned in a separarate paragraph like "SEE ALSO" in the end
of *Description* field or in file `*-examples.el'. The
*Recommends* field follows guidelines of
Section (required)
This field contains category keyword. The valid keywords are
those listed in `M-x' `finder-list-keywords'.
Status
This field lists succinct information about the package. Each
keyword has a unique meaning. The allowed list is:
keyword := core-emacs[-NN.N]
| core-xemacs[-NN.N]
| unmaintained
| broken
| unsafe
| stable
| unstable
| experimental
| obsolete
The `core-*' values mark the extension or its features being
included (or will be) in the mentioned [X]Emacs. The optional
NN.N announces in which Emacs flavor the feature was included;
e.g. *core-emacs-22.1*.
Value `unmaintained' means that the original developer has
vanished or abandoned the project and is no longer available
for contacting or further development.
Value `unsafe' means that the not all the symbols are name
space clean (prefix-*); meaning that some of the commands
might clash with existing function in Emacs.
The current release status of epackage can be indicated with
terms `stable' (no active upstream developed recently),
`unstable' (upstream is active developing) or `experimental'
(no guarantees, not necessarily tested, this is the latest
code). Value `broken' means that there are known problems,
limitations or that the package may not work in some Emacs
version. Further information about "brokenness" should be
supplied in the end of *Description:* field in section "BUGS"
or similar.
Value `obsolete' means that the functionality can be found in
recent Emacs. Obsolete packages are candidate for removal
at some point. It would be good idea to mention Emacs version
and feature where this is available in a paragraph at the end
of *Description:* field section "NOTE" or similar.
Upstream
The upstream developer's name and email address. Multiple
developers or alternative addresses are separated by commas,
just like in email. The role can be expressed in RFC 2822
comment-parenthesis. An example:
Upstream: John Doe (Author) ,
Joe Average (Co-developer)
Note: Don't just copy the addresses from source code. It is of no
use for anybody if the address is no longer valid. Contact
upstream to verify the address before making epackage available:
To: upstream@example.com
Subject: Emacs package.el
Your software is bundled with the Distributed Emacs Lisp
Package System called epackage. Would you verify that this
address is still your preferred contact. Simply reply
shortly "ok" or let me know if you prefer to use another
address.
Thanks,
John Doe
Upstream-Bugs
URL to report issues of current extension. The URL can be an
email address(es) or a link to an issue tracker. In case the field
is empty or missing, the `Upstream' field is used.
Vcs-Browser
The URL address to the version control browser of the upstream
repository. This field follows the guidelines of
Vcs-Type
Version Control System type information of *Vcs-Browser*. The
value is the lowercase name of a version control program; cvs,
svn, bzr, hg, git etc. A special value "http" can be used to
signify direct HTTP download. This field follows the guidelines of
.
An example of an Emacs extension hosted directly at a web
page:
Vcs-Type: http
Vcs-Url: http://www.emacswiki.org/emacs/download/vline.el
If `Vcs-Type' is *http*, this argument can be list of URLs separated
by whitespace. And example to span multple lines:
Vcs-Type: http
Vcs-Url: http://example.com/file1.el
http://example.com/file2.el
http://example.com/file3.el
Vcs-Url
The Version Control System repository URL without any options.
For CVS, this is the value of `CVSROOT' which contains the
protocol name. This field follows the guidelines of
.
An example:
Vcs-Type: cvs
Vcs-Url: :pserver:anonymous@example.com/reository/foo
Vcs-Args
Additional arguments passed to VCS program after specifying
the *Vcs-Url* E.g. CVS directories may need a specific module
to check out. A setup like below would yield command: "cvs -d
co -d upstream "
Vcs-Type: cvs
Vcs-Url: :pserver:anonymous@example.com/reository/foo
Vcs-Args: module
Vcs-User
Login name used to access VCS repository. In case the
repository cannot be accessed simply by visiting the `Vcs-Url'
(or in the case of CVS: pressing RETURN at login prompt), this
is the used login name; typically `anonymous' or the like.
Vcs-Password
Password for the Version Control System repository. In some
extremely rare cases a generic password, like "guest" to
access repository, may be needed.
Wiki
This field points to extension page (or page that talks about
it) at . If the extension does not
yet have a Emacswiki page, encourage upstream to create one.
X-*
Any other custom fields can be inserted by using the `X-*' field
notation. Examples:
X-Comment: This is a comment.
X-Upstream-Homepage: URL
X-Development: YYYY-MM-DD upstream email confirmed
If converting extension to a epackage needs special treatment,
please document those in field like:
X-Packaging:
Before BBDB can be used, the autoloads file must be generated.
Run command:
.
./configure && make autoloads
.
And it will generate file lisp/bbdb-autoloads.el
Epackage compatibility levels
The latest epackage format is always described in section
"Epackage specification" above. Below you can find list of
formats and changes.
o 2011-12-03 Draft spec. Compatibility level 1.
Batch command line interface
Several FUNCTIONS can be accessed from command line in a
manner of:
emacs --batch -Q -l /path/to/epackage.el -f FUNCTION
The functions and their command line arguments are:
;; Interactive, menu driven
epackage-batch-ui-menu
epackage-batch-ui-upgrade-packages-all
epackage-batch-upgrade-package PACKAGE ...
epackage-batch-download-package PACKAGE ...
epackage-batch-remove-package PACKAGE ...
epackage-batch-clean-package PACKAGE ...
epackage-batch-activate-package PACKAGE ...
epackage-batch-deactivate-package PACKAGE ...
epackage-batch-enable-package PACKAGE ...
epackage-batch-disable-package PACKAGE ...
epackage-batch-ui-list-installed-packages
epackage-batch-ui-list-not-installed-packages
epackage-batch-ui-list-downloaded-packages
epackage-batch-ui-loader-file-generate
epackage-batch-ui-loader-file-byte-compile
;; This command upgrades the sources list
epackage-batch-ui-sources-list-upgrade
Development notes
XEmacs
This extension was written in Emacs 23, but it may work in
Emacs 22 (2007) although that has not been tested. No support
for older Emacs versions is on the chart. Real life, daily
work and my own other Open Source projects take their share. I
have to regret that I will not be having resources to port or
support this utility to XEmacs. Please send patches if you
take the code to ride in XEmacs. Fortunately XEmacs already
includes its own package manager: see the `pui-*' commands.
Depends
The *OR-operator(|)*, is not really implemented. The packages
"emacs" and "xemacs" are treated specifically and the effect
of "|" is actually the same as if it were written with comma:
Depends: emacs (>= 23) | xemacs (> 21.3)
Depends: emacs (>= 23), xemacs (> 21.3)
Writing an algorithm for package depends clause that would
understand variety of operations (>=, <=, !, |) is
challenging. Take for examples the Debian package depends
guidelines described at
which was the source of inspiration for the used syntax. The
Debian packaging system is centralized, so it has the
knowledge about all the available packages and their version
numbers. In Debian, the commands can build the full
dependency list and check if install is even possible. In
contrast, the epackage sources list refers to distributed
locations. The available versions or further depends
information can only be determined only after the package has
been downloaded by reading the "Depends:" field. Because of
this, the distributed system:
o Cannot know beforehand what epackages would be required for X
o Cannot know beforehand if it is possible to to even install
package fully to satisfy all depends.
o Cannot ask to install a specific version because the
version information is only available *after* the package
has been downloaded. The version information is in the
Git tags.
o Cannot easily know en masse to which packages updates
would be available. Because there is no central place to
read, each repository needs to be probed separately
to determine updates. This causes slight network perfomance
wear if done frequently (multiple times a day).
In daily use these issues don't matter much. If package X
requires Y, the Y will be downloaded. If Y further requires Z,
the Z will be downloaded etc. Somewhere at the end of chain
the download will stop. It is just that no progress indicator
can be presented to tell how many more packages there is to
load. This is no issue actually as most of the Emacs Lisp
extensions are self standing and have no external
dependencies; in contrast to Linux packages that may have huge
number of library dependencies.
PACKAGE VERSIONS AND DEPENDS
NOTE: upstream should use standard Emacs package `inversion.el'
which provides means to ensure that a specific library version
is required.
Regarding the requirement for a specific version of the package
in form of:
Depends: foo (>= 0.9)
|
No-op. Will not be used.
Emacs extensions have never had any Perl like "use PACKAGE
VERSION" statements, thus there is not much point of
implementing this the `epackage.el'. The syntax is there in
case somewhere in the future Emacs modifies the `require' and
relevant `load' calls to accept optional version argument. For
now, as it has always been, the extension developers ensure
that the extensions work together with the help of tests like
`boundp', `fboundp' and `featurep'. If an extension breaks due
to change in some other extension, it is best to notify the
original developer and get the code updated. Compatibility
problems between extensions are usually temporary. In case the
upstream developer is no longer there to to fix things, the
extension is best to be removed from list of packages. Or, if
you have the time and skills, you can start maintaining an old
extension to bring it new life and becoming the new upstream.
Depends and removing packages
The depends system was added to *ease* *installing* of
packages. But we can't have one without touching the other
issues: what if package is removed? Say package A requires
both B and C. Currently user has total control and can remove
package C and make A non-working. Nothing prevents removing or
disabling packages as one wishes. In order to do the removals
in a safe fashion, the dependency graphs of all packages would
need to be collected and maintained.
Currently there are no removal dependecy checks of any kind.
Version
Why is there no "Version:" field in the `info' file that could
be used to show the extension version to the user? The Git
repository is supposed to have tags for all upstream versions
of the package. It would be duplicate and manual work to keep
the `info::Version' field in synch with the tags of Git
repository. The version numbers are in fact immaterial and
unnecessary: nice to know, but in daily use, not much used.
User isn't downloading some specific version of extension, but
upgrading his packages to the latest versions. In Epackage, an
upgrade updates full Git repository, thus bringing all
possible versions of the extension available; of these, the
latest is always activated.
To select an old version, user must work on the Git
repositories manually. There are no plans to support selecting
previous versions because that would bring instability to the
whole system. Imagine this: A depends on B, but user selects
specific version of B - which is older one and won't work with
other packages. Multiply this problem with N versions of
several extensions. Summary: it's best to stick with the
latest and send bug reports from latest versions to upstream.
DEVELOPING THOUGHTS (TODO)
[entries sorted by priority]
General
o Sources List: We have a Download problem, like broken link to
repository
=> Display to user that he should consider sending and error
report mail the Sources List maintainer
o Lint: if upstream is also the packager, then his repository
should not have "upstream" branch. There is no need.
o Boot: What if user manually deletes directories?
What to do with left over config files? Implement self healing.
Check on boot?
o Sources List: If package is no longer there, but has been
downloaded, the package may have been removed. Notify user about
obsolete package. Package may also have been renamed. What do
we do then?
o [already implemented?] After download. Trying to install or
activate package, check emacs compatibility and refuse to
install if not met.
REPO
o Someone recreated repo: git push --force. It can no longer
be pulled => recreate from scratch. Problem: User has made his
local modifications, how to check?
Maintainer kills the repo and re-instantiates it
from fresh? Symptoms: can't pull, because repos have diverged and
do not have common objects. SOLUTION: offer deleting repo and
downloading it again. Warn if there are any local modifications,
the user might want to have a backup (*.b). Can we do that? What
if a backup already exists?
o Check validity of "git tag -l" and upstream/* against the
specification. Two dashes etc.
o Better Fetch, pull conflict notifications. Now a Git error.
o Git tags (versions of packages), where is this information kept?
Cache? Affects GUI.
o New updates available? Git polling mechanism with idle timers?
Auto upgrade?
GUI
o Write M-x epackage-manager (the real interface).
o Cache. Build it dynamically from packages and
combine with package information (e.g. version).
o If user selects DETAIL view, collect
information to another buffer dynamically (info, git tags,
current git branch)
o Rescan current information? (what is installed, what is not)
=> Keep cache? Or regenerate, or scan at startup every time?
Idle timers?
Extensions
o Big packages that come with configure? What to do with them?
Further ideas
o Do something for *.texinfo files in big packages.
o Verify Compatibility Level of a downloaded epackage
o Handle Conflicts field
o Edit yellow pages catalog?
=> Submit/update yellow pages catalog changes?
=> version controlled, patches? Submit via email? Github Gist?
o The epackage/*-compile.el is run with `eval-current-buffer'.
Security considerations? Should we care?
These are Git repositories and maintainers should be trusted
=> possible solution: require detached GPG signing of *-compile.el
=> Too much hassle for developers?
o Package removal: present some analysis command to show what
would happen if package X would be removed. Are other packages
depending on X or can it be removed safely?