2 This file is in Outline mode. It is best viewed under SXEmacs.
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
8 For general SXEmacs navigation tips: Press C-h t
10 The SXEmacs Packages Quick Start Guide
11 -------------------------------------
13 This text is intended to help you get started installing a new SXEmacs and
14 its packages. For more details see the 'Startup Paths' and 'Packages'
15 sections of the SXEmacs info manual.
17 * Real Real Quickstart FAQ
18 --------------------------
20 Q. Do I need to have the packages to compile SXEmacs?
22 A. Theoretically, no -- SXEmacs 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
25 essential part of making your installed SXEmacs _useful_.
27 Q. How do I tell SXEmacs where to find the packages?
29 A. Normally, you put the packages under $prefix/share/sxemacs/*-packages, where
30 $prefix is specified using the `--prefix' parameter to `configure'.
31 (See `Package hierarchies' below). However, if you have the packages
32 somewhere else (e.g. you're a developer and are compiling the packages
33 yourself, and want your own private copy of everything), use the
34 `--with-package-path' parameter, something like this:
36 configure --with-package-path="~/.sxemacs::/src/sxemacs/site-packages:/src/sxemacs/xemacs-packages:/src/sxemacs/mule-packages" ...
38 Q. After installing, I want SXEmacs to do `foo', but when I invoke it
39 (or click the toolbar button or select the menu item), nothing (or
40 an error) happens, and it used to work.
42 A. See the first FAQ; you may be missing a package that is essential to
43 you. You can either track it down and install it, or install the
44 `Sumo Tarball' (see the second FAQ).
49 The SXEmacs package system is still in its infancy. Please expect a few
50 minor hurdles on the way. Also neither the interface nor the structure is
51 set in stone. The SXEmacs maintainers reserve the right to sacrifice
52 backwards compatibility as quirks are worked out over the coming
58 In order to reduce the size and increase the maintainability of
59 SXEmacs, we don't bundle or ship any elisp packages, other than a
60 "bare bones" assortment of elisp that gives SXEmacs fairly basic
63 The SXEmacs team doesn't host any package repositories, and doesn't
64 maintain any packages. But there's no need for concern, SXEmacs can
65 use the XEmacs packages without problem.
70 On Startup SXEmacs looks for packages in so-called package hierarchies.
71 Normally, there are up to four system wide hierarchies, like this:
73 $prefix/share/sxemacs/xemacs-packages/
74 Normal packages go here.
76 $prefix/share/sxemacs/mule-packages/
77 Mule packages go here and are only searched by MULE-enabled SXEmacsen.
79 $prefix/share/sxemacs/site-packages/
80 Local and 3rd party packages go here.
82 $prefix/share/sxemacs/sxemacs-packages/
83 SXEmacs-specific go here (none exist yet)
85 This is what you get when you untar the SUMO tarballs under
86 $prefix/share/sxemacs.
88 $prefix is specified using the `--prefix' parameter to `configure', and
89 defaults to `/usr/local'.
91 If your packages are located in the above directories, SXEmacs will
92 automatically find them at startup; however, if you have your packages
93 somewhere else (e.g. you're a developer and are compiling the packages
94 yourself, and want your own private copy of everything), you can tell
95 SXEmacs specifically where to look for the packages by using the
96 `--with-package-path' parameter to the 'configure' script. Normally, it looks
99 configure --with-package-path="~/.xemacs::/src/xemacs/site-packages:/src/xemacs/xemacs-packages:/src/xemacs/mule-packages" ...
101 See `configure --help' for more info about the format of this parameter.
103 Note: Most people will _not_ need to set --with-package-path
105 * Where to get the packages
106 ---------------------------
108 Packages are available from ftp://ftp.xemacs.org/pub/xemacs/packages
111 * Bootstrapping the package tools
112 ---------------------------------
113 You only need to read this section if you do not have _any_ XEmacs
116 Unlike XEmacs, SXEmacs' package tools are usable without having to
117 manually install any packages to "bootstrap" it. There are two
118 requirements for this to work...
120 1. Your SXEmacs includes support for FFI. Configure
121 automatically detects it if you have it. And this quick
122 test will return `t' if you do...
124 M-: (fboundp #'ffi-defun) RET
126 2. libcurl.so installed. Note that you do not need this library
129 All you have to do now is...
131 1. Set a download site...
133 Menu: Tools -> Packages -> Set Download Site ->
135 2. `M-x pui-bootstrap RET'
137 That's it! What will happen is that SXEmacs will download and install
138 the latest package-index file. Then it will download and install the
139 latest versions of the EFS and xemacs-base packages. Finally, SXEmacs
140 will ask you if you want to install more packages. At this point,
141 SXEmacs reverts back to "normal" PUI behaviour (using EFS to download
145 * How to install the packages
146 -----------------------------
147 There are a few different ways to install packages:
149 1. Automatically, using the package tools from SXEmacs.
150 2. Manually, using individual package tarballs.
151 3. Manually, all at once, using the 'Sumo Tarball'.
152 4. The lazy (smart) XEmacs users' way.
154 ** Automatically, using the package tools from SXEmacs
155 -----------------------------------------------------
157 SXEmacs comes with some tools to make the periodic updating and
158 installing easier. It will notice if new packages or versions are
159 available and will fetch them from the FTP site.
161 (1) Choose a download site.
162 - via menu: Tools -> Packages -> Set Download Site
163 - via keyb: M-x customize-variable RET package-get-remote RET
164 (put in the details of remote host and directory)
166 If the package tarballs _AND_ the package-index file are in a
167 local directory, you can: M-x pui-set-local-package-get-directory RET
169 (2) Obtain a list of packages and display the list in a buffer named
171 - menu: Tools -> Packages -> List & Install
172 - keyb: M-x pui-list-packages RET
174 SXEmacs will now connect to the remote site and download the
175 latest package-index file.
177 The resulting buffer, "*Packages*" has brief instructions at the
180 (3) Choose the packages you wish to install.
181 - mouse: Click button 2 on the package name.
182 - keyb: RET on the package name
184 (4) Make sure you have everything you need.
185 - menu: Packages -> Add Required
188 SXEmacs will now search for packages that are required by the
189 ones that you have chosen to install and offer to select
192 For novices and gurus alike, this step can save your bacon.
193 It's easy to forget to install a critical package.
195 (5) Download and install the packages.
196 - menu: Packages -> Install/Remove Selected
199 ** Manually, using individual package tarballs
200 ----------------------------------------------
202 Fetch the packages from the FTP site, CD-ROM whatever. The filenames
203 have the form name-<version>-pkg.tar.gz and are gzipped tar files. For
204 a fresh install it is sufficient to untar the file at the top of the
207 Note: If you are upgrading packages already installed, it's best to
208 remove the old package first (see 'Upgrading/Removing Packages' below).
210 For example if we are installing the 'xemacs-base'
211 package (version 1.48):
213 mkdir $prefix/share/sxemacs/xemacs-packages RET # if it does not exist yet
214 cd $prefix/share/sxemacs/xemacs-packages RET
215 gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
217 Or if you have GNU tar, the last step can be:
219 tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
221 For MULE related packages, it is best to untar into the mule-packages
222 hierarchy, i.e. for the mule-base package, version 1.37:
224 mkdir $prefix/share/sxemacs/mule-packages RET # if it does not exist yet
225 cd $prefix/share/sxemacs/mule-packages RET
226 gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
228 Or if you have GNU tar, the last step can be:
230 tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
233 ** Manually, all at once, using the 'Sumo Tarball'
234 --------------------------------------------------
236 Those with little time, cheap connections and plenty of disk space can
237 install all the packages at once using the sumo tarballs.
242 For an SXEmacs compiled with Mule you also may want:
244 xemacs-mule-sumo.tar.gz
246 N.B. They are called 'Sumo Tarballs' for good reason. They are
247 currently about 19MB and 4.5MB (gzipped) respectively.
251 cd $prefix/share/sxemacs ; gunzip -c <tarballname> | tar xvf - RET
253 Or, if you have GNU tar:
255 cd $prefix/share/sxemacs ; tar zxvf /path/to/<tarballname> RET
257 As the Sumo tarballs are not regenerated as often as the individual
258 packages, it is recommended that you use the automatic package tools
259 afterwards to pick up any recent updates.
261 ** The lazy (smart) XEmacs users' way
262 -------------------------------------
264 If you are a XEmacs user and already have all the packages installed
265 in the XEmacs locations, here is a quick and easy way to get SXEmacs
266 to see and use them too...
268 ln -svf /usr/local/lib/xemacs /usr/local/share/sxemacs RET
270 You can do the same with your ~/.xemacs directory too...
272 ln -svf ~/.xemacs ~/.sxemacs RET
278 Updated packages can only be used by SXEmacs after a restart.
280 * Which Packages to install?
281 ----------------------------
283 This is difficult to say. When in doubt install a package. If you
284 administrate a big site it might be a good idea to just install
285 everything. A good minimal set of packages for SXEmacs-latin1 would be
287 xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
288 edit-utils, mail-lib, net-utils, os-utils, prog-modes, text-modes,
291 If you are using the SXEmacs package tools, don't forget to do:
293 Packages -> Add Required
295 To make sure you have everything that the packages you have chosen to
298 See also '.../etc/PACKAGES' for further descriptions of the individual
301 * Upgrading/Removing Packages
302 -----------------------------
304 As the exact files and their locations contained in a package may
305 change it is recommended to remove a package first before installing a
306 new version. In order to facilitate removal each package contains an
307 pgkinfo/MANIFEST.pkgname file which list all the files belong to the
308 package. M-x package-admin-delete-binary-package RET can be used to
309 remove a package using this file.
311 Note that the interactive package tools included with SXEmacs already do
314 * User Package directories
315 --------------------------
317 In addition to the system wide packages, each user can have his own
318 packages installed under "~/.sxemacs/". If you want to install packages
319 there using the interactive tools, you need to set
320 'package-get-install-to-user-init-directory' to 't'
322 * Site lisp/Site start
323 ----------------------
325 The site-packages hierarchy replaces the old 'site-lisp' directory.
326 SXEmacs no longer looks into a 'site-lisp' directly by default.
327 A good place to put 'site-start.el' would be in
328 $prefix/share/sxemacs/site-packages/lisp/
330 * Finding the right packages
331 ----------------------------
333 If you want to find out which package contains the functionality you
334 are looking for, use M-x package-get-package-provider, and give it a
335 symbol that is likely to be in that package.
337 For example, if some code you want to use has a (require 'thingatpt)
340 M-x package-get-package-provider RET thingatpt RET
342 which will return something like: (fsf-compat "1.08").