NOTE: This extension is in early state; meaning that it is experimental. The core elements are being planned, written and tested. Currently there is only the batch command line UI:
# 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 <http://emacswiki.org> which enhance standard Emacs. The typical procedure to add a new extension to Emacs has been:
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
The epackages are in the form of distributed1 Git2 version control repositories. The traditional packaging methods, like ELPA3, rely on archives like *.tar.gz. In contrast, the DVCS approach offers interesting features over the traditional archive distribution approach:
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 the packaging, refer to section "The DELPS framework".
[1] DVCS = Distributed Version Control System http://en.wikipedia.org/wiki/Distributed_revision_control
[3] http://www.emacswiki.org/emacs/ELPA
[PLANNED: not yet implemented; Use makefile: "make ui"]
Command M-x epackage 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:
The fields are:
In this view, some of the commands are (see mode help C-h m):
Planned:
Building the initial list of available packages takes some time at startup. The package state is shown with following status indicators:
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) |
Quick links for developers:
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:
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.
% * *
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 | |
* ----------------------------------------> |
| | |
============================================= |
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
| *-<type>.el autoloads, install, activate...
|
+--packages/ Git DVCS repositories
|
+-- 00sources/ Yellow pages: list of available packages
+-- package/ Downloaded PACKAGE
+-- ... |
The Git repository branches used are:
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:
<PACKAGE, the Emacs extension root dir>
| <upstream files and possible directories>
|
+- .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:
;; <explain in paragraph or two what is preconfigured>
<activation statements>
(provide 'PACKAGE-ekg-xactivate) |
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 |
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.
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.
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 <http://www.debian.org/doc/debian-policy/ch-controlfields.html>.
*Package: <unique name, all lowercase>
*Section: <data | extensions | files | languages | mail | tools | M-x finder-list-keywords>
License: <GPL-[23]+ | BSD | MIT | Apache-2.0 | ... | Custom | None>
Licence-Text: <only, if license is "Custom">
*Depends: emacs (>= 23)
Recommends:
Status: [ <keyword> ...]
Archive: <ELPA/GNU, ELPA/Marmalade, MELPA, ELPA>
Compat: [ <epackage version> ]
*Maintainer: First Last first.last@example.com
Bugs: [ URL ]
*Upstream: First Last first.last@example.com
Upstream-Bugs: [ URL ]
Vcs-Type:
Vcs-Url:
Vcs-Browser:
Vcs-Args:
Vcs-User:
Vcs-Password:
Homepage:
Wiki: http://www.emacswiki.org/emacs/<page name>
X-<Field>-<Name>: [anything]
Commentary: <single *.el file>
Info: <location of *.info files>
*Description: <short one line>
[<Longer description>]
.
[<Longer description, next paragraph>] |
An example:
Package: test-package
Section: extensions
License: GPL-2+
Depends: emacs (>= 23)
Status: unmaintained
Maintainer: Joe Average joe@example.org
Upstream: John doe jdoe@example.com
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. |
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.gnu.org>, "ELPA/Marmalade" <http://marmalade-repo.org>, "MELPA" <http://melpa.milkbox.net/>, and being phased out original "ELPA" <http://tromey.com/elpa/index.html>. 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 <http://www.emacswiki.org> 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 <http://www.debian.org/doc/debian-policy/ch-relationships.html>.
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:
Examples:
Package: cygwin-mount
Description: Add Cygwin mount point support (ms)
Package: lib-xml-rpm
Description: library of remote procedure calls alls 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. It is recommended to use addresses that don't move; those of http://Freecode.com, http://www.Sourceforge.com, http://Launchpad.net, http://Github.com, http://Bitbucket.com etc. The Freecode is especially good because it provides project information in coherent manner. Through Freecode it is also possible to browse related software and subscribe to project announcements. Freecode is also easy for the upstream developers to set up because it does not require heavy project management; only links.
In any case, the homepage URL should not directly point to the developer's volatile personal homepage if there are alternatives. It is good idea to encourage "garage" upstream developers to set up their software at some project hosting site which encourage collaboration and provide infrastructure e.g. for issue tracking. For more information, see <http://en.wikipedia.org/wiki/Comparison_of_open_source_software_hosting_facilities>.
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 <http://spdx.org/licenses/>. A special word "None" should be used if the software has no license information in any of the source files. Examples of valid license tokens:
GPL-2, GPL-2+, GPL-3, GPL-3+, MIT, BSD-2-clause, Apache-2.0 |
If License is not any of the OSI known standard licenses <http://www.opensource.org/licenses>, 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:
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 <http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps>
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) jdoe@example.com,
Joe Average (Co-developer) jave@example.com |
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 <http://www.debian.org/doc/developers-reference/best-pkging-practices.html#bpp-vcs>
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 <http://www.debian.org/doc/developers-reference/best-pkging-practices.html#bpp-vcs>. 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 <http://www.debian.org/doc/developers-reference/best-pkging-practices.html#bpp-vcs>. 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 <Vcs-Url> co -d upstream <Vcs-Args>"
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 <http://www.emacswiki.org>. 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 |
The latest epackage format is always described in section "Epackage specification" above. Below you can find list of formats and changes.
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 |
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 <http://www.debian.org/doc/debian-policy/ch-relationships.html> 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:
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 spcific 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 immateria an 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.
[Within groups, sorted by priority]
General
REPO
GUI
Extensions
Some day in the future: