"Fossies" - the Fresh Open Source Software Archive

Member "xemacs-21.4.22/README.packages" (7 Jul 2004, 11260 Bytes) of archive /linux/misc/xemacs-21.4.22.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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 
   10 The XEmacs Packages Quick Start Guide
   11 -------------------------------------
   12 
   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.
   16 
   17 * Real Real Quickstart FAQ
   18 --------------------------
   19 
   20 Q. Do I need to have the packages to compile XEmacs?
   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
   25    essential part of making your installed XEmacs _useful_.
   26 
   27 Q. I really liked the old way that packages were bundled and do not
   28    want to mess with packages at all.
   29 
   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 
   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 
   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.
   47 
   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 
   52 * A note of caution
   53 -------------------
   54 
   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
   57 set in stone. The XEmacs maintainers reserve the right to sacrifice
   58 backwards compatibility as quirks are worked out over the coming
   59 releases.
   60 
   61 * Some package theory
   62 ---------------------
   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 
   70 You select just the ones you need. Install them by untarring them into
   71 the right place. On startup XEmacs will find them, set up the load
   72 path correctly, install autoloads, etc, etc.
   73 
   74 * Package hierarchies
   75 ---------------------
   76 
   77 On Startup XEmacs looks for packages in so-called package hierarchies.
   78 Normally, there are three system wide hierarchies, like this:
   79 
   80 $prefix/lib/xemacs/xemacs-packages/
   81      Normal packages go here.
   82 
   83 $prefix/lib/xemacs/mule-packages/
   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 
   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.
  106 
  107 * Where to get the packages
  108 ---------------------------
  109 
  110 Packages are available from ftp://ftp.xemacs.org/pub/xemacs/packages
  111 and its mirrors.
  112 
  113 * How to install the packages
  114 -----------------------------
  115 There are a few different ways to install packages:
  116 
  117 	1. Automatically, using the package tools from XEmacs.
  118 	2. Manually, using individual package tarballs.
  119 	3. Manually, all at once, using the 'Sumo Tarball'.
  120 
  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.
  127 
  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:
  137 
  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.
  142 
  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)
  147 
  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
  150 
  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
  155 
  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.
  161 
  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
  165 
  166   (4) Make sure you have everything you need.
  167       - menu: Packages -> Add Required
  168       - keyb: r
  169 
  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.
  173 
  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
  180 
  181 ** Manually, using individual package tarballs
  182 ----------------------------------------------
  183 
  184 Fetch the packages from the FTP site, CD-ROM whatever. The filenames
  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
  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).
  191 
  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:
  200 
  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:
  205 
  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:
  211 
  212    tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
  213 
  214 
  215 ** Manually, all at once, using the 'Sumo Tarball'
  216 --------------------------------------------------
  217 
  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:
  221 
  222    xemacs-sumo.tar.gz
  223 
  224 For an XEmacs compiled with Mule you also need:
  225 
  226    xemacs-mule-sumo.tar.gz
  227 
  228 N.B. They are called 'Sumo Tarballs' for good reason. They are
  229 currently about 19MB and 4.5MB (gzipped) respectively.
  230 
  231 Install them by:
  232 
  233    cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET
  234 
  235 Or, if you have GNU tar:
  236 
  237    cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET
  238 
  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.
  242 
  243 * After Installation
  244 --------------------
  245 
  246 Updated packages can only be used by XEmacs after a restart.
  247 
  248 * Which Packages to install?
  249 ----------------------------
  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,
  257 text-modes, time, mailcrypt
  258 
  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.
  265 
  266 See also '.../etc/PACKAGES' for further descriptions of the individual
  267 packages.
  268 
  269 * Upgrading/Removing Packages
  270 -----------------------------
  271 
  272 As the exact files and their locations contained in a package may
  273 change it is recommended to remove a package first before installing a
  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 
  282 * User Package directories
  283 --------------------------
  284 
  285 In addition to the system wide packages, each user can have his own
  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'
  289 
  290 * Site lisp/Site start
  291 ----------------------
  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/
  297 
  298 * Finding the right packages
  299 ----------------------------
  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
  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").