From: Chong Yidong Date: Sun, 6 Mar 2011 21:52:17 +0000 (-0500) Subject: Document package archives in the Lisp manual. X-Git-Tag: emacs-pretest-24.0.90~104^2~275^2~660 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0b3cecebd530db6eab09aa3338eafc97b03446ff;p=emacs.git Document package archives in the Lisp manual. * doc/lispref/package.texi: Update index keywords. (Package Archives): New node contents. Document package-x.el. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 4129b37986f..32d13b57ffd 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2011-03-06 Chong Yidong + + * package.texi: Update index keywords. + (Package Archives): New node contents. Document package-x.el. + 2011-03-06 Juanma Barranquero * makefile.w32-in (srcs): Add package.texi. diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 4de44fe165d..62fbc2a9a07 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -5,7 +5,8 @@ @setfilename ../../info/package @node Packaging, Antinews, System Interface, Top @chapter Preparing Lisp code for distribution -@cindex packaging +@cindex package +@cindex Lisp package Emacs provides a standard way to distribute Emacs Lisp code to users. A @dfn{package} is a collection of one or more files, @@ -24,8 +25,11 @@ put it in a @dfn{package archive} for others to download. @node Packaging Basics @section Packaging Basics -@cindex packaging basics @cindex package attributes +@cindex package name +@cindex package version +@cindex dependencies +@cindex package dependencies A package is either a @dfn{simple package} or a @dfn{multi-file package}. A simple package is stored in a package archive as a single @@ -69,6 +73,7 @@ installing this package also automatically installs its dependencies; if any dependency cannot be found, the package cannot be installed. @end table +@cindex content directory, package Installing a package, either via the Package Menu, or via the command @code{package-install-file}, creates a subdirectory of @code{package-user-dir} named @file{@var{name}-@var{version}}, where @@ -78,6 +83,7 @@ package's @dfn{content directory}. It is where Emacs puts the package's contents (the single Lisp file for a simple package, or the files extracted from a multi-file package). +@cindex package autoloads Emacs then searches every Lisp file in the content directory for autoload magic comments (@pxref{Autoload}). These autoload definitions are saved to a file named @file{@var{name}-autoloads.el} @@ -98,7 +104,8 @@ typically called to begin using the package. @node Simple Packages @section Simple Packages -@cindex single file packages +@cindex single file package +@cindex simple package A simple package consists of a single Emacs Lisp source file. The file must conform to the Emacs Lisp library header conventions @@ -160,7 +167,7 @@ single-file package to a package archive. @node Multi-file Packages @section Multi-file Packages -@cindex multi-file packages +@cindex multi-file package A multi-file package is less convenient to create than a single-file package, but it offers more features: it can include multiple Emacs @@ -206,10 +213,10 @@ file is used as the long description. If the content directory contains a file named @file{dir}, this is assumed to be an Info directory file made with @command{install-info}. @xref{Invoking install-info, Invoking install-info, Invoking -install-info, texinfo, Texinfo}. The Info files listed in this -directory file should also be present in the content directory. In -this case, Emacs will automatically add the content directory to -@code{Info-directory-list} when the package is activated. +install-info, texinfo, Texinfo}. The relevant Info files should also +be present in the content directory. In this case, Emacs will +automatically add the content directory to @code{Info-directory-list} +when the package is activated. Do not include any @file{.elc} files in the package. Those are created when the package is installed. Note that there is no way to @@ -234,5 +241,79 @@ variable @code{load-file-name} (@pxref{Loading}). Here is an example: @node Package Archives @section Creating and Maintaining Package Archives - -To be done. +@cindex package archive + + Via the Package Menu, users may download packages from @dfn{package +archives}. Such archives are specified by the variable +@code{package-archives}, whose default value contains a single entry: +the archive hosted by the GNU project at @url{elpa.gnu.org}. This +section describes how to set up and maintain a package archive. + +@cindex base location, package archive +@defopt 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 @code{(@var{id} . @var{location})}, where @var{id} is the name of +the archive (a string) and @var{location} is its @dfn{base location} +(a string). + +If the base location starts with @samp{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. +@end defopt + + 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 +@code{package-x} library. This is included with Emacs, but not loaded +by default; type @kbd{M-x load-library @kbd{RET} package-x @kbd{RET}} +to load it, or add @code{(require 'package-x)} to your init file. +@xref{Lisp Libraries,, Lisp Libraries, emacs, The GNU Emacs Manual}. +Once loaded, you can make use of the following: + +@defopt 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 @code{package-x} library +will use this base location. + +The directory name should be absolute. You may specify a remote name, +such as @file{/ssh:foo@@example.com:/var/www/packages/}, if the +package archive is on a different machine. @xref{Remote Files,, +Remote Files, emacs, The GNU Emacs Manual}. +@end defopt + +@deffn Command package-upload-file filename +This command prompts for @var{filename}, a file name, and uploads that +file to @code{package-archive-upload-base}. The file must be either a +simple package (a @file{.el} file) or a multi-file package (a +@file{.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 @code{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). +@end deffn + +@deffn Command package-upload-buffer +This command is similar to @code{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 +@file{.el} file) or a multi-file package (a @file{.tar} file); +otherwise, an error is raised. +@end deffn + +@noindent +After you create an archive, remember that it is not accessible in the +Package Menu interface unless it is in @code{package-archives}.