1 @node Packages, Abbrevs, Running, Top
2 @comment node-name, next, previous, up
7 The XEmacs 21 distribution comes only with a very basic set of
8 built-in modes and packages. Most of the packages that were part of
9 the distribution of earlier versions of XEmacs are now available
10 separately. The installer as well as the user can choose which
11 packages to install; the actual installation process is easy.
12 This gives an installer the ability to tailor an XEmacs installation for
13 local needs with safe removal of unnecessary code.
16 * Package Terminology:: Understanding different kinds of packages.
17 * Using Packages:: How to install and use packages.
18 * Building Packages:: Building packages from sources.
21 @node Package Terminology, Using Packages, , Packages
22 @comment node-name, next, previous, up
24 @subsection Package Flavors
26 There are two main flavors of packages.
29 @item Regular Packages
30 @cindex regular packages
31 A regular package is one in which multiple files are involved and one
32 may not in general safely remove any of them.
34 @item Single-File Packages
35 @cindex single-file packages
36 A single-file package is an aggregate collection of thematically
37 related but otherwise independent lisp files. These files are bundled
38 together for download convenience and individual files may be deleted at
39 will without any loss of functionality.
42 @subsection Package Distributions
44 XEmacs Lisp packages are distributed in two ways, depending on the
45 intended use. Binary Packages are for installers and end-users and may
46 be installed directly into an XEmacs package directory. Source Packages
47 are for developers and include all files necessary for rebuilding
48 bytecompiled lisp and creating tarballs for distribution.
50 @subsection Binary Packages
51 @cindex binary packages
52 Binary packages may be installed directly into an XEmacs package
55 @subsection Source Packages
56 @cindex source packages
57 Source packages contain all of the Package author's (where appropriate
58 in regular packages) source code plus all of the files necessary to
59 build distribution tarballs (Unix Tar format files, gzipped for space
62 @node Using Packages, Building Packages, Package Terminology, Packages
63 @comment node-name, next, previous, up
65 @subsection Getting Started
67 When you first download XEmacs 21, you will usually first grab the
68 @dfn{core distribution},
69 @cindex core distribution
71 @file{xemacs-21.0.tar.gz}. (Replace the @t{21.0} by the current version
72 number.) The core distribution contains the sources of XEmacs and a
73 minimal set of Emacs Lisp files, which are in the subdirectory named
74 @file{lisp}. This subdirectory used to contain all Emacs Lisp files
75 distributed with XEmacs. Now, to conserve disk space, most
76 non-essential packages were made optional.
78 @subsection Choosing the Packages You Need
80 The available packages can currently be found in the same ftp directory
81 where you grabbed the core distribution from, and are located in the
82 subdirectory @file{packages/binary-packages}. Package file names follow
83 the naming convention @file{<package-name>-<version>-pkg.tar.gz}.
85 If you have EFS @ref{(EFS)}, packages can be installed over the network.
86 Alternatively, if you have copies of the packages locally, you can
87 install packages from a local disk or CDROM.
89 The file @file{etc/PACKAGES} in the core distribution contains a list of
90 the packages available at the time of the XEmacs release. Packages are
91 also listed on the @code{Options} menu under:
94 Options->Customize->Emacs->Packages
97 However, don't select any of these menu picks unless you actually want
98 to install the given package (and have properly configured your system
101 You can also get a list of available packages, and whether or not they
102 are installed, using the visual package browser and installer. You can
103 access it via the menus:
106 Options->Manage Packages->List & Install
109 Or, you can get to it via the keyboard:
112 M-x pui-list-packages
115 Hint to system administrators of multi-user systems: it might be a good
116 idea to install all packages and not interfere with the wishes of your
119 If you can't find which package provides the feature you require, try
120 using the @code{package-get-package-provider} function. Eg., if you know
121 that you need @code{thingatpt}, type:
124 M-x package-get-package-provider RET thingatpt
127 which will return something like (fsf-compat "1.06"). You can the use
128 one of the methods above for installing the package you want.
130 @subsection XEmacs and Installing Packages
132 Normally, packages are installed over the network, using EFS
133 @ref{(EFS)}. However, you may not have network access, or you may
134 already have some or all of the packages on a local disk, such as a
135 CDROM. If you want to install from a local disk, you must first tell
136 XEmacs where to find the package binaries. This is done by adding a line
137 like the following to your @file{.emacs} file:
140 (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
144 Here, you'd change @file{/my/path/to/package/binaries} to be the path
145 to your local package binaries. Next, restart XEmacs, and you're ready
146 to go (advanced users can just re-evaluate the sexp).
148 If you are installing from a temporary, one-time directory, you can also
149 add these directory names to @code{package-get-remote} using:
152 M-x pui-add-install-directory
155 Note, however, that any directories added using this function are not
156 saved; this information will be lost when you quit XEmacs.
158 If you're going to install over the network, you only have to insure
159 that EFS @ref{(EFS)} works, and that it can get outside a firewall, if
160 you happen to be behind one. You shouldn't have to do anything else;
161 XEmacs already knows where to go. However you can add your own mirrors
162 to this list. See @code{package-get-remote}.
164 The easiest way to install a package is to use the visual package
165 browser and installer, using the menu pick:
168 Options->Manage Packages->List & Install
172 Options->Manage Packages->Using Custom->Select-> ...
175 You can also access it using the keyboard:
178 M-x pui-list-packages
181 The visual package browser will then display a list of all packages.
182 Help information will be displayed at the very bottom of the buffer; you
183 may have to scroll down to see it. You can also press @kbd{?} to get
184 the same help. From this buffer, you can tell the package status by the
185 character in the first column:
189 The package has not been installed.
191 The package has been installed, but a newer version is available. The
192 current version is out-of-date.
194 The package has been marked for installation/update.
197 If there is no character in the first column, the package has been
198 installed and is up-to-date.
200 From here, you can select or unselect packages for installation using
201 the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from
203 Once you've finished selecting the packages, you can
204 press the @kbd{x} key (or use the menu) to actually install the
205 packages. Note that you will have to restart XEmacs for XEmacs to
206 recognize any new packages.
215 Toggle between selecting and unselecting a package for installation.
217 Install selected packages.
219 View, in the minibuffer, additional information about the package, such
220 as the package date (not the build date) and the package author. Moving
221 the mouse over a package name will also do the same thing.
223 Toggle between verbose and non-verbose package display.
225 Refresh the package display.
227 Kill the package buffer.
230 Moving the mouse over a package will also cause additional information
231 about the package to be displayed in the minibuffer.
233 @subsection Other package installation interfaces
235 For an alternative package interface, you can select packages from the
236 customize menus, under:
239 Options->Customize->Emacs->Packages-> ...
243 Options->Manage Packages->Using Custom->Select-> ...
246 Set their state to on, and then do:
249 Options->Manage Packages->Using Custom->Update Packages
252 This will automatically retrieve the packages you have selected from the
253 XEmacs ftp site or your local disk, and install them into
254 XEmacs. Additionally it will update any packages you already have
255 installed to the newest version. Note that if a package is newly
256 installed you will have to restart XEmacs for the change to take effect.
258 You can also install packages using a semi-manual interface:
261 M-x package-get-all <return>
264 Enter the name of the package (e.g., @code{prog-modes}), and XEmacs
265 will search for the latest version (as listed in the lisp file
266 @file{lisp/package-get-base.el}), and install it and any packages that
269 @subsection Manual Binary Package Installation
271 Pre-compiled, binary packages can be installed in either a system
272 package directory (this is determined when XEmacs is compiled), or in
274 subdirectories of your @file{$HOME} directory:
277 ~/.xemacs/mule-packages
278 ~/.xemacs/xemacs-packages
281 Packages in the former directory will only be found by a Mule-enabled
284 XEmacs does not have to be running to install binary packages, although
285 XEmacs will not know about any newly-installed packages until you
286 restart XEmacs. Note, however, that installing a newer version of a
287 package while XEmacs is running could cause strange errors in XEmacs;
288 it's best to exit XEmacs before upgrading an existing package.
290 To install binary packages manually:
294 Download the package(s) that you want to install. Each binary package
295 will typically be a gzip'd tarball.
298 Decide where to install the packages: in the system package
299 directory, or in @file{~/.xemacs/mule-packages} or
300 @file{~/.xemacs/xemacs-packages}, respectively. If you want to install
301 the packages in the system package directory, make sure you can write
302 into that directory. If you want to install in your @file{$HOME}
303 directory, create the directory, @file{~/.xemacs/mule-packages} or
304 @file{~/.xemacs/xemacs-packages}, respectively.
307 Next, @code{cd} to the directory under which you want to install the
311 From this directory, uncompress and extract each of the gzip'd tarballs
312 that you downloaded in step 1. Unix and Cygnus cygwin users will
313 typically do this using the commands:
316 gunzip < package.tar.gz | tar xvf -
319 Above, replace @file{package.tar.gz} with the filename of the
320 package that you downloaded in step 1.
322 Of course, if you use GNU @code{tar}, you could also use:
325 tar xvzf package.tar.gz
328 @comment What about native MS Windows users???
331 That's it. Quit and restart XEmacs to get it to recognize any new or
336 @node Building Packages, , Using Packages, Packages
337 @comment node-name, next, previous, up
339 Source packages are available from the @file{packages/source-packages}
340 subdirectory of your favorite XEmacs distribution site. Alternatively,
341 they are available via CVS from @file{cvs.xemacs.org}. Look at
342 @file{http://cvs.xemacs.org} for instructions.
344 @subsection Prerequisites for Building Source Packages
346 You must have GNU @code{cp}, GNU @code{install} (or a BSD compatible
347 @code{install} program) GNU @code{make} (3.75 or later preferred),
348 @code{makeinfo} (1.68 from @code{texinfo-3.11} or later required), GNU
349 @code{tar} and XEmacs 21.0. The source packages will untar into a
350 correct directory structure. At the top level you must have
351 @file{XEmacs.rules} and @file{package-compile.el}. These files are
352 available from the XEmacs FTP site from the same place you obtained your
353 source package distributions.
355 @subsection What You Can Do With Source Packages
357 NB: A global build operation doesn't exist yet as of 13 January 1998.
359 Source packages are most useful for creating XEmacs package tarballs
360 for installation into your own XEmacs installations or for
361 distributing to others.
363 Supported operations from @file{make} are:
367 Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
370 Remove XEmacs backups as well as the files deleted by @code{make clean}.
373 Bytecompile all files, build and bytecompile byproduct files like
374 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
375 of TeXinfo documentation if present.
378 Usually aliased to @code{make srckit-std}. This does a @code{make
379 distclean} and creates a package source tarball in the staging
380 directory. This is generally only of use for package maintainers.
383 May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
384 @code{binkit-sourcedata}, or
385 @code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
386 nothing to install in a data directory or info directory.
387 @code{sourceinfo} indicates that source and info files are to be
388 installed. @code{sourcedata} indicates that source and etc (data) files
389 are to be installed. @code{sourcedatainfo} indicates source, etc
390 (data), and info files are to be installed. A few packages have needs
391 beyond the basic templates so this is not yet complete.
394 Runs the rules @code{srckit} followed by @code{binkit}. This is
395 primarily of use by XEmacs maintainers producing files for distribution.