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 separately
10 available. 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 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 and 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 distribition 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->Customize->List Packages
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 @subsection XEmacs and Installing Packages
121 Normally, packages are installed over the network, using EFS
122 @ref{(EFS)}. However, you may not have network access, or you may
123 already have some or all of the packages on a local disk, such as a
124 CDROM. If you want to install from a local disk, you must first tell
125 XEmacs where to find the package binaries. This is done by adding a line
126 like the following to your @file{.emacs} file:
129 (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
133 Here, you'd change @file{/my/path/to/package/binaries} to be the path
134 to your local package binaries. Next, restart XEmacs, and you're ready
135 to go (advanced users can just re-evaluate the sexp).
137 If you are installing from a temporary, one-time directory, you can also
138 add these directory names to @code{package-get-remote} using:
141 M-x pui-add-install-directory
144 Note, however, that any directories added using this function are not
145 saved; this information will be lost when you quit XEmacs.
147 If you're going to install over the network, you only have to insure
148 that EFS @ref{(EFS)} works, and that it can get outside a firewall, if
149 you happen to be behind one. You shouldn't have to do anything else;
150 XEmacs already knows where to go.
152 The easiest way to install a package is to use the visual package
153 browser and installer, using the menu pick:
156 Options->Customize->List Packages
159 You can also access it using the keyboard:
162 M-x pui-list-packages
165 The visual package browser will then display a list of all packages.
166 Help information will be displayed at the very bottom of the buffer; you
167 may have to scroll down to see it. You can also press @kbd{?} to get
168 the same help. From this buffer, you can tell the package status by the
169 character in the first column:
173 The package has not been installed.
175 The package has been installed, but a newer version is available. The
176 current version is out-of-date.
178 The package has been marked for installation/update.
181 If there is no character in the first column, the package has been
182 installed and is up-to-date.
184 From here, you can select or unselect packages for installation using
185 the @key{RET} key, or using the @kbd{Mouse-2} or @kbd{Mouse-3} buttons.
186 Once you've finished selecting the packages, you can press the @kbd{x}
187 key to actually install the packages. Note that you will have to
188 restart XEmacs for XEmacs to recognize any new packages.
198 Toggle between selecting and unselecting a package for installation.
200 Install selected packages.
202 View, in the minibuffer, additional information about the package, such
203 as the package date (not the build date) and the package author. Moving
204 the mouse over a package name will also do the same thing.
206 Toggle between verbose and non-verbose package display.
208 Refresh the package display.
210 Kill the package buffer.
213 Moving the mouse over a package will also cause additional information
214 about the package to be displayed in the minibuffer.
216 @subsection Other package installation interfaces
218 For an alternative package interface, you can select packages from the
219 customize menus, under:
222 Options->Customize->Emacs->Packages-> ...
225 Set their state to on, and then do:
228 Options->Customize->Update Packages
231 This will automatically retrieve the packages you have selected from the
232 XEmacs ftp site or your local disk, and install them into
233 XEmacs. Additionally it will update any packages you already have
234 installed to the newest version. Note that if a package is newly
235 installed you will have to restart XEmacs for the change to take effect.
237 You can also install packages using a semi-manual interface:
240 M-x package-get-all <return>
243 Enter the name of the package (e.g., @code{prog-modes}), and XEmacs
244 will search for the latest version (as listed in the lisp file
245 @file{lisp/package-get-base.el}), and install it and any packages that
248 @subsection Manual Binary Package Installation
250 Pre-compiled, binary packages can be installed in either a system
251 package directory (this is determined when XEmacs is compiled), or in a
252 subdirectory off your @file{$HOME} directory:
258 XEmacs does not have to be running to install binary packages, although
259 XEmacs will not know about any newly-installed packages until you
260 restart XEmacs. Note, however, that installing a newer version of a
261 package while XEmacs is running could cause strange errors in XEmacs;
262 it's best to exit XEmacs before upgrading an existing package.
264 To install binary packages manually:
268 Download the package(s) that you want to install. Each binary package
269 will typically be a gzip'd tarball.
272 Decide where to install the packages: in the system package directory,
273 or in @file{~/.xemacs/packages}. If you want to install the
274 packages in the system package directory, make sure you can write into
275 that directory. If you want to install in your @file{$HOME} directory,
276 create the directory, @file{~/.xemacs/packages}.
279 Next, @code{cd} to the directory under which you want to install the
283 From this directory, uncompress and extract each of the gzip'd tarballs
284 that you downloaded in step 1. Unix and Cygnus cygwin users will
285 typically do this using the commands:
288 gunzip < package.tar.gz | tar xvf -
291 Above, replace @file{package.tar.gz} with the filename of the
292 package that you downloaded in step 1.
294 Of course, if you use GNU @code{tar}, you could also use:
297 tar xvzf package.tar.gz
300 @comment What about native MS Windows users???
303 That's it. Quit and restart XEmacs to get it to recognize any new or
308 @node Building Packages, , Using Packages, Packages
309 @comment node-name, next, previous, up
311 Source packages are available from the @file{packages/source-packages}
312 subdirectory of your favorite XEmacs distribution site. Alternatively,
313 they are available via CVS from @file{cvs.xemacs.org}. Look at
314 @file{http://cvs.xemacs.org} for instructions.
316 @subsection Prerequisites for Building Source Packages
318 You must have GNU @code{cp}, GNU @code{install} (or a BSD compatible
319 @code{install} program) GNU @code{make} (3.75 or later preferred),
320 @code{makeinfo} (1.68 from @code{texinfo-3.11} or later required), GNU
321 @code{tar} and XEmacs 21.0. The source packages will untar into a
322 correct directory structure. At the top level you must have
323 @file{XEmacs.rules} and @file{package-compile.el}. These files are
324 available from the XEmacs FTP site from the same place you obtained your
325 source package distributions.
327 @subsection What You Can Do With Source Packages
329 NB: A global build operation doesn't exist yet as of 13 January 1998.
331 Source packages are most useful for creating XEmacs package tarballs
332 for installation into your own XEmacs installations or for
333 distributing to others.
335 Supported operations from @file{make} are:
339 Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
342 Remove XEmacs backups as well as the files deleted by @code{make clean}.
345 Bytecompile all files, build and bytecompile byproduct files like
346 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
347 of TeXinfo documentation if present.
350 Usually aliased to @code{make srckit-std}. This does a @code{make
351 distclean} and creates a package source tarball in the staging
352 directory. This is generally only of use for package maintainers.
355 May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
356 @code{binkit-sourcedata}, or
357 @code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
358 nothing to install in a data directory or info directory.
359 @code{sourceinfo} indicates that source and info files are to be
360 installed. @code{sourcedata} indicates that source and etc (data) files
361 are to be installed. @code{sourcedatainfo} indicates source, etc
362 (data), and info files are to be installed. A few packages have needs
363 beyond the basic templates so this is not yet complete.
366 Runs the rules @code{srckit} followed by @code{binkit}. This is
367 primarily of use by XEmacs maintainers producing files for distribution.