1 Copyright (C) 2010-2011, 2014 Free Software Foundation, Inc.
2 See the end of the file for license conditions.
5 This branch contains the sources, deployment scripts, and auxilliary
6 files for the Emacs Lisp package archive (elpa.gnu.org).
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).
15 ** admin/ -- scripts for administering the package archive.
16 ** html/ -- HTML for the elpa.gnu.org website.
17 ** packages/ -- source code for the packages.
22 ** Contents of the packages/ directory:
23 This directory holds the package sources, with one subdirectory for
26 Each directory in here corresponds to a package, which can be
27 either a single-file package or a multifile package.
29 A nightly cron job refreshes the GNU ELPA archive from this repository.
31 This cron job only creates a new package when the "version" (as specified in
32 the "Version:" header) of a package is modified. This means that you can
33 safely work on the next version here without worrying about the unstable
34 code making it to GNU ELPA, and simply update the "version" when you want to
39 *** Add a simple (1-file) package as packages/NAME/NAME.el.
41 The file needs to follow the usual coding conventions (most importantly
42 start with ";;; <file> --- <description>") and have a "Version:" and
43 "Maintainer:" pseudo-header.
45 *** Add a multi-file package as a directory, packages/NAME.
47 It needs to have a file named packages/NAME/NAME.el which follows the same
50 *** Commit your changes the usual way ("git add", "git commit", etc).
52 Changes in the Git repository do not immediately propagate to the
53 user-facing archive (what users see when they do `M-x list-packages').
54 That is done by deploying the archive, which happens automatically
55 once a day, and the changes are only reflected when the "Version:"
60 Each package should follow the ELPA packaging conventions, but there are
61 some differences due to the way the deployment script creates the packages
62 and the web-pages from this source code:
63 - Multi-file packages put the package metadata in the main <pkg>.el file
64 in the format used for single-file packages: the <pkg>-pkg.el file is
65 auto-generated from it.
66 - Every package should have both a "Version:" *and* a "Maintainer:".
67 - the "URL:" header can be used to specify the home page
68 of the package, if it's maintained externally.
69 - A "News:" section (or "NEWS" file) can/should be used to list the
70 user-visible changes of each version.
71 - The "Package-Type:" header can be used to force the type of package
72 created (can be either `simple' for single-file packages or `multi' for
73 tarballs). By default the type is decided based on whether there are
74 several Elisp files in the source.
75 - If you want some files to not be included in the tarball, you can
76 put a `.elpaignore' file in the root of your package directory, where you
77 can list patterns of files to ignore (this file is passed to tar's -X).
81 Some packages are maintained in external branches. These should be
82 appropriately listed in the `externals-list' file.
83 There are two different cases: subtrees and externals.
85 In both cases, a copy of the code is kept in the `elpa' repository and
86 should be sync'd with the upstream every once in a while. This copy may
87 include local changes, tho ideally these should be kept to a minimum.
91 In the `subtree' case, the copy of the code is kept here in the
92 corresponding `packages/<pkg>' directory. You should be able to use:
94 git subtree add --prefix=packages/<pkg> <remote-repo> <remote-branch>
96 to add your package from some remote repo, and then
98 git subtree pull --prefix=packages/<pkg> <remote-repo> <remote-branch>
100 whenever you want to update it. On older git versions you can try "git
103 When you're adding and pulling, DO NOT --SQUASH!!
105 Don't worry about flooding elpa.git's commit log with your package's
106 commit messages. Your package is part of elpa.git. Squashing
107 doesn't help and only gets in the way.
111 In the `external' case, the copy of the code is not kept here but in the
112 `externals/<pkg>' branch in the `elpa' repository.
114 You can check out all the external packages into the `packages' directory
119 You can check out a specific external PACKAGE into the `packages'
120 directory with these commands:
123 git clone --reference .. --single-branch --branch externals/PACKAGE $(git config remote.origin.url) PACKAGE
125 If you already have a packages/PACKAGE directory with a previous
126 checkout, you can update it like this:
133 If you want to develop a package publicly prior to its first release (to
134 benefit from others' feedback, primarily), but not in an external repo,
136 - you can simply put "Version: 0" to indicate that this should not be
138 - or you can push to an "ephemeral" branch -- subject to rebase and eventual
139 removal upon finishing merge -- for the duration of the incubation.
143 ** To install all the packages "in place":
148 This compiles and generates autoloads for all the packages in the
149 packages/ directory. You can then add that directory, e.g. with:
151 (eval-after-load 'package
152 '(add-to-list 'package-directory-list ".../elpa/packages"))
154 ** To deploy the package repository as a remotely-accessible archive:
159 (cd ../elpa; git log --format=%H | tail -n 1) >.changelog-witness
161 ln -s ../elpa/GNUmakefile
162 admin/update-archive.sh
164 This deploys the packages to the staging/ directory (sibling of "build").
165 Unlike "make", this makes a full copy of the packages, tars up
166 multi-file packages, and doesn't byte-compile any files.
168 ** To access a deployed archive
170 To access the archive via HTTP, have a symlink (say) /var/www/packages
171 pointing to DEST/packages, and set up Emacs with
173 (setq package-archives '(("new-elpa" . "http://foo.com/packages")))
175 You can also access the archive via normal file access. Such "local
176 archives" are useful for debugging:
178 (setq package-archives '(("local-elpa" . ".../elpa/packages")))
180 ** Notes specific to elpa.gnu.org
182 The way things are set up on this machine, we refresh the archive by
183 a cron job. You can do it by hand by logging in (access set up by FSF
188 admin/update-archive.sh
190 Which makes a full archive deployment, as discussed above. The symlink
191 /var/www/packages points to the staging package directory under
194 The Org mode dailies are also fetched and added by the script
195 admin/org-synch.sh, run as a cron job.
198 This file is part of GNU Emacs.
200 GNU Emacs is free software: you can redistribute it and/or modify
201 it under the terms of the GNU General Public License as published by
202 the Free Software Foundation, either version 3 of the License, or
203 (at your option) any later version.
205 GNU Emacs is distributed in the hope that it will be useful,
206 but WITHOUT ANY WARRANTY; without even the implied warranty of
207 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
208 GNU General Public License for more details.
210 You should have received a copy of the GNU General Public License
211 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
216 paragraph-separate: "[
\f]*$"