README

   1 Copyright (C) 2010-2011 Free Software Foundation, Inc.
   2 See the end of the file for license conditions.
   3
   4
   5 This branch contains the sources, deployment scripts, and auxilliary
   6 files for the Emacs Lisp package archive (elpa.gnu.org).
   7
   8 This file explains the branch layout, how to add and edit packages,
   9 and how to deploy the archive (either on elpa.gnu.org, or a local copy
  10 for testing purposes).
  11
  12
  13 * DIRECTORY LAYOUT
  14
  15 ** admin/    -- scripts for administering the package archive.
  16 ** html/     -- HTML for the elpa.gnu.org website.
  17 ** packages/ -- source code for the packages.
  18
  19
  20 * PACKAGES
  21
  22 ** Contents of the packages/ directory:
  23 This directory holds the package sources, with one subdirectory for
  24 each package.
  25
  26 ** To add a package:
  27
  28 *** Add a simple (1-file) package as packages/NAME/NAME.el.
  29
  30 *** Add a multi-file package as a directory, packages/NAME.
  31
  32 *** Commit your changes the usual way ("bzr add", "bzr commit", etc).
  33
  34 Changes in the Bzr repository do not immediately propagate to the
  35 user-facing archive (what users see when they do `M-x list-packages').
  36 That is done by deploying the archive.
  37
  38
  39 * DEPLOYMENT
  40
  41 ** To use the package repository as a "site installation" of packages:
  42
  43   make site
  44
  45 This compiles and generates autoloads for all the packages in the
  46 packages/ directory, and creates a site/ directory containing symlinks
  47 to the package directories.
  48
  49 Now you have to add this site/ directory to `package-directory-list',
  50 and all the packages will be available.
  51
  52 ** To deploy the package repository as a remotely-accessible archive:
  53
  54   make archive
  55
  56 or
  57
  58   make archive-full
  59
  60 This deploys the packages to the archive/ directory.  Unlike "make
  61 site", this makes a full copy of the packages, and tars up multi-file
  62 packages.
  63
  64 A full deployment also copies the admin scripts to archive/admin, and
  65 fetches externally hosted packages (currently, the Org daily builds)
  66 and adds them to the archive.
  67
  68 ** To access a deployed archive
  69
  70 To access the archive via HTPP, have a symlink (say) /var/www/packages
  71 pointing to DEST/packages, and set up Emacs with
  72
  73   (setq package-archives '(("new-elpa" . "http://foo.com/packages")))
  74
  75 You can also access the archive via normal file access.  Such "local
  76 archives" are useful for debugging:
  77
  78   (setq package-archives '(("local-elpa" . "DEST/packages")))
  79
  80 ** Notes specific to elpa.gnu.org
  81
  82 The way things are set up on this machine, we refresh the archive by
  83 logging in (login access set up by FSF admins), and
  84
  85 su elpa
  86 cd ~elpa/elpa
  87 bzr up
  88
  89 Then make a full archive deployment, as discussed above.  The symlink
  90 /var/www/packages points to the staging package directory under
  91 /home/elpa/.
  92
  93 The Org mode dailies are also fetched and added by the script
  94 admin/org-synch.sh, run as a cron job.
  95
  96 \f
  97 This file is part of GNU Emacs.
  98
  99 GNU Emacs is free software: you can redistribute it and/or modify
 100 it under the terms of the GNU General Public License as published by
 101 the Free Software Foundation, either version 3 of the License, or
 102 (at your option) any later version.
 103
 104 GNU Emacs is distributed in the hope that it will be useful,
 105 but WITHOUT ANY WARRANTY; without even the implied warranty of
 106 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 107 GNU General Public License for more details.
 108
 109 You should have received a copy of the GNU General Public License
 110 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 111
 112 \f
 113 Local variables:
 114 mode: outline
 115 paragraph-separate: "[  \f]*$"
 116 end: