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.