Mercurial > hg > xemacs-beta

comparison man/xemacs/packages.texi @ 373:6240c7796c7a r21-2b2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2b2
author cvs
date Mon, 13 Aug 2007 11:04:06 +0200
parents cc15677e0335
children a300bb07d72d
comparison
equal deleted inserted replaced
372:49e1ed2d7ed8 373:6240c7796c7a
1 @node Packages, Abbrevs, Running, Top 1 @node Packages, Abbrevs, Running, Top
2 @comment node-name, next, previous, up 2 @comment node-name, next, previous, up
3 3
4 @section Introduction to XEmacs Packages 4 @section Packages
5 @cindex packages 5 @cindex packages
6 6
7 The XEmacs 21 distribution comes only with a very basic set of 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 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 9 the distribution of earlier versions of XEmacs are now separately
10 available. The installer as well as the user can choose which 10 available. The installer as well as the user can choose which
11 packages to install; the actual installation process is easy. 11 packages to install; the actual installation process is easy.
12 This gives an installer the ability to tailor an XEmacs installation for 12 This gives an installer the ability to tailor an XEmacs installation for
13 local needs with safe removal of unnecessary code. 13 local needs with safe removal of unnecessary code.
14 14
15 @menu
16 * Package Terminology:: Understanding different kinds of packages.
17 * Using Packages:: How to install and use packages.
18 * Building Packages:: Building packages from sources.
19 @end menu
20
21 @node Package Terminology, Using Packages, , Packages
22 @comment node-name, next, previous, up
23
15 @subsection Package Flavors 24 @subsection Package Flavors
16 25
17 There are two main flavors of packages. 26 There are two main flavors of packages.
18 27
19 @itemize @emph 28 @itemize @bullet
20 @item Regular Packages 29 @item Regular Packages
30 @cindex regular packages
21 A regular package is one in which multiple files are involved and one 31 A regular package is one in which multiple files are involved and one
22 may not in general safely remove any of them. 32 may not in general safely remove any of them.
23 33
24 @item Single-File Packages 34 @item Single-File Packages
35 @cindex single-file packages
25 A single-file package is an aggregate collection of thematically 36 A single-file package is an aggregate collection of thematically
26 related but otherwise independent lisp files. These files are bundled 37 related but otherwise independent lisp files. These files are bundled
27 together for download convenience and individual files may deleted at 38 together for download convenience and individual files may deleted at
28 will without any loss of functionality. 39 will without any loss of functionality.
29 @end itemize 40 @end itemize
35 be installed directly into an XEmacs package directory. Source Packages 46 be installed directly into an XEmacs package directory. Source Packages
36 are for developers and include all files necessary for rebuilding 47 are for developers and include all files necessary for rebuilding
37 bytecompiled lisp and creating tarballs for distribution. 48 bytecompiled lisp and creating tarballs for distribution.
38 49
39 @subsection Binary Packages 50 @subsection Binary Packages
51 @cindex binary packages
40 Binary packages may be installed directly into an XEmacs package 52 Binary packages may be installed directly into an XEmacs package
41 hierarchy. 53 hierarchy.
42 54
43 @subsection Source Packages 55 @subsection Source Packages
44 56 @cindex source packages
45 Source packages contain all of the Package author's (where appropriate 57 Source packages contain all of the Package author's (where appropriate
46 in regular packages) source code plus all of the files necessary to 58 in regular packages) source code plus all of the files necessary to
47 build distribution tarballs (Unix Tar format files and gzipped for space 59 build distribution tarballs (Unix Tar format files and gzipped for space
48 savings). 60 savings).
49 61
50 @subsection Prerequisites for building Source Packages 62 @node Using Packages, Building Packages, Package Terminology, Packages
63 @comment node-name, next, previous, up
64
65 @subsection Getting Started
66
67 When you first download XEmacs 21, you will usually first grab the
68 @dfn{core distribution},
69 @cindex core distribution
70 a file called
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.
77
78 @subsection Choosing the Packages You Need
79
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}.
84
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.
88
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:
92
93 @example
94 Options->Customize->Emacs->Packages
95 @end example
96
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
99 to do so).
100
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:
104
105 @example
106 Options->Customize->List Packages
107 @end example
108
109 Or, you can get to it via the keyboard:
110
111 @example
112 M-x pui-list-packages
113 @end example
114
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
117 users.
118
119 @subsection XEmacs and Installing Packages
120
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:
127
128 @example
129 (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
130 package-get-remote))
131 @end example
132
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).
136
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:
139
140 @example
141 M-x pui-add-install-directory
142 @end example
143
144 Note, however, that any directories added using this function are not
145 saved; this information will be lost when you quit XEmacs.
146
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.
151
152 The easiest way to install a package is to use the visual package
153 browser and installer, using the menu pick:
154
155 @example
156 Options->Customize->List Packages
157 @end example
158
159 You can also access it using the keyboard:
160
161 @example
162 M-x pui-list-packages
163 @end example
164
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:
170
171 @table @kbd
172 @item -
173 The package has not been installed.
174 @item *
175 The package has been installed, but a newer version is available. The
176 current version is out-of-date.
177 @item +
178 The package has been marked for installation/update.
179 @end table
180
181 If there is no character in the first column, the package has been
182 installed and is up-to-date.
183
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.
189
190 Key summary:
191
192 @table @kbd
193 @item ?
194 Display simple help.
195 @item @key{RET}
196 @itemx @key{Mouse-2}
197 @itemx @key{Mouse-3}
198 Toggle between selecting and unselecting a package for installation.
199 @item x
200 Install selected packages.
201 @item @key{SPC}
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.
205 @item v
206 Toggle between verbose and non-verbose package display.
207 @item g
208 Refresh the package display.
209 @item q
210 Kill the package buffer.
211 @end table
212
213 Moving the mouse over a package will also cause additional information
214 about the package to be displayed in the minibuffer.
215
216 @subsection Other package installation interfaces
217
218 For an alternative package interface, you can select packages from the
219 customize menus, under:
220
221 @example
222 Options->Customize->Emacs->Packages-> ...
223 @end example
224
225 Set their state to on, and then do:
226
227 @example
228 Options->Customize->Update Packages
229 @end example
230
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.
236
237 You can also install packages using a semi-manual interface:
238
239 @example
240 M-x package-get-all <return>
241 @end example
242
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
246 it depends upon.
247
248 @subsection Manual Binary Package Installation
249
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:
253
254 @example
255 ~/.xemacs/packages
256 @end example
257
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.
263
264 To install binary packages manually:
265
266 @enumerate
267 @item
268 Download the package(s) that you want to install. Each binary package
269 will typically be a gzip'd tarball.
270
271 @item
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}.
277
278 @item
279 Next, @code{cd} to the directory under which you want to install the
280 package(s).
281
282 @item
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:
286
287 @example
288 gunzip < package.tar.gz | tar xvf -
289 @end example
290
291 Above, replace @file{package.tar.gz} with the filename of the
292 package that you downloaded in step 1.
293
294 Of course, if you use GNU @code{tar}, you could also use:
295
296 @example
297 tar xvzf package.tar.gz
298 @end example
299
300 @comment What about native MS Windows users???
301
302 @item
303 That's it. Quit and restart XEmacs to get it to recognize any new or
304 changed packages.
305
306 @end enumerate
307
308 @node Building Packages, , Using Packages, Packages
309 @comment node-name, next, previous, up
310
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.
315
316 @subsection Prerequisites for Building Source Packages
51 317
52 You must have GNU @code{cp}, GNU @code{install} (or a BSD compatible 318 You must have GNU @code{cp}, GNU @code{install} (or a BSD compatible
53 @code{install} program) GNU @code{make} (3.75 or later preferred), 319 @code{install} program) GNU @code{make} (3.75 or later preferred),
54 @code{makeinfo} (1.68 from @code{texinfo-3.11} or later required), GNU 320 @code{makeinfo} (1.68 from @code{texinfo-3.11} or later required), GNU
55 @code{tar} and XEmacs 21.0. The source packages will untar into a 321 @code{tar} and XEmacs 21.0. The source packages will untar into a
56 correct directory structure. At the top level you must have 322 correct directory structure. At the top level you must have
57 @file{XEmacs.rules} and @file{package-compile.el}. These files are 323 @file{XEmacs.rules} and @file{package-compile.el}. These files are
58 available from the XEmacs FTP site from the same place you obtained your 324 available from the XEmacs FTP site from the same place you obtained your
59 source package distributions. 325 source package distributions.
60 326
61 @subsection What you can do with Source Packages 327 @subsection What You Can Do With Source Packages
62 328
63 NB: A global build operation doesn't exist yet as of 13 January 1998. 329 NB: A global build operation doesn't exist yet as of 13 January 1998.
64 330
65 Source packages are most useful for creating XEmacs package tarballs 331 Source packages are most useful for creating XEmacs package tarballs
66 for installation into your own XEmacs installations or for 332 for installation into your own XEmacs installations or for
67 distributing to others. 333 distributing to others.
68 334
69 Supported operations from Make are: 335 Supported operations from @file{make} are:
70 336
71 @table @code 337 @table @code
72 @item clean 338 @item clean
73 Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}. 339 Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
74 340