Commit 0b3ceceb authored by Chong Yidong's avatar Chong Yidong
Browse files

Document package archives in the Lisp manual.

* doc/lispref/package.texi: Update index keywords.
(Package Archives): New node contents.  Document package-x.el.
parent 2b0787b3
2011-03-06 Chong Yidong <cyd@stupidchicken.com>
* package.texi: Update index keywords.
(Package Archives): New node contents. Document package-x.el.
2011-03-06 Juanma Barranquero <lekktu@gmail.com>
* makefile.w32-in (srcs): Add 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}.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment