Source

xemacsweb / Documentation / packageGuide.content

%title%
Quickstart Package Guide
%author%
john s jacobs anderson using old content with no listed author
%main%
                        <h1>Quickstart Package Guide</h1>
            
            <p> This text is intended to help you get started installing a
              new XEmacs and its packages from start.  For details see the
              <strong>'Startup Paths'</strong> and <strong>'Packages'</strong> sections of the
              XEmacs info manual.</p>
            
            <h2>Index</h2>

            <table border="0" cellspacing="0" cellpadding="0">
	    <tbody><tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#realQuick" shape="rect">Real quick quickstart guide</a>
                  </td></tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#A_note_of_caution" shape="rect">A note of caution</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#Some_Package_Theory" shape="rect">Some Package Theory</a>
                  </td>
	      </tr>  
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#Package_hierarchies" shape="rect">Package hierarchies</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#Where_to_get_the_packages" shape="rect">
                      Where to get the packages</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#How_to_install_the_packages" shape="rect">
                      How to install the packages</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#The_Sumo_Tarball" shape="rect">The Sumo Tarball</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#Installing_by_Hand" shape="rect">Installing by Hand</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#Installing_automatically" shape="rect">
                      Installing automatically</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#After_Installation" shape="rect">After Installation</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#Note_to_MULE_users" shape="rect">Note to MULE users</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#Which_Packages_to_install?" shape="rect">
                      Which Packages to install?</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="packageGuide.html#Upgrading:Removing_Package" shape="rect">
                      Upgrading/Removing Packages</a>
                  </td>
	      </tr>
	      <tr><td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="./packageGuide.html#User_Package_directories" shape="rect">
                      User Package directories</a>
                  </td>
	      </tr>
	      <tr> 
		<td rowspan="1" colspan="1"><img src="../Images/blank.png" alt="" height="1" width="40"/></td>
		<td rowspan="1" colspan="1">
                    <a href="packageGuide.html#Site_lisp:Site_start" shape="rect">
                      Site lisp/Site start</a>
                  </td>
	      </tr></tbody>
	  </table>	   

            <h2><a name="realQuick" shape="rect">Real Real Quickstart FAQ</a></h2>

            <p><strong>Q:</strong> Do I need to have the packages to compile
              XEmacs?
              <br clear="none"/>
              <strong>A:</strong> No.</p>
            
            <p><strong>Q:</strong> I really liked the old way that packages were
              bundled and do not want to mess with packages at
              all.
              <br clear="none"/>
              <strong>A:</strong> You can grab all the packages at once like you
              used to with old XEmacs versions, skip to the 
              <a href="./packageGuide.html#The_Sumo_Tarball" shape="rect">'Sumo Tarball'</a>
              section below.</p>
            
            <h2><a name="A_note_of_caution" shape="rect">A note of caution</a></h2>
            <p>
              The XEmacs package system is still in its
              infancy. Please expect a few minor hurdles on the
              way. Also neither the interface nor the structure is
              set in stone. The XEmacs maintainers reserve the
              right to sacrifice backwards compatibility as quirks
              are worked out over the coming releases.</p>
            
            <h2><a name="Some_Package_Theory" shape="rect">
                Some Package Theory</a></h2>
            <p>
              In order to reduce the size and increase the
              maintainability of XEmacs, the majority of the Elisp
              that came with previous releases have been
              unbundled. They have been replaced by the package
              system.  Each elisp add-on (or groups of them when
              they are small) now comes in its own tarball that
              contains a small search hierarchy.</p>
            
            <p>
              You select just the ones you need. Install them by
              untarring them into the right place. On startup
              XEmacs will find them, set up the load path
              correctly, install autoloads, etc, etc.</p>
            
            <h2><a name="Package_hierarchies" shape="rect">Package hierarchies</a></h2>
            <p>
              On startup XEmacs looks for packages in so called
              package hierarchies.  These can be specified by the
              <code>package-path</code> parameter to the
              <code>configure</code> script. However by default there are
              three system wide hierarchies.</p>
            
            <p>Local and 3rd party packages go here:
              <code>$prefix/lib/xemacs/site-packages</code><br clear="none"/>
              Only searched by MULE-enabled XEmacsen:
              <code>$prefix/lib/xemacs/mule-packages</code><br clear="none"/>
		Normal packages go here:
		<code>$prefix/lib/xemacs/xemacs-packages</code></p>

            <h2><a name="Where_to_get_the_packages" shape="rect">Where to get the packages</a></h2>

            <p>Packages are available from
              <a href="ftp://ftp.xemacs.org/pub/xemacs/packages" shape="rect">ftp://ftp.xemacs.org/pub/xemacs/packages</a>
              and its mirrors. Some package descriptions and links to other
              resources can be found on the
              <a href="../Download/elispPackages.html" shape="rect">Elisp Packages</a> page.</p>

            <h2><a name="How_to_install_the_packages" shape="rect">How to install the packages</a></h2>

            <p>Choose one of the following options:</p>

            <ol>
	    <li>All at once, using the 
                <a href="./packageGuide.html#The_Sumo_Tarball" shape="rect">'Sumo Tarball'</a>.</li>
	    <li><a href="./packageGuide.html#Installing_by_Hand" shape="rect">By hand</a></li>
	    <li><a href="./packageGuide.html#Installing_automatically" shape="rect">Automatically</a>,
                using the package tools from XEmacs.</li>
	  </ol>		

            <h2><a name="The_Sumo_Tarball" shape="rect">The Sumo Tarball</a></h2>

            <p>Those with little time, cheap connections and plenty of disk space
              can install all packages at once using the sumo tarballs.  Download
              the file

              <code>xemacs-sumo-&lt;date&gt;.tar.gz</code>

              from the <a href="ftp://ftp.xemacs.org/pub/xemacs/packages" shape="rect">ftp site</a></p>

            <p>For an XEmacs compiled with Mule you also need

              <code>xemacs-mule-sumo-&lt;date&gt;.tar.gz</code></p>

            <p><em>Note:</em> They are called 
              <a href="./packageGuide.html#The_Sumo_Tarball" shape="rect">'Sumo Tarballs'</a> for good
              reason. They are currently about 15MB and 2.3MB
              (gzipped) respectively.</p>

            <p>
              Install them by
            </p>

            <code>
              cd $prefix/lib/xemacs ; gunzip -c &lt;tarballname&gt; | tar xf -
            </code>

            <p>As the Sumo tarballs are not regenerated as often as the individual
              packages, it is recommended that you use the
              <a href="./packageGuide.html#Installing_automatically" shape="rect">automatic package tools</a>
              afterwards to pick up any recent updates.</p>  

            <h2><a name="Installing_by_Hand" shape="rect">Installing by Hand</a></h2>

            <p>Fetch the packages from the <a href="ftp://ftp.xemacs.org/pub/xemacs/packages" shape="rect">ftp site</a>,
              CDROM whatever. The filenames
              have the form <code>name-&lt;version&gt;-pkg.tar.gz</code> and are gzipped
              tar files. For a fresh install it is sufficient to untar the file at
              the top of the package hierarchy. For example if we are installing the
              <code>'xemacs-base'</code> package in version 1.27:

              <br clear="none"/><br clear="none"/><code>
                mkdir $prefix/lib/xemacs/xemacs-packages \ # if it does not exist yet<br clear="none"/>
		    cd $prefix/lib/xemacs/xemacs-packages<br clear="none"/>
		      gunzip -c ...../xemacs-base-1.27-pkg.tar.gz | tar xf -<br clear="none"/>
              </code></p>

            <p> For MULE related packages, it is best to untar in the
              mule-packages hierarchy, i.e. for the mule-base package, version 1.25

              <br clear="none"/><br clear="none"/><code>
                mkdir $prefix/lib/xemacs/mule-packages # if it does not exist yet<br clear="none"/>
		    cd $prefix/lib/xemacs/mule-packages<br clear="none"/>
		      gunzip -c ...../mule-base-1.25-pkg.tar.gz | tar xf -<br clear="none"/>
              </code></p>

            <h2><a name="Installing_automatically" shape="rect">Installing automatically</a></h2>

            <p> XEmacs comes with some tools to make the periodic updating and
              installing easier. It will notice if new packages or versions are
              available and will fetch them from the ftp site.</p>

            <p> Unfortunately this requires that a few packages are already in
              place. You will have to install them by hand as above or use a SUMO
              tarball. This requirement will hopefully go away in the future. The
              packages you need are:</p> 

            <table>
	    <tbody><tr>
		<td rowspan="1" colspan="1" align="right"><strong>efs</strong></td>
		<td rowspan="1" colspan="1">To fetch the files from the ftp site or mirrors.</td>
	      </tr>
	      <tr>
		<td rowspan="1" colspan="1" align="right"><strong>xemacs-base</strong></td>
		<td rowspan="1" colspan="1">Needed by efs.</td>
	      </tr>
	      <tr>
		<td rowspan="1" colspan="1" align="right" valign="top"><strong>mailcrypt</strong><br clear="none"/>(optional)</td>
		<td rowspan="1" colspan="1" valign="top">
                    If you have PGP installed and want to verify the
                    signature of the index file.
                  </td>
	      </tr>
	      <tr>
		<td rowspan="1" colspan="1" align="right" valign="top"><strong>mule-base</strong><br clear="none"/>(optional)</td>
		<td rowspan="1" colspan="1" valign="top">
                    Needed if you want to run XEmacs with MULE with
                    a non-English language environment.
                  </td>
	      </tr></tbody>
	  </table>

            <p> After installing these by hand, you can start XEmacs. (It is a
              good idea to use 'xemacs -vanilla' here as your startup files might
              need things now moved to packages.)</p>

            <ul>
	    <li>First you need to specify an FTP site to use.  Use
                <strong>Options-&gt;Manage Packages-&gt;Add Download Site</strong> in the
                menubar or type <code>M-x customize-variable RET
                  package-get-remote RET</code>
                <br clear="none"/>
                Alternatively, if you already have the packages on a local disk
                then you can specify this directly by typing <code>M-x
                  pui-add-install-directory</code>. Please make sure you also have
                a corresponding copy of the package
                index there.</li>
	    <li>Invoke <strong> Options-&gt;Manage Packages-&gt;List &amp; Install
                </strong> from the menubar or type <code>M-x pui-list-packages
                  RET</code>. XEmacs will now first try to fetch a new version of
                the package index from the FTP site. Depending on whether you
                are using <strong>mailcrypt/PGP</strong>, you will get some question
                about keys to fetch or whether to use the index without
                verifying the signature. If the new index was different from the
                one already on disk, XEmacs will offer you to overwrite the old
                index.</li>
	    
	    <li>XEmacs will show you a buffer named <code>*Packages*</code> with
                an overview of available and installed packages, including a
                short description.  In this buffer you can select which packages
                you want by using the mouse or typing <code>RET</code>.</li>

	    <li>When you are finished choosing packages, invoke
                <strong>'Packages->Install/Remove Select'</strong> from the menubar or
                type <code>x</code> to begin installing packages.</li>
	    
	  </ul>

            <h2><a name="After_Installation" shape="rect">After Installation</a></h2>

            <p> New packages can only be used by XEmacs after a restart.</p>

            <h2><a name="Note_to_MULE_users" shape="rect">Note to MULE users</a></h2>

            <p> It is a good idea to keep packages that are MULE-only separate by
              putting them in the mule-packages hierarchy.  Non-Mule XEmacsen will
              ignore packages in mule-packages so it is safe to have that directory
              in the package path of a Non-Mule XEmacs.</p>

            <h2><a name="Which_Packages_to_install?" shape="rect">Which Packages to install?</a></h2>

            <p> This is difficult to say. When in doubt install a package. If you
              administrate a big site it might be a good idea to just install
              everything. A good minimal set of packages for XEmacs-latin1 would be</p>

            <blockquote><code> xemacs-base, xemacs-devel, c-support, cc-mode,
                debug, dired, efs, edit-utils, fsf-compat, mail-lib, net-utils,
                os-utils, prog-modes, text-modes, time</code></blockquote>

            <p>Unfortunately the package system currently provides neither
              dependencies nor conflicts. This will be a future enhancement. The
              above set includes most packages that are used by others.</p>

            <p>See also <code>.../etc/PACKAGES'</code> for further descriptions of
              the individual packages (currently outdated).</p> 

            <h2><a name="Upgrading:Removing_Package" shape="rect">Upgrading/Removing Packages</a></h2>

            <p> As the exact files and their locations contained in a package may
              change it is recommend to remove a package first before installing a
              new version. In order to facilitate removal each package contains an
              <code>pgkinfo/MANIFEST.pkgname</code> file which list all the files
              belong to the package. The command <code>M-x
                package-admin-delete-binary-package RET</code> can be used to remove a
              package using this file.</p>

            <p> Note that the interactive package tools included with XEmacs
              already do this for you.</p> 

            <h2><a name="User_Package_directories" shape="rect">User Package directories</a></h2>

            <p> In addition to the system wide packages, each user can have his
              own packages installed in <code>~/.xemacs</code> (Note that this will
              most likely change to <code>~/.xemacs/packages</code> in the near
              future). If you want to install packages there using the interactive
              tools, you need to set the variable
              <code>'pui-package-install-dest-dir'</code> to <code>~/.xemacs</code></p>

            <h2><a name="Site_lisp:Site_start" shape="rect">Site lisp/Site start</a></h2>

            <p> The site-packages hierarchy replaces the old
              <code>site-lisp</code> directory.  XEmacs no longer looks into a
              <code>site-lisp</code> directly by default.  A good place to put
              <code>site-start.el</code> would be in
              <code>$prefix/lib/xemacs/site-packages/lisp/</code></p>