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 init file:
140 (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
146 Here, you'd change @file{/my/path/to/package/binaries} to be the path
147 to your local package binaries. Next, restart XEmacs, and you're ready
148 to go (advanced users can just re-evaluate the sexp).
150 If you are installing from a temporary, one-time directory, you can also
151 add these directory names to @code{package-get-remote} using:
154 M-x pui-add-install-directory
157 Note, however, that any directories added using this function are not
158 saved; this information will be lost when you quit XEmacs.
160 If you're going to install over the network, you only have to insure
161 that EFS @ref{(EFS)} works, and that it can get outside a firewall, if
162 you happen to be behind one. You shouldn't have to do anything else;
163 XEmacs already knows where to go. However you can add your own mirrors
164 to this list. See @code{package-get-remote}.
166 The easiest way to install a package is to use the visual package
167 browser and installer, using the menu pick:
170 Options->Manage Packages->List & Install
174 Options->Manage Packages->Using Custom->Select-> ...
177 You can also access it using the keyboard:
180 M-x pui-list-packages
183 The visual package browser will then display a list of all packages.
184 Help information will be displayed at the very bottom of the buffer; you
185 may have to scroll down to see it. You can also press @kbd{?} to get
186 the same help. From this buffer, you can tell the package status by the
187 character in the first column:
191 The package has not been installed.
193 The package has been installed, but a newer version is available. The
194 current version is out-of-date.
196 The package has been marked for installation/update.
199 If there is no character in the first column, the package has been
200 installed and is up-to-date.
202 From here, you can select or unselect packages for installation using
203 the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from
205 Once you've finished selecting the packages, you can
206 press the @kbd{x} key (or use the menu) to actually install the
207 packages. Note that you will have to restart XEmacs for XEmacs to
208 recognize any new packages.
217 Toggle between selecting and unselecting a package for installation.
219 Install selected packages.
221 View, in the minibuffer, additional information about the package, such
222 as the package date (not the build date) and the package author. Moving
223 the mouse over a package name will also do the same thing.
225 Toggle between verbose and non-verbose package display.
227 Refresh the package display.
229 Kill the package buffer.
232 Moving the mouse over a package will also cause additional information
233 about the package to be displayed in the minibuffer.
235 @subsection Other package installation interfaces
237 For an alternative package interface, you can select packages from the
238 customize menus, under:
241 Options->Customize->Emacs->Packages-> ...
245 Options->Manage Packages->Using Custom->Select-> ...
248 Set their state to on, and then do:
251 Options->Manage Packages->Using Custom->Update Packages
254 This will automatically retrieve the packages you have selected from the
255 XEmacs ftp site or your local disk, and install them into
256 XEmacs. Additionally it will update any packages you already have
257 installed to the newest version. Note that if a package is newly
258 installed you will have to restart XEmacs for the change to take effect.
260 You can also install packages using a semi-manual interface:
263 M-x package-get-all <return>
266 Enter the name of the package (e.g., @code{prog-modes}), and XEmacs
267 will search for the latest version (as listed in the lisp file
268 @file{lisp/package-get-base.el}), and install it and any packages that
271 @subsection Manual Binary Package Installation
273 Pre-compiled, binary packages can be installed in either a system
274 package directory (this is determined when XEmacs is compiled), or in
276 subdirectories of your @file{$HOME} directory:
279 ~/.xemacs/mule-packages
280 ~/.xemacs/xemacs-packages
283 Packages in the former directory will only be found by a Mule-enabled
286 XEmacs does not have to be running to install binary packages, although
287 XEmacs will not know about any newly-installed packages until you
288 restart XEmacs. Note, however, that installing a newer version of a
289 package while XEmacs is running could cause strange errors in XEmacs;
290 it's best to exit XEmacs before upgrading an existing package.
292 To install binary packages manually:
296 Download the package(s) that you want to install. Each binary package
297 will typically be a gzip'd tarball.
300 Decide where to install the packages: in the system package
301 directory, or in @file{~/.xemacs/mule-packages} or
302 @file{~/.xemacs/xemacs-packages}, respectively. If you want to install
303 the packages in the system package directory, make sure you can write
304 into that directory. If you want to install in your @file{$HOME}
305 directory, create the directory, @file{~/.xemacs/mule-packages} or
306 @file{~/.xemacs/xemacs-packages}, respectively.
309 Next, @code{cd} to the directory under which you want to install the
313 From this directory, uncompress and extract each of the gzip'd tarballs
314 that you downloaded in step 1. Unix and Cygnus cygwin users will
315 typically do this using the commands:
318 gunzip < package.tar.gz | tar xvf -
321 Above, replace @file{package.tar.gz} with the filename of the
322 package that you downloaded in step 1.
324 Of course, if you use GNU @code{tar}, you could also use:
327 tar xvzf package.tar.gz
330 @comment What about native MS Windows users???
333 That's it. Quit and restart XEmacs to get it to recognize any new or
338 @node Building Packages, , Using Packages, Packages
339 @comment node-name, next, previous, up
341 Source packages are available from the @file{packages/source-packages}
342 subdirectory of your favorite XEmacs distribution site. Alternatively,
343 they are available via CVS from @file{cvs.xemacs.org}. Look at
344 @file{http://cvs.xemacs.org} for instructions.
346 @subsection Prerequisites for Building Source Packages
348 You must have GNU @code{cp}, GNU @code{install} (or a BSD compatible
349 @code{install} program) GNU @code{make} (3.75 or later preferred),
350 @code{makeinfo} (1.68 from @code{texinfo-3.11} or later required), GNU
351 @code{tar} and XEmacs 21.0. The source packages will untar into a
352 correct directory structure. At the top level you must have
353 @file{XEmacs.rules} and @file{package-compile.el}. These files are
354 available from the XEmacs FTP site from the same place you obtained your
355 source package distributions.
357 @subsection What You Can Do With Source Packages
359 NB: A global build operation doesn't exist yet as of 13 January 1998.
361 Source packages are most useful for creating XEmacs package tarballs
362 for installation into your own XEmacs installations or for
363 distributing to others.
365 Supported operations from @file{make} are:
369 Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
372 Remove XEmacs backups as well as the files deleted by @code{make clean}.
375 Bytecompile all files, build and bytecompile byproduct files like
376 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
377 of TeXinfo documentation if present.
380 Usually aliased to @code{make srckit-std}. This does a @code{make
381 distclean} and creates a package source tarball in the staging
382 directory. This is generally only of use for package maintainers.
385 May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
386 @code{binkit-sourcedata}, or
387 @code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
388 nothing to install in a data directory or info directory.
389 @code{sourceinfo} indicates that source and info files are to be
390 installed. @code{sourcedata} indicates that source and etc (data) files
391 are to be installed. @code{sourcedatainfo} indicates source, etc
392 (data), and info files are to be installed. A few packages have needs
393 beyond the basic templates so this is not yet complete.
396 Runs the rules @code{srckit} followed by @code{binkit}. This is
397 primarily of use by XEmacs maintainers producing files for distribution.