path: root/Install.txt

                   Installation Details for XFree86® 4.8.0

                          The XFree86 Project, Inc

                               12 August 2007

                                  Abstract

      How to install XFree86.

1.  Introduction

This document contains information about installing the XFree86 binaries pro-
vided by The XFree86 Project.

The XFree86 binaries that we provide for UNIX-like OS's (Linux, the BSDs,
Solaris, etc) are packaged in a platform-independent gzipped tar format, aka
"tarballs," identified by the .tgz suffix.  Along with the binaries we pro-
vide a customized version of the GNU tar utility called "extract" and an
installation script.  We recommend that these be used to install the bina-
ries.  (The source for this customized version of GNU tar can be found in the
XFree86 CVS repository's "utils" module, and from our ftp site
<URL:ftp://ftp.xfree86.org/pub/XFree86/misc/utils-1.1.3.tgz>.)

2.  Downloading the XFree86 4.8.0 binaries

We provide XFree86 4.8.0 binaries for a range of operating systems at our ftp
site <URL:ftp://ftp.xfree86.org/pub/XFree86/4.8.0/binaries/> and our web site
<URL:http://ftp.xfree86.org/pub/XFree86/4.8.0/binaries/>.  Often during
releases our site is heavily loaded.  Instead of downloading directly from us
we recommend that instead you use one of our mirror sites.

Our binaries are organized by sub-directories which correspond to each of the
OS/platforms for which we provide binaries.  First go to the sub-directory
that represents your OS platform. In some cases (e.g., Linux) there may be a
number of choices depending on the architecture or libc version your platform
uses.  In all case we recommend that you first download the Xinstall.sh
script, and run it as in the following example to find out which binary dis-
tribution you should download.

     sh Xinstall.sh -check

The output of this utility tells you which is the correct set of binaries for
you to download.  If you are careful with this step you will save yourself a
lot time and trouble from NOT downloading an incompatible distribution.

NOTES:

   o The Xinstall.sh script must be downloaded in binary mode, otherwise it
     will not  run correctly.  If you get lots of "command not found" mes-
     sages when you try to run it, then it is most likely because the script
     was not  downloaded in binary mode.  Some web browsers will not  do this
     for files of that name, so we also have a copy of it called "Xin-
     stall.bin", and most browsers should download that correctly.  When
     downloading it under this name, select "save as" on your browser, and
     save the file under the name "Xinstall.sh".

   o The Xinstall.sh script requires some system commands and utilities to
     function correctly.  While most systems will have these, some Linux
     installations may not.  If the script fails because of some missing sys-
     tem command, you need to install it before you can continue.

   o Always use the version of the Xinstall.sh script that is provided with
     the release.   Older versions of the script may not install newer
     releases correctly.

   o If the binary distribution reported by the Xinstall.sh script is not
     present on the XFree86 site, then there are two possibilities: The first
     is that it has not uploaded yet.  This is likeliest possibility if you
     are looking shortly after the release date.  The second possibility is
     that your target will not be be available for this release.  This is
     likeliest possibility if you are looking more than about two weeks after
     the release date.  Check here
     <URL:http://www.xfree86.org/4.8.0/UPDATES.html> for information about
     updates to our binary distributions, and here
     <URL:http://www.xfree86.org/4.8.0/ERRATA.html> for errata related to
     this release.

Assuming that you have run the Xinstall.sh script and found the binary dis-
tribution suitable for your system, download the necessary files.  The thir-
teen (13) mandatory files for all installations are listed below.  The
installer script will complain if you do not have all of the required files
in the same directory.

          1.   Xinstall.sh    The installer script
          2.   extract        The utility for extracting tarballs
          3.   Xbin.tgz       X clients/utilities and run-time libraries
          4.   Xlib.tgz       Some data files required at run-time
          5.   Xman.tgz       Manual pages
          6.   Xdoc.tgz       XFree86 documentation
          7.   Xfnts.tgz      Base set of fonts
          8.   Xfenc.tgz      Base set of font encoding data
          9.   Xetc.tgz       Run-time configuration files, part 1
          10.  Xrc.tgz        Run-time configuration files, part 2
          11.  Xvar.tgz       Run-time data
          12.  Xxserv.tgz     XFree86 X server
          13.  Xmod.tgz       XFree86 X server modules

NOTES:

   o Some web browsers have a problem downloading the extract utility cor-
     rectly.  If you encounter this problem, download the version called
     extract.exe.  (NOTE: This is not a MS-DOS/Windows       executable.)

   o Some distributions do not require the Xvar.tgz tarball.  If it is
     present in the binaries sub-directory for your platform, then it is
     required.

   o The Darwin/Mac OS X distribution do not have or require the Xmod.tgz
     tarball.

   o Some distributions may have additional mandatory tarballs.  While rare,
     the installer script will tell you if any are missing.

The following thirteen (13) tarballs are optional.  You should download the
ones you want to install.

          1.   Xdrm.tgz       Source for DRM kernel modules
          2.   Xfsrv.tgz      Font server
          3.   Xnest.tgz      Nested X server
          4.   Xprog.tgz      X header files, config files and compile-time libs
          5.   Xprt.tgz       X Print server
          6.   Xvfb.tgz       Virtual framebuffer X server
          7.   Xtinyx.tgz     TinyX servers
          8.   Xf100.tgz      100dpi fonts
          9.   Xfcyr.tgz      Cyrillic fonts
          10.  Xfscl.tgz      Scalable fonts (Speedo, Type1 and TrueType)
          11.  Xhtml.tgz      HTML version of the documentation
          12.  Xps.tgz        PostScript version of the documentation
          13.  Xpdf.tgz       PDF version of the documentation

NOTES:

   o Not all distributions will have all of the above optional tarballs.

   o Some distributions may have some additional optional tarballs.

If you miss some and want to install them later, go to the Manual Installa-
tion (section 4., page 1) section.

3.  Installing XFree86 4.8.0 using the Xinstall.sh script

We strongly recommend that our XFree86 4.8.0 binaries be installed using the
Xinstall.sh script we provide.  There are a lot of steps in the manual
installation process, and those steps can vary according to the platform and
hardware setup.  There is a description of the manual installation process
for the most common cases below (section 4., page 1).

You must login as the super user (root) to run the installer script and place
all of the downloaded files into a single directory.  Use the cd command to
change to the chosen directory and run the installer script as follows:

     sh Xinstall.sh

Answer the prompts as they come up.  If you are missing something that is
required, the installer may tell you to install it before trying again.  If
the problem is that you did not download all of mandatory files aforemen-
tioned, then the installer will tell you which ones are missing and ask you
to download them before proceeding.

3.1  Questions the installer may ask

The installer asks some questions that may not have obvious answers.  The
information here should help you answer them.  In most cases, apart from the
first question, the default answers should be OK.

If you run the installer from within an X session (the installer checks if
$DISPLAY is set), you will be warned that doing so is not a good idea.
Unless you have a good reason for knowing that this will not be a problem,
you should exit your X session, including stopping xdm or equivalent if it is
running, before continuing.  If you ignore this warning and run into prob-
lems, well, you were warned!

If you have an existing X installation, you will be warned that proceeding
with this installation will overwrite it.  Only those things that are part of
our standard distribution will be overwritten.  Other X applications that you
may have installed will not be removed.  Some configuration files may be
overwritten though, but the installer should prompt you before doing so and
will attempt to backup the existing files first.  As the opening greeting
says, it is strongly recommended that you backup any existing installation
before proceeding.  If you want your old applications to still be there after
you've installed, do not do the "backup" by simply renaming your old
/usr/X11R6 directory.  It is better to make a copy of it, and then install
over the top of the original one.  If you run into problems and want to
revert to the old installation, you can then delete the overwritten one and
copy the saved version back.

During the first part of the installation over an existing version, the
script may remove some old files or directories that would get in the way of
the new installation.  It will list which files/directories have been
removed.  If none are listed, then none were removed.

The next step when installing over an existing version is to check for exist-
ing configuration files.  On most platforms, the run-time configuration files
are installed by default under /etc/X11 instead of under /usr/X11R6/lib/X11.
The installer will give you the option of moving any that are in the old
location, creating the necessary symbolic links.  If you do not want to have
them moved, then you should answer "no" when asked about it.  If you have no
exiting run-time configuration files in the /etc/X11, then the new configura-
tion files will be installed in /usr/X11R6/lib/X11 instead.

Note: for the rare systems that do not have symbolic links, this question
will not be asked.  The default answer is "yes" because that is best for most
situations.  It makes it easier to share the /usr/X11R6 directory between
multiple hosts, and allows it to be mounted read-only.  If you do not need
these features, then you can safely answer "no" if you do not want them
moved.

When installing over an existing version, you will be prompted before each
set of configuration files is installed.  If you haven't made any Customisa-
tions to your existing configuration files, then you can safely answer "yes"
for each of these.  If you have made customisations, you can try answering
"no".  If you run into problems later, you may need to manually merge your
customisations into the the new version of the configuration files.  If your
platform uses customised xinit or xdm configuration files, overwriting them
may prevent your usual desktop from coming up after installing XFree86.  For
this reason you may wish to answer "no" when prompted for those files.  An
important set of files to answer "yes" to is the xkb files.  If they are not
up to date you may run into problems running the latest XFree86 server.

The installer will attempt to make a backup of your original files before
copying in the new ones.  This may not be foolproof and it is recommended
that you still make your own backup of everything first.  If you wish to
install the configuration manually, they can be found in the Xetc.tgz and
Xrc.tgz tarballs.  See the section below (section 4., page 1) about manual
installation for information about extracting them separately.

After the configuration files have been dealt with, the other mandatory com-
ponents of the binary distribution will be installed.  This should proceed
without any user intervention.

If you downloaded any of the optional components, the installer will ask you
about each one before it is installed.  The default answer is "yes".  If
there are any that you've since decided that you do not want to install,
answer "no" when prompted.

After that is done, the main part of the installation is complete.  The next
steps are to tidy up some aspects of the installation.  The first of these is
to run "ldconfig" on systems that require it, so that the newly installed
shared libraries are accessible.  Then the fonts.dir files in some directo-
ries are updated so that the fonts can be accessed correctly.  Next, the
installer checks to see if your system has a termcap file or terminfo files.
If it finds the former, it tells you how you may update the entries in that
file.  If it finds the latter, it asks you if you want it to update them for
you.

You may be asked if you want to create links for the GL libraries and header
files.  The OpenGL standard on some platforms (Linux in particular) says that
these should be installed in the standard system locations (/usr/lib and
/usr/include), so the installer offers to create the appropriate links.  If
you're running Linux, you should probably answer yes.  For other platforms it
is your choice.  If you already have another version of libGL in /usr/lib,
answering "yes" will remove it and replace it with a link to the version we
supply.  The installer will show you a listing of any existing versions
before asking if they should be replaced.

Finally, the installer asks you if you want a link created for the rstart
utility.  On most modern systems the link isn't essential, so the default
answer is "no".  Answer "yes" if you know that you need it.  If you find
later that you need it, you can create it easily by running:

     rm -f /usr/bin/rstartd
     ln -s /usr/X11R6/bin/rstartd /usr/bin/rstartd

3.2  After the installation is complete

The next step is to get the XFree86 server running.  The recommended way to
do this is to run:

     XFree86 -autoconfig

This will work well in many cases, and if it suits your needs you can make it
the default by simply moving/renaming any existing XF86Config file so that
the XFree86 server does not find it.  If it doesn't, or if you want to make
changes to the auto-detected configuration, try the xf86cfg or xf86config
utilities or try running:

     XFree86 -configure

Note that if you are running Darwin/Mac OS X, there is no step 3 :-).  You
should skip this step, as configuration is not required or possible.  The X
server configuration file is not used on Darwin/Mac OS X.

After the X server configuration is done, it may be advisable to reboot,
especially if you run xdm (or equivalent) or the font server (xfs).

4.  Installing XFree86 4.8.0 manually

This section contains information about manually installing the XFree86 4.8.0
binary distributions.  You should only use this method if you know what
you're doing.  The information here covers some common cases, but not every
possible case.  It also may not be complete or up to date.  Use at your own
risk.

Put all of the downloaded files into a single directory (choose some tempo-
rary location with enough space).  Become the super user (root).  All of the
following commands should be run as root, and they should be run from the
directory that has all of the downloaded files.  The "extract" utility should
be used to unpack the tarballs.  This is a customised version of GNU tar that
has the gzip code built-in, and which has a different usage when run under
the name "extract".  One important thing that extract does that most versions
of tar do not do by default is that it unlinks existing files before writing
new ones.  This is important when installing over an existing version of X.
If you choose to use some other utility to extract the tarballs, you're on
your own.

4.1  A new installation

The simplest case is when there is no existing X installation.  The installa-
tion procedure for this case is as follows:

     chmod +x extract
     mkdir /usr/X11R6
     mkdir /etc/X11
     ./extract -C /usr/X11R6 X[a-df-qs-uw-z]*.tgz
     ./extract -C /usr/X11R6 Xvfb.tgz    # If you are installing Xvfb
     ./extract -C /etc Xetc.tgz
     ./extract -C /etc Xrc.tgz
     ./extract -C /var Xvar.tgz
     ln -s /etc/X11/app-defaults /usr/X11R6/lib/X11
     ln -s /etc/X11/fs /usr/X11R6/lib/X11
     ln -s /etc/X11/lbxproxy /usr/X11R6/lib/X11
     ln -s /etc/X11/proxymngr /usr/X11R6/lib/X11
     ln -s /etc/X11/rstart /usr/X11R6/lib/X11
     ln -s /etc/X11/twm /usr/X11R6/lib/X11
     ln -s /etc/X11/xdm /usr/X11R6/lib/X11
     ln -s /etc/X11/xinit /usr/X11R6/lib/X11
     ln -s /etc/X11/xsm /usr/X11R6/lib/X11
     ln -s /etc/X11/xserver /usr/X11R6/lib/X11
     chmod ug-w /usr/X11R6/lib           # Make sure the permissions are OK
     /sbin/ldconfig /usr/X11R6/lib       # For Linux
     /sbin/ldconfig -m /usr/X11R6/lib    # For FreeBSD, NetBSD, OpenBSD
     /usr/X11R6/bin/mkfontdir /usr/X11R6/lib/X11/fonts/misc

4.2  Installing over an old installation

If you have an existing installation of X, you should make a backup copy of
it before installing the new version over the top of it.

Before doing anything else, make sure the extract command is executable, and
also link it to the name "gnu-tar" so that it can be used as a regular tar
command:

     chmod +x extract
     rm -f gnu-tar
     ln extract gnu-tar

The first part of the procedure is to move the old run-time config files from
/usr/X11R6/lib/X11 to /etc/X11.  Create /etc/X11 if it doesn't already exist.
For each of the following sub-directories (app-defaults, fs, lbxproxy, prox-
ymngr, rstart, twm, xdm, xinit, xsm, xserver) that you want to move, check
that there is a sub-directory of this name in /usr/X11R6/lib/X11.  Create a
sub-directory of the same name under /etc/X11, then copy the files over by
running:

     ./gnu-tar -C /usr/X11R6/lib/X11/subdir -c -f - . | \
       ./gnu-tar -C /etc/X11/subdir -v -x -p -U -f -

For each subdirectory that is moved, remove the one under /usr/X11R6/lib/X11
and create a symbolic link to the new location:

     rm -fr /usr/X11R6/lib/X11/subdir
     ln -s /etc/X11/subdir /usr/X11R6/lib/X11

For those subdirectories that didn't already exist under /usr/X11R6/lib/X11,
create one under /etc/X11 and create the symbolic link to it:

     mkdir /etc/X11/subdir
     ln -s /etc/X11/subdir /usr/X11R6/lib/X11

Once that is done, extract the config files from the Xetc.tgz and Xrc.tgz
tarballs into a temporary directory:

     mkdir tmpdir
     ./extract -C tmpdir Xetc.tgz
     ./extract -C tmpdir Xrc.tgz

and then copy each sub-directory over to the installed location:

     ./gnu-tar -C tmpdir/subdir -c -f - . | \
       ./gnu-tar -C /usr/X11R6/lib/X11/subdir -v -x -p -U -f -

If you have customised any config files in your old installation, you may
want to omit those sub-directories, or copy selected files over by hand.

Once that's done, the main part of the installation can be done:

     ./extract -C /usr/X11R6 `pwd`/X[a-df-qs-uw-z]*.tgz
     ./extract -C /usr/X11R6 Xvfb.tgz    # If you are installing Xvfb
     ./extract -C /var Xvar.tgz
     chmod ug-w /usr/X11R6/lib           # Make sure the permissions are OK
     /sbin/ldconfig /usr/X11R6/lib       # For Linux
     /sbin/ldconfig -m /usr/X11R6/lib    # For FreeBSD, NetBSD, OpenBSD
     /usr/X11R6/bin/mkfontdir /usr/X11R6/lib/X11/fonts/misc

     Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/Install.sgml,v 1.23 tsi Exp $


$XFree86: xc/Install.txt,v 1.5tsi Exp $