456
+ − 1 -*- Outline -*-
+ − 2 This file is in Outline mode. It is best viewed under XEmacs.
+ − 3
+ − 4 Press C-c C-o (Ctrl+c Ctrl+o) now to see a list of headings.
+ − 5 To expand a heading: Put the cursor on the heading and press C-c C-s
+ − 6 To collapse a heading: Press C-c C-d
+ − 7
+ − 8 For general XEmacs navigation tips: Press C-h t
+ − 9
331
+ − 10 The XEmacs Packages Quick Start Guide
+ − 11 -------------------------------------
+ − 12
826
+ − 13 This text is intended to help you get started installing a new XEmacs and
+ − 14 its packages. For more details see the 'Startup Paths' and 'Packages'
+ − 15 sections of the XEmacs info manual.
331
+ − 16
456
+ − 17 * Real Real Quickstart FAQ
+ − 18 --------------------------
331
+ − 19
+ − 20 Q. Do I need to have the packages to compile XEmacs?
826
+ − 21
+ − 22 A. Theoretically, no -- XEmacs will build and install just fine without any
+ − 23 packages installed. However, only the most basic editing functions will
+ − 24 be available with no packages installed, so installing packages is an
438
+ − 25 essential part of making your installed XEmacs _useful_.
331
+ − 26
+ − 27 Q. I really liked the old way that packages were bundled and do not
+ − 28 want to mess with packages at all.
826
+ − 29
331
+ − 30 A. You can grab all the packages at once like you used to with old
+ − 31 XEmacs versions, skip to the 'Sumo Tarball' section below.
+ − 32
826
+ − 33 Q. How do I tell XEmacs where to find the packages?
+ − 34
+ − 35 A. Normally, you put the packages under $prefix/lib/packages, where
+ − 36 $prefix is specified using the `--prefix' parameter to `configure'.
+ − 37 (See `Package hierarchies' below). However, if you have the packages
+ − 38 somewhere else (e.g. you're a developer and are compiling the packages
+ − 39 yourself, and want your own private copy of everything), use the
+ − 40 `--package-path' parameter, something like this:
+ − 41
+ − 42 configure --package-path="~/.xemacs::/src/xemacs/site-packages:/src/xemacs/xemacs-packages:/src/xemacs/mule-packages" ...
+ − 43
444
+ − 44 Q. After installing, I want XEmacs to do `foo', but when I invoke it
+ − 45 (or click the toolbar button or select the menu item), nothing (or
+ − 46 an error) happens, and it used to work.
826
+ − 47
444
+ − 48 A. See the first FAQ; you may be missing a package that is essential to
+ − 49 you. You can either track it down and install it, or install the
+ − 50 `Sumo Tarball' (see the second FAQ).
+ − 51
456
+ − 52 * A note of caution
+ − 53 -------------------
331
+ − 54
438
+ − 55 The XEmacs package system is still in its infancy. Please expect a few
+ − 56 minor hurdles on the way. Also neither the interface nor the structure is
331
+ − 57 set in stone. The XEmacs maintainers reserve the right to sacrifice
+ − 58 backwards compatibility as quirks are worked out over the coming
438
+ − 59 releases.
331
+ − 60
826
+ − 61 * Some package theory
456
+ − 62 ---------------------
331
+ − 63
+ − 64 In order to reduce the size and increase the maintainability of XEmacs,
+ − 65 the majority of the Elisp packages that came with previous releases
+ − 66 have been unbundled. They have been replaced by the package system.
+ − 67 Each elisp add-on (or groups of them when they are small) now comes
+ − 68 in its own tarball that contains a small search hierarchy.
+ − 69
438
+ − 70 You select just the ones you need. Install them by untarring them into
331
+ − 71 the right place. On startup XEmacs will find them, set up the load
+ − 72 path correctly, install autoloads, etc, etc.
+ − 73
456
+ − 74 * Package hierarchies
+ − 75 ---------------------
331
+ − 76
826
+ − 77 On Startup XEmacs looks for packages in so-called package hierarchies.
+ − 78 Normally, there are three system wide hierarchies, like this:
331
+ − 79
826
+ − 80 $prefix/lib/xemacs/xemacs-packages/
331
+ − 81 Normal packages go here.
+ − 82
826
+ − 83 $prefix/lib/xemacs/mule-packages/
456
+ − 84 Mule packages go here and are only searched by MULE-enabled XEmacsen.
+ − 85
+ − 86 $prefix/lib/xemacs/site-packages/
+ − 87 Local and 3rd party packages go here.
+ − 88
826
+ − 89 This is what you get when you untar the SUMO tarballs under
+ − 90 $prefix/lib/xemacs.
+ − 91
+ − 92 $prefix is specified using the `--prefix' parameter to `configure', and
+ − 93 defaults to `usr/local'.
+ − 94
+ − 95 If your packages are located in the above directories, XEmacs will
+ − 96 automatically find them at startup; however, if you have your packages
+ − 97 somewhere else (e.g. you're a developer and are compiling the packages
+ − 98 yourself, and want your own private copy of everything), you can tell
+ − 99 XEmacs specifically where to look for the packages by using the
+ − 100 `--package-path' parameter to the 'configure' script. Normally, it looks
+ − 101 like this:
+ − 102
+ − 103 configure --package-path="~/.xemacs::/src/xemacs/site-packages:/src/xemacs/xemacs-packages:/src/xemacs/mule-packages" ...
+ − 104
+ − 105 See `configure.usage' for more info about the format of this parameter.
456
+ − 106
+ − 107 * Where to get the packages
+ − 108 ---------------------------
331
+ − 109
+ − 110 Packages are available from ftp://ftp.xemacs.org/pub/xemacs/packages
438
+ − 111 and its mirrors.
331
+ − 112
456
+ − 113 * How to install the packages
+ − 114 -----------------------------
+ − 115 There are a few different ways to install packages:
331
+ − 116
1648
+ − 117 1. Automatically, using the package tools from XEmacs.
456
+ − 118 2. Manually, using individual package tarballs.
1648
+ − 119 3. Manually, all at once, using the 'Sumo Tarball'.
331
+ − 120
1648
+ − 121 ** Automatically, using the package tools from XEmacs
+ − 122 -----------------------------------------------------
+ − 123
+ − 124 XEmacs comes with some tools to make the periodic updating and
+ − 125 installing easier. It will notice if new packages or versions are
+ − 126 available and will fetch them from the FTP site.
331
+ − 127
1648
+ − 128 Unfortunately this requires that a few packages are already in place.
+ − 129 You will have to install them by hand as above or use a SUMO tarball.
+ − 130 This requirement will hopefully go away in the future. The packages
+ − 131 you need are:
+ − 132
+ − 133 efs - To fetch the files from the FTP site or mirrors.
+ − 134 xemacs-base - Needed by efs.
+ − 135
+ − 136 and optionally:
331
+ − 137
1648
+ − 138 mailcrypt - For PGP verification of the package-index file.
+ − 139
+ − 140 After installing these by hand, fire up XEmacs and follow these
+ − 141 steps.
331
+ − 142
1648
+ − 143 (1) Choose a download site.
+ − 144 - via menu: Tools -> Packages -> Set Download Site
+ − 145 - via keyb: M-x customize-variable RET package-get-remote RET
+ − 146 (put in the details of remote host and directory)
331
+ − 147
1648
+ − 148 If the package tarballs _AND_ the package-index file are in a
+ − 149 local directory, you can: M-x pui-set-local-package-get-directory RET
331
+ − 150
1648
+ − 151 (2) Obtain a list of packages and display the list in a buffer named
+ − 152 "*Packages*".
+ − 153 - menu: Tools -> Packages -> List & Install
+ − 154 - keyb: M-x pui-list-packages RET
456
+ − 155
1648
+ − 156 XEmacs will now connect to the remote site and download the
+ − 157 latest package-index file.
+ − 158
+ − 159 The resulting buffer, "*Packages*" has brief instructions at the
+ − 160 end of the buffer.
331
+ − 161
1648
+ − 162 (3) Choose the packages you wish to install.
+ − 163 - mouse: Click button 2 on the package name.
+ − 164 - keyb: RET on the package name
331
+ − 165
1648
+ − 166 (4) Make sure you have everything you need.
+ − 167 - menu: Packages -> Add Required
+ − 168 - keyb: r
456
+ − 169
1648
+ − 170 XEmacs will now search for packages that are required by the
+ − 171 ones that you have chosen to install and offer to select
+ − 172 those packages also.
331
+ − 173
1648
+ − 174 For novices and gurus alike, this step can save your bacon.
+ − 175 It's easy to forget to install a critical package.
+ − 176
+ − 177 (5) Download and install the packages.
+ − 178 - menu: Packages -> Install/Remove Selected
+ − 179 - keyb: x
331
+ − 180
456
+ − 181 ** Manually, using individual package tarballs
+ − 182 ----------------------------------------------
331
+ − 183
456
+ − 184 Fetch the packages from the FTP site, CD-ROM whatever. The filenames
331
+ − 185 have the form name-<version>-pkg.tar.gz and are gzipped tar files. For
+ − 186 a fresh install it is sufficient to untar the file at the top of the
456
+ − 187 package hierarchy.
+ − 188
+ − 189 Note: If you are upgrading packages already installed, it's best to
+ − 190 remove the old package first (see 'Upgrading/Removing Packages' below).
331
+ − 191
456
+ − 192 For example if we are installing the 'xemacs-base'
+ − 193 package (version 1.48):
+ − 194
+ − 195 mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
+ − 196 cd $prefix/lib/xemacs/xemacs-packages RET
+ − 197 gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
+ − 198
+ − 199 Or if you have GNU tar, the last step can be:
331
+ − 200
456
+ − 201 tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
+ − 202
+ − 203 For MULE related packages, it is best to untar into the mule-packages
+ − 204 hierarchy, i.e. for the mule-base package, version 1.37:
331
+ − 205
456
+ − 206 mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
+ − 207 cd $prefix/lib/xemacs/mule-packages RET
+ − 208 gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
+ − 209
+ − 210 Or if you have GNU tar, the last step can be:
331
+ − 211
456
+ − 212 tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
+ − 213
+ − 214
1648
+ − 215 ** Manually, all at once, using the 'Sumo Tarball'
+ − 216 --------------------------------------------------
331
+ − 217
1648
+ − 218 Those with little time, cheap connections and plenty of disk space can
+ − 219 install all the packages at once using the sumo tarballs.
+ − 220 Download the file:
456
+ − 221
1648
+ − 222 xemacs-sumo.tar.gz
331
+ − 223
1648
+ − 224 For an XEmacs compiled with Mule you also need:
+ − 225
+ − 226 xemacs-mule-sumo.tar.gz
331
+ − 227
1648
+ − 228 N.B. They are called 'Sumo Tarballs' for good reason. They are
+ − 229 currently about 19MB and 4.5MB (gzipped) respectively.
331
+ − 230
1648
+ − 231 Install them by:
456
+ − 232
1648
+ − 233 cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET
456
+ − 234
1648
+ − 235 Or, if you have GNU tar:
331
+ − 236
1648
+ − 237 cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET
456
+ − 238
1648
+ − 239 As the Sumo tarballs are not regenerated as often as the individual
+ − 240 packages, it is recommended that you use the automatic package tools
+ − 241 afterwards to pick up any recent updates.
456
+ − 242
+ − 243 * After Installation
+ − 244 --------------------
331
+ − 245
1648
+ − 246 Updated packages can only be used by XEmacs after a restart.
331
+ − 247
456
+ − 248 * Which Packages to install?
+ − 249 ----------------------------
331
+ − 250
+ − 251 This is difficult to say. When in doubt install a package. If you
+ − 252 administrate a big site it might be a good idea to just install
+ − 253 everything. A good minimal set of packages for XEmacs-latin1 would be
+ − 254
+ − 255 xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
+ − 256 edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,
1648
+ − 257 text-modes, time, mailcrypt
331
+ − 258
456
+ − 259 If you are using the XEmacs package tools, don't forget to do:
+ − 260
+ − 261 Packages -> Add Required
+ − 262
+ − 263 To make sure you have everything that the packages you have chosen to
+ − 264 install need.
331
+ − 265
+ − 266 See also '.../etc/PACKAGES' for further descriptions of the individual
456
+ − 267 packages.
331
+ − 268
456
+ − 269 * Upgrading/Removing Packages
+ − 270 -----------------------------
331
+ − 271
+ − 272 As the exact files and their locations contained in a package may
438
+ − 273 change it is recommended to remove a package first before installing a
331
+ − 274 new version. In order to facilitate removal each package contains an
+ − 275 pgkinfo/MANIFEST.pkgname file which list all the files belong to the
+ − 276 package. M-x package-admin-delete-binary-package RET can be used to
+ − 277 remove a package using this file.
+ − 278
+ − 279 Note that the interactive package tools included with XEmacs already do
+ − 280 this for you.
+ − 281
456
+ − 282 * User Package directories
+ − 283 --------------------------
331
+ − 284
+ − 285 In addition to the system wide packages, each user can have his own
1648
+ − 286 packages installed under "~/.xemacs/". If you want to install packages
+ − 287 there using the interactive tools, you need to set
+ − 288 'package-get-install-to-user-init-directory' to 't'
331
+ − 289
456
+ − 290 * Site lisp/Site start
+ − 291 ----------------------
331
+ − 292
+ − 293 The site-packages hierarchy replaces the old 'site-lisp' directory.
+ − 294 XEmacs no longer looks into a 'site-lisp' directly by default.
+ − 295 A good place to put 'site-start.el' would be in
+ − 296 $prefix/lib/xemacs/site-packages/lisp/
424
+ − 297
456
+ − 298 * Finding the right packages
+ − 299 ----------------------------
424
+ − 300
+ − 301 If you want to find out which package contains the functionality you
+ − 302 are looking for, use M-x package-get-package-provider, and give it a
456
+ − 303 symbol that is likely to be in that package.
+ − 304
+ − 305 For example, if some code you want to use has a (require 'thingatpt)
+ − 306 in it:
+ − 307
+ − 308 M-x package-get-package-provider RET thingatpt RET
+ − 309
+ − 310 which will return something like: (fsf-compat "1.08").