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 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 @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. However you can add your own mirrors
151 to this list. See @code{package-get-remote}.
153 The easiest way to install a package is to use the visual package
154 browser and installer, using the menu pick:
157 Options->Manage Packages->List & Install
161 Options->Manage Packages->Using Custom->Select-> ...
164 You can also access it using the keyboard:
167 M-x pui-list-packages
170 The visual package browser will then display a list of all packages.
171 Help information will be displayed at the very bottom of the buffer; you
172 may have to scroll down to see it. You can also press @kbd{?} to get
173 the same help. From this buffer, you can tell the package status by the
174 character in the first column:
178 The package has not been installed.
180 The package has been installed, but a newer version is available. The
181 current version is out-of-date.
183 The package has been marked for installation/update.
186 If there is no character in the first column, the package has been
187 installed and is up-to-date.
189 From here, you can select or unselect packages for installation using
190 the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from
192 Once you've finished selecting the packages, you can
193 press the @kbd{x} key (or use the menu) to actually install the
194 packages. Note that you will have to restart XEmacs for XEmacs to
195 recognize any new packages.
204 Toggle between selecting and unselecting a package for installation.
206 Install selected packages.
208 View, in the minibuffer, additional information about the package, such
209 as the package date (not the build date) and the package author. Moving
210 the mouse over a package name will also do the same thing.
212 Toggle between verbose and non-verbose package display.
214 Refresh the package display.
216 Kill the package buffer.
219 Moving the mouse over a package will also cause additional information
220 about the package to be displayed in the minibuffer.
222 @subsection Other package installation interfaces
224 For an alternative package interface, you can select packages from the
225 customize menus, under:
228 Options->Customize->Emacs->Packages-> ...
232 Options->Manage Packages->Using Custom->Select-> ...
235 Set their state to on, and then do:
238 Options->Manage Packages->Using Custom->Update Packages
241 This will automatically retrieve the packages you have selected from the
242 XEmacs ftp site or your local disk, and install them into
243 XEmacs. Additionally it will update any packages you already have
244 installed to the newest version. Note that if a package is newly
245 installed you will have to restart XEmacs for the change to take effect.
247 You can also install packages using a semi-manual interface:
250 M-x package-get-all <return>
253 Enter the name of the package (e.g., @code{prog-modes}), and XEmacs
254 will search for the latest version (as listed in the lisp file
255 @file{lisp/package-get-base.el}), and install it and any packages that
258 @subsection Manual Binary Package Installation
260 Pre-compiled, binary packages can be installed in either a system
261 package directory (this is determined when XEmacs is compiled), or in
263 subdirectories of your @file{$HOME} directory:
266 ~/.xemacs/mule-packages
267 ~/.xemacs/xemacs-packages
270 Packages in the former directory will only be found by a Mule-enabled
273 XEmacs does not have to be running to install binary packages, although
274 XEmacs will not know about any newly-installed packages until you
275 restart XEmacs. Note, however, that installing a newer version of a
276 package while XEmacs is running could cause strange errors in XEmacs;
277 it's best to exit XEmacs before upgrading an existing package.
279 To install binary packages manually:
283 Download the package(s) that you want to install. Each binary package
284 will typically be a gzip'd tarball.
286 @item Decide where to install the packages: in the system package
287 directory, or in @file{~/.xemacs/mule-packages} or
288 @file{~/.xemacs/xemacs-packages}, respectively. If you want to install
289 the packages in the system package directory, make sure you can write
290 into that directory. If you want to install in your @file{$HOME}
291 directory, create the directory, @file{~/.xemacs/mule-packages} or
292 @file{~/.xemacs/xemacs-packages}, respectively.
295 Next, @code{cd} to the directory under which you want to install the
299 From this directory, uncompress and extract each of the gzip'd tarballs
300 that you downloaded in step 1. Unix and Cygnus cygwin users will
301 typically do this using the commands:
304 gunzip < package.tar.gz | tar xvf -
307 Above, replace @file{package.tar.gz} with the filename of the
308 package that you downloaded in step 1.
310 Of course, if you use GNU @code{tar}, you could also use:
313 tar xvzf package.tar.gz
316 @comment What about native MS Windows users???
319 That's it. Quit and restart XEmacs to get it to recognize any new or
324 @node Building Packages, , Using Packages, Packages
325 @comment node-name, next, previous, up
327 Source packages are available from the @file{packages/source-packages}
328 subdirectory of your favorite XEmacs distribution site. Alternatively,
329 they are available via CVS from @file{cvs.xemacs.org}. Look at
330 @file{http://cvs.xemacs.org} for instructions.
332 @subsection Prerequisites for Building Source Packages
334 You must have GNU @code{cp}, GNU @code{install} (or a BSD compatible
335 @code{install} program) GNU @code{make} (3.75 or later preferred),
336 @code{makeinfo} (1.68 from @code{texinfo-3.11} or later required), GNU
337 @code{tar} and XEmacs 21.0. The source packages will untar into a
338 correct directory structure. At the top level you must have
339 @file{XEmacs.rules} and @file{package-compile.el}. These files are
340 available from the XEmacs FTP site from the same place you obtained your
341 source package distributions.
343 @subsection What You Can Do With Source Packages
345 NB: A global build operation doesn't exist yet as of 13 January 1998.
347 Source packages are most useful for creating XEmacs package tarballs
348 for installation into your own XEmacs installations or for
349 distributing to others.
351 Supported operations from @file{make} are:
355 Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
358 Remove XEmacs backups as well as the files deleted by @code{make clean}.
361 Bytecompile all files, build and bytecompile byproduct files like
362 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
363 of TeXinfo documentation if present.
366 Usually aliased to @code{make srckit-std}. This does a @code{make
367 distclean} and creates a package source tarball in the staging
368 directory. This is generally only of use for package maintainers.
371 May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
372 @code{binkit-sourcedata}, or
373 @code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
374 nothing to install in a data directory or info directory.
375 @code{sourceinfo} indicates that source and info files are to be
376 installed. @code{sourcedata} indicates that source and etc (data) files
377 are to be installed. @code{sourcedatainfo} indicates source, etc
378 (data), and info files are to be installed. A few packages have needs
379 beyond the basic templates so this is not yet complete.
382 Runs the rules @code{srckit} followed by @code{binkit}. This is
383 primarily of use by XEmacs maintainers producing files for distribution.