39.4 Creating and Maintaining Package Archives

Via the Package Menu, users may download packages from package
archives. Such archives are specified by the variable
package-archives, whose default value contains a single entry:
the archive hosted by the GNU project at http://elpa.gnu.org. This
section describes how to set up and maintain a package archive.

— User Option: package-archives

The value of this variable is an alist of package archives recognized
by the Emacs package manager.

Each alist element corresponds to one archive, and should have the
form (id . location), where id is the name of
the archive (a string) and location is its base location
(a string).

If the base location starts with ‘http:’, it is treated as a HTTP
URL, and packages are downloaded from this archive via HTTP (as is the
case for the default GNU archive).

Otherwise, the base location should be a directory name. In this
case, Emacs retrieves packages from this archive via ordinary file
access. Such “local” archives are mainly useful for testing.

A package archive is simply a directory in which the package files,
and associated files, are stored. If you want the archive to be
reachable via HTTP, this directory must be accessible to a web server.
How to accomplish this is beyond the scope of this manual.

A convenient way to set up and update a package archive is via the
package-x library. This is included with Emacs, but not loaded
by default; type M-x load-library <RET> package-x <RET> to
load it, or add (require 'package-x) to your init file.
See Lisp Libraries.
Once loaded, you can make use of the following:

— User Option: package-archive-upload-base

The value of this variable is the base location of a package archive,
as a directory name. The commands in the package-x library
will use this base location.

The directory name should be absolute. You may specify a remote name,
such as /ssh:foo@example.com:/var/www/packages/, if the
package archive is on a different machine. See Remote Files.

— Command: package-upload-file filename

This command prompts for filename, a file name, and uploads that
file to package-archive-upload-base. The file must be either a
simple package (a .el file) or a multi-file package (a
.tar file); otherwise, an error is raised. The package
attributes are automatically extracted, and the archive's contents
list is updated with this information.

If package-archive-upload-base does not specify a valid
directory, the function prompts interactively for one. If the
directory does not exist, it is created. The directory need not have
any initial contents (i.e., you can use this command to populate an
initially empty archive).

— Command: package-upload-buffer

This command is similar to package-upload-file, but instead of
prompting for a package file, it uploads the contents of the current
buffer. The current buffer must be visiting a simple package (a
.el file) or a multi-file package (a .tar file);
otherwise, an error is raised.

After you create an archive, remember that it is not accessible in the
Package Menu interface unless it is in package-archives.

Maintaining a public package archive entails a degree of responsibility.
When Emacs users install packages from your archive, those packages
can cause Emacs to run arbitrary code with the permissions of the
installing user. (This is true for Emacs code in general, not just
for packages.) So you should ensure that your archive is
well-maintained and keep the hosting system secure.

One way to increase the security of your packages is to sign
them using a cryptographic key. If you have generated a
private/public gpg key pair, you can use gpg to sign the package like
this:

gpg -ba -o file.sig file

For a single-file package, file is the package Lisp file;
for a multi-file package, it is the package tar file.
You can also sign the archive's contents file in the same way.
Make the .sig files available in the same location as the packages.
You should also make your public key available for people to download;
e.g., by uploading it to a key server such as http://pgp.mit.edu/.
When people install packages from your archive, they can use
your public key to verify the signatures.

A full explanation of these matters is outside the scope of this
manual. For more information on cryptographic keys and signing,
see GnuPG. Emacs comes
with an interface to GNU Privacy Guard, see EasyPG.