Commit 07b48fa9 authored by Paul Eggert's avatar Paul Eggert
Browse files

Merge from mainline.

parents d4323972 ef272f1f
2011-03-06 Chong Yidong <cyd@stupidchicken.com>
* search.texi (Isearch Yank): C-y now bound to isearch-yank-kill.
2011-03-03 Drake Wilson <drake@begriffli.ch> (tiny change)
* misc.texi (emacsclient Options): Add q/quiet.
......
......@@ -271,19 +271,24 @@ keybindings. These keybindings are part of the keymap
@node Isearch Yank
@subsection Isearch Yanking
Within incremental search, you can use @kbd{C-w} and @kbd{C-y} to grab
text from the buffer into the search string. This makes it convenient
to search for another occurrence of text at point.
Within incremental search, @kbd{C-y} (@code{isearch-yank-kill})
copies text from the kill ring into the search string. It uses the
same text that @kbd{C-y}, outside of incremental search, would
normally yank into the buffer. @kbd{Mouse-2} in the echo area does
the same. @xref{Yanking}.
@kbd{C-w} copies the character or word after point and adds it to
the search string, advancing point over it. (The decision, whether to
copy a character or a word, is heuristic.)
@kbd{C-w} (@code{isearch-yank-word-or-char}) grabs the next
character or word at point, and adds it to the search string. This is
convenient for searching for another occurrence of the text at point.
(The decision, whether to copy a character or a word, is heuristic.)
@kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the
current line into the search string. If point is already at the end
of a line, it grabs the entire next line. If the search is currently
case-insensitive, both @kbd{C-y} and @kbd{C-w} convert the text they
copy to lower case, so that the search remains case-insensitive.
Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) grabs the rest
of the current line, and adds it to the search string. If point is
already at the end of a line, it grabs the entire next line.
If the search is currently case-insensitive, both @kbd{C-w} and
@kbd{M-s C-e} convert the text they copy to lower case, so that the
search remains case-insensitive.
@kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one
character at a time: @kbd{C-M-w} deletes the last character from the
......@@ -293,10 +298,6 @@ after point into the search string is to enter the minibuffer by
@kbd{M-e} and to type @kbd{C-f} at the end of the search string in the
minibuffer.
The character @kbd{M-y} copies text from the kill ring into the
search string. It uses the same text that @kbd{C-y} would yank.
@kbd{Mouse-2} in the echo area does the same. @xref{Yanking}.
@node Isearch Scroll
@subsection Scrolling During Incremental Search
......
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.
2011-03-06 Chong Yidong <cyd@stupidchicken.com>
* package.texi (Packaging, Packaging Basics, Simple Packages)
(Multi-file Packages): Expand and clarify.
(Package Archives): Temporary placeholder node.
* elisp.texi (Top): Update node listing.
* Makefile.in (srcs): Add package.texi.
2011-03-05 Chong Yidong <cyd@stupidchicken.com>
......
......@@ -1399,6 +1399,7 @@ Preparing Lisp code for distribution
* Packaging Basics:: The basic concepts of Emacs Lisp packages.
* Simple Packages:: How to package a single .el file.
* Multi-file Packages:: How to package multiple files.
* Package Archives:: Maintaining package archives.
Starting Up Emacs
......
......@@ -87,6 +87,7 @@ srcs = \
$(srcdir)/numbers.texi \
$(srcdir)/objects.texi \
$(srcdir)/os.texi \
$(srcdir)/package.texi \
$(srcdir)/positions.texi \
$(srcdir)/processes.texi \
$(srcdir)/searching.texi \
......
......@@ -5,188 +5,232 @@
@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 for Emacs Lisp code to be distributed
to users. This approach lets users easily download, install,
uninstall, and upgrade Lisp code that they might want to use.
Emacs provides a standard way to distribute Emacs Lisp code to
users. A @dfn{package} is a collection of one or more files,
formatted and bundled in such a way that users can easily download,
install, uninstall, and upgrade it.
A @dfn{package} is simply one or more files, formatted and bundled
in a particular way. Typically a package includes primarily Emacs
Lisp code, but it is possible to create other kinds of packages as
well.
The following sections describe how to create a package, and how to
put it in a @dfn{package archive} for others to download.
@menu
* Packaging Basics:: The basic concepts of Emacs Lisp packages.
* Simple Packages:: How to package a single .el file.
* Multi-file Packages:: How to package multiple files.
* Package Archives:: Maintaining package archives.
@end menu
@node Packaging Basics
@section Packaging Basics
@cindex packaging basics
A package has a few attributes:
@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
Emacs Lisp file, while a multi-file package is stored as a tar file
(containing multiple Lisp files, and possibly non-Lisp files such as a
manual).
In ordinary usage, the difference between simple packages and
multi-file packages is relatively unimportant; the Package Menu
interface makes no distinction between them. However, the procedure
for creating them differs, as explained in the following sections.
Each package (whether simple or multi-file) has certain
@dfn{attributes}:
@table @asis
@item Name
A string, the name of the package. This attribute is mandatory. If
it does not exist, the package cannot be installed by the package
manager.
A short word (e.g. @samp{auctex}). This is usually also the symbol
prefix used in the program (@pxref{Coding Conventions}).
@item Version
A version number, which is anything that can be parsed by
@code{version-to-list}. This attribute is mandatory. If it does not
exist, the package cannot be installed by the package manager.
A version number, in a form that the function @code{version-to-list}
understands (e.g. @samp{11.86}). Each release of a package should be
accompanied by an increase in the version number.
@item Brief description
This is shown to the user in the package menu buffer. It is just a
single line. On a terminal with 80 characters per line, there are
only 36 characters available in the package menu mode for showing the
brief description, so it is best to keep it very brief. If no brief
name is given, an empty string is used.
This is shown when the package is listed in the Package Menu. It
should occupy a single line, ideally in 36 characters or less.
@item Long description
This can be a @file{README} file or the like. This is available to
the user before the package is installed, via the package menu. It
should more fully describe the package and its capabilities, so a user
can read it to decide whether he wants to install the package. This
attribute is optional.
This is shown in the buffer created by @kbd{C-h P}
(@code{describe-package}), following the package's brief description
and installation status. It normally spans multiple lines, and should
fully describe the package and its capabilities.
@item Dependencies
This is a list of other packages and their minimal acceptable
versions. This is used both at download time (to make sure all the
needed code is available) and at activation time (to ensure a package
is only activated if all its dependencies have been successfully
activated). This attribute is optional.
@item Manual
A package can optionally include an Info manual.
A list of other packages (possibly including minimal acceptable
version numbers) on which this package depends. The list may be
empty, meaning this package has no dependencies. Otherwise,
installing this package also automatically installs its dependencies;
if any dependency cannot be found, the package cannot be installed.
@end table
Conceptually, a package goes through several state transitions (in
reality some of these transitions are grouped together):
@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
@var{name} is the package's name and @var{version} its version
(e.g. @file{~/.emacs.d/elpa/auctex-11.86/}). We call this the
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}
in the content directory. They are typically used to autoload the
principal user commands defined in the package, but they can also
perform other tasks, such as adding an element to
@code{auto-mode-alist} (@pxref{Auto Major Mode}). During this time,
Emacs will also byte-compile the Lisp files.
After installation, and (by default) each time Emacs is started, the
installed package is @dfn{activated}. During activation, Emacs adds
the package's content directory to @code{load-path}, and evaluates the
autoload definitions in @file{@var{name}-autoloads.el}.
Note that a package typically does @emph{not} autoload every
function and variable defined within it---only the handful of commands
typically called to begin using the package.
@table @asis
@item Download
Fetch the package from somewhere.
@node Simple Packages
@section Simple Packages
@cindex single file package
@cindex simple package
@item Install
Unpack the package, or write a @file{.el} file into the appropriate
install directory. This step also includes extracting autoloads and
byte-compiling the Emacs Lisp code.
A simple package consists of a single Emacs Lisp source file. The
file must conform to the Emacs Lisp library header conventions
(@pxref{Library Headers}). The package's attributes are taken from
the various headers, as illustrated by the following example:
@item Activate
Update @code{load-path} and @code{Info-directory-list} and evaluate
the autoloads, so that the package is ready for the user to use.
@end table
@example
@group
;;; superfrobnicator.el --- Frobnicate and bifurcate flanges
It is best for users if packages do not do too much work at
activation time. The best approach is to have activation consist of
some autoloads and little more.
;; Copyright (C) 2011 Free Software Foundation, Inc.
@end group
@node Simple Packages
@section Simple Packages
@cindex single file packages
;; Author: J. R. Hacker <jrh@@example.com>
;; Version: 1.3
;; Package-Requires: ((flange "1.0"))
;; Keywords: frobnicate
The simplest package consists of a single Emacs Lisp source file.
In this case, all the attributes of the package (@pxref{Packaging
Basics}) are taken from this file.
@dots{}
The package system expects this @file{.el} file to conform to the
Emacs Lisp library header conventions. @xref{Library Headers}.
;;; Commentary:
The name of the package is the same as the base name of the
@file{.el} file, as written in the first comment line. For example,
given the header line:
;; This package provides a minor mode to frobnicate and/or
;; bifurcate any flanges you desire. To activate it, just type
@dots{}
@smallexample
;;; superfrobnicator.el --- frobnicate and bifurcate flanges
@end smallexample
;;;###autoload
(define-minor-mode superfrobnicator-mode
@dots{}
@end example
the package name will be @samp{superfrobnicator}.
The name of the package is the same as the base name of the file, as
written on the first line. Here, it is @samp{superfrobnicator}.
The short description of the package is also taken from the first
line of the file.
The brief description is also taken from the first line. Here, it
is @samp{Frobnicate and bifurcate flanges}.
If the file has a ``Commentary'' header, then it is used as the long
description.
The version number comes from the @samp{Package-Version} header, if
it exists, or from the @samp{Version} header otherwise. One or the
other @emph{must} be present. Here, the version number is 1.3.
The version of the package comes either from the ``Package-Version''
header, if it exists, or from the ``Version'' header. A package is
required to have a version number. Each release of a package must be
accompanied by an increase in the version number.
If the file has a @samp{;;; Commentary:} section, this section is
used as the long description. (When displaying the description, Emacs
omits the @samp{;;; Commentary:} line, as well as the leading comment
characters in the commentary itself.)
If the file has a ``Package-Requires'' header, then that is used as
the package dependencies. Otherwise, the package is assumed not to
have any dependencies.
If the file has a @samp{Package-Requires} header, that is used as
the package dependencies. In the above example, the package depends
on the @samp{flange} package, version 1.0 or higher. @xref{Library
Headers}, for a description of the @samp{Package-Requires} header. If
the header is omitted, the package has no dependencies.
A single-file package cannot have an Info manual.
The file ought to also contain one or more autoload magic comments,
as explained in @ref{Packaging Basics}. In the above example, a magic
comment autoloads @code{superfrobnicator-mode}.
The file will be scanned for autoload cookies at install time.
@xref{Autoload}.
@xref{Package Archives}, for a explanation of how to add a
single-file package to a package archive.
@node Multi-file Packages
@section Multi-file Packages
@cindex multi-file packages
A multi-file package is just a @file{.tar} file. While less
convenient to create than a single-file package, a multi-file package
also offers more features: it can include an Info manual, multiple
Emacs Lisp files, and also other data files needed by a package.
The contents of the @file{.tar} file must all appear beneath a
single directory, named after the package and version. Files can
appear in subdirectories of this top-most directory, but Emacs Lisp
code will only be found (and thus byte-compiled) at the top-most
level. Also, the @file{.tar} file is typically also given this same
name. For example, if you are distributing version 1.3 of the
superfrobnicator, the package file would be named
``superfrobnicator-1.3.tar'' and the contents would all appear in the
directory @file{superfrobnicator-1.3} in that @file{.tar}.
The package must include a @file{-pkg.el} file, named after the
package. In our example above, this file would be called
@file{superfrobnicator-pkg.el}. This file must have a single form in
it, a call to @code{define-package}. The package dependencies and
brief description are taken from this form.
@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
Lisp files, an Info manual, and other file types (such as images).
Prior to installation, a multi-file package is stored in a package
archive as a tar file. The tar file must be named
@file{@var{name}-@var{version}.tar}, where @var{name} is the package
name and @var{version} is the version number. Its contents, once
extracted, must all appear in a directory named
@file{@var{name}-@var{version}}, the @dfn{content directory}
(@pxref{Packaging Basics}). Files may also extract into
subdirectories of the content directory.
One of the files in the content directory must be named
@file{@var{name}-pkg.el}. It must contain a single Lisp form,
consisting of a call to the function @code{define-package}, described
below. This defines the package's version, brief description, and
requirements.
For example, if we distribute version 1.3 of the superfrobnicator as
a multi-file package, the tar file would be
@file{superfrobnicator-1.3.tar}. Its contents would extract into the
directory @file{superfrobnicator-1.3}, and one of these would be the
file @file{superfrobnicator-pkg.el}.
@defun define-package name version &optional docstring requirements
Define a package. @var{name} is the name of the package, a string.
@var{version} is the package's version, a string. It must be in a
form that can be understood by @code{version-to-list}.
@var{docstring} is the short description of the package.
This function defines a package. @var{name} is the package name, a
string. @var{version} is the version, as a string of a form that can
be understood by the function @code{version-to-list}. @var{docstring}
is the brief description.
@var{requirements} is a list of required packages and their versions.
Each element in this list should have the form @code{(@var{dep-name}
@var{dep-version})}, where @var{dep-name} is a symbol whose name is
the dependency's package name, and @var{dep-version} is the
dependency's version (a string).
@end defun
If a @file{README} file exists in the content directory, then it is
used as the long description.
If the content directory contains a file named @file{README}, this
file is used as the long description.
If the package has an Info manual, you should distribute the needed
info files, plus a @file{dir} file made with @command{install-info}.
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}.
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 will be
created at install time. Note that there is no way to control the
order in which files are byte-compiled; your package must be robust
here.
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
control the order in which files are byte-compiled.
The installation process will scan all the @file{.el} files in the
package for autoload cookies. @xref{Autoload}. They are extracted
into a @file{-autoloads.el} file (e.g.,
@file{superfrobnicator-autoloads.el}), so do not include a file of
that name in your package.
Do not include any file named @file{@var{name}-autoloads.el}. This
file is reserved for the package's autoload definitions
(@pxref{Packaging Basics}). It is created automatically when the
package is installed, by searching all the Lisp files in the package
for autoload magic comments.
Any other files in the @file{.tar} file are simply unpacked when the
package is installed. This can be useful if your package needs
auxiliary data files --- e.g., icons or sounds.
Emacs Lisp code installed via the package manager must take special
care to be location-independent. One easy way to do this is to make
references to auxiliary data files relative to @var{load-file-name}.
For example:
If the multi-file package contains auxiliary data files (such as
images), the package's Lisp code can refer to these files via the
variable @code{load-file-name} (@pxref{Loading}). Here is an example:
@smallexample
(defconst superfrobnicator-base (file-name-directory load-file-name))
......@@ -194,3 +238,82 @@ For example:
(defun superfrobnicator-fetch-image (file)
(expand-file-name file superfrobnicator-base))
@end smallexample
@node Package Archives
@section Creating and Maintaining Package Archives
@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}.
......@@ -247,6 +247,15 @@ replaced with Lisp commands `doc-file-to-man' and `doc-file-to-info'.
* Editing Changes in Emacs 24.1
** Search changes
+++
*** C-y in Isearch is now bound to isearch-yank-kill, instead of
isearch-yank-line.
+++
*** M-s C-e in Isearch is now bound to isearch-yank-line.
+++
** There is a new command `count-words-region', which does what you expect.
......
2011-03-06 Stefan Monnier <monnier@iro.umontreal.ca>
* progmodes/gud.el (gdb-script-syntax-propertize-function):
Don't change the syntax of a \n that closes a comment (bug#8169).
2011-03-06 Chong Yidong <cyd@stupidchicken.com>
* emacs-lisp/package-x.el (package-archive-upload-base): Make it a
defcustom.
(package--update-file): Doc fix. Accept relative file names.
(package--archive-contents-from-file): Remove the argument, since
it's necessarily always "archive-contents".
(package-maint-add-news-item): Pass relative file name args to
package--update-file.
(package-upload-buffer-internal): Prompt for a destination if
package-archive-upload-base is invalid. Create the directory if
it does not exist.
(package-upload-buffer, package-upload-file): Doc fix.
2011-03-06 Chong Yidong <cyd@stupidchicken.com>
* isearch.el (isearch-mode-map): Bind C-y to isearch-yank-kill,
and move isearch-yank-line to M-s C-e (Bug#8183).
2011-03-06 Alan Mackenzie <acm@muc.de>
* progmodes/cc-engine.el (c-guess-basic-syntax): Reindent.
(c-guess-basic-syntax): Move CASE 19 to a different place,
correctly to process template-args-cont lines.
2011-03-06 Jay Belanger <jay.p.belanger@gmail.com>
 
* calc/calc-ext.el (calc-init-extensions):
Rename calc-logunits-dblevel and calc-logunits-nplevel to
calc-dblevel and calc-nplevel, respectively.
Add keybindings for calc-spn, calc-midi and calc-freq. Add
autoloads for calcFunc-spn, calcFunc-midi, calcFunc-freq,
calc-spn, calc-midi and calc-freq.