Info Catalog elisp: Multi-file Packages elisp: Packaging

elisp: Package Archives

 
 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.  Lisp Libraries
 (emacs)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.  Remote Files
      (emacs)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, 
 GnuPG (gnupg)Top.  Emacs comes with an interface to GNU Privacy Guard,
 EasyPG (epa)Top.
 

Info Catalog elisp: Multi-file Packages elisp: Packaging