path: root/xc/programs/Xserver/hw/xfree86/doc/sgml/BUILD.sgml

<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN" [
<!ENTITY % defs SYSTEM "defs.ent"> %defs;
]>

<article>
<title>Building XFree86 from a Source Distribution
<author>David Dawes, Matthieu Herrb
<Date>27 May 2001

<abstract>
This document describes how to build XFree86 from the <bf>source</bf>
distribution.  It is designed to
be used in conjunction with the OS-specific README files.
</abstract>

<toc>

<p>
<quote>
<bf/NOTE:/  Refer to the appropriate OS-specific README file before attempting
       to build XFree86.  These files contain additional information that 
       you may need to successfully build under your OS.
</quote>


We highly recommend using gcc to build XFree86, but it generally also
builds with the native compiler for each platform; 

<sect>How to get the XFree86 &relvers; source

<p>
There are a few starting points for getting the XFree86 source.  One option
is to start directly with the XFree86 &relvers; source distribution.  In this
case, the procedure is as follows:
<itemize>
  <item>The XFree86 source is contained in files <tt>X&srcvers;src-1.tgz</tt>,
	<tt>X&srcvers;src-2.tgz</tt> and <tt>X&srcvers;src-3.tgz</tt>.  These can be found
	at <htmlurl name="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/source/"
	url="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/source/"> and similar
	locations on XFree86 mirror sites.  <tt>X&srcvers;src-2.tgz</tt> contains
	the fonts and documentation source.  <tt>X&srcvers;src-3.tgz</tt> contains
	the hardcopy documentation.  <tt>X&srcvers;src-1.tgz</tt> contains
	everything else.  If you don't need the docs or fonts you can get
	by with only <tt>X&srcvers;src-1.tgz</tt>.
  <item>Extract each of these files by running the following from a directory
	on a filesystem containing enough space (the full source requires
	around 270MB, and a similar amount is required in addition to this
	for the compiled binaries):
	<quote><tt>
	gzip -d &lt; X410src-1.tgz | tar vxf -<newline>
	gzip -d &lt; X410src-2.tgz | tar vxf -<newline>
	gzip -d &lt; X410src-3.tgz | tar vxf -<newline>
	</tt></quote>
    <item>If the release is not a full release, it is available as a
    patch against the previous full release in the 
<htmlurl
name="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/patches/"
url="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/patches/">
directory. Get the patch file from there and apply it by running the
following command:
<quote><tt>
cd <em>the directory containing the</em> xc <em>directory</em><newline>
gzip -d &lt; <em>file</em> | patch -s -p0 -E 
</tt>
</quote>
Look for special patching instructions in the <htmlurl name="Release
Notes" url="http://www.xfree86.org/&relvers;/RELNOTES.html">.
</itemize>

Another option is to get the source by anonymous CVS or CVSup. 
See <htmlurl name="http://www.xfree86.org/cvs/"
url="http://www.xfree86.org/cvs/"> for details on the different
procedure available. 

All method will produce one main source directory called <tt>xc</tt>. 

<sect>Configuring the source before building
<p>
It is recommended that you start the configuration process by going to the
<tt>xc/config/cf</tt> directory, and copying the file <tt>xf86site.def</tt>
to <tt>host.def</tt>.  Then read through the <tt>host.def</tt> file
(which is heavily commented), and set any parameters that you want for
your configuration.  You can usually find out what the default settings
are by checking the <tt>.cf</tt> file(s) relevant to your OS.

Unlike previous versions, imake can now automatically detect and set
the various <bf>OS*Version</bf> parameters, so you shouldn't need to
enter those settings explicitly.

If you are using just the <tt>X&srcvers;src-1.tgz</tt> part of the
source dist, you will need to define <bf>BuildFonts</bf> to
<bf>NO</bf>.

<sect>Using a shadow directory of symbolic links for the build
<p>
A recommended practice is to use a shadow directory of symbolic links
to do the build of XFree86. This permits to keep the source directory
unmodified during the build, which has the following benefits:
<itemize>
<item>In the case where CVS is used to maintain the source tree up to
date, the update process is not disturbed by foreign files not under
the control of CVS. 
<item>It is possible to build XFree86 for several different Operating
System or architectures from the same sources, shared by NFS.
<item>It is possible to build XFree86 with different configuration
options, just by putting a real copy<tt>host.def</tt> in each build
tree and by customizing it separately in each build tree.
</itemize>
<p>
To make a shadow directory of symbolic links, use the following steps:
<itemize>
<item>create the directory at the top of the build tree. It is often
created at the same level that the <tt>xc</tt> directory, but this is
not mandatory. 
<quote><tt>
cd <em>the directory containing the </em>xc<em>directory</em><newline>
mkdir build
</tt></quote>
<item>use the <tt>lndir</tt>command to make the shadow tree:
<quote><tt>
lndir ../xc
</tt></quote>
Note that you can refer to the <tt>xc</tt> directory with an absolute
path if needed. 
<p>
See the <htmlurl name="lndir(1) manual page"
url="http://www.xfree86.org/&relvers;/lndir.1.html"> for details. 
</itemize>
If <tt>lndir</tt> is not already installed on your system, you can
build it manually from the XFree86 sources by running the following
commands: 
<quote><tt>
cd xc/config/util<newline>
make -f Makefile.ini lndir<newline>
cp lndir <em>some directory in your PATH</em>
</tt></quote>

<sect>Building and installing the distribution
<p>
Before building the distribution, read through the OS-specific <tt/README/
file in <tt>xc/programs/Xserver/hw/xfree86/doc</tt> that is relevant to
you.  Once those OS-specific details have been taken care of, go your
build directory 
(either the <tt/xc/ directory or the shadow tree created before) and
run ``<tt/make World/'' with the <bf/BOOTSTRAPCFLAGS/ 
set as described in the OS-specific README (if necessary, but most
systems supported by XFree86 don't need <bf/BOOTSTRAPCFLAGS/).  It is
advisable to redirect stdout and stderr to <tt/World.Log/ so that you
can track down problems that might occur during the build.
<p> 
With Bourne-like shells (Bash, the Korn shell, <tt>zsh</tt>, etc.) use
a command like:
<quote><tt>
make World &gt; World.log 2&gt;&amp;1
</tt></quote>
Witch C-shell variants (<tt>csh</tt>, <tt>tcsh</tt>, etc), use:
<quote><tt>
make World &gt;&amp; World.log
</tt></quote>
You can follow the progress of the build by running:
<quote><tt>
tail -f World.log
</tt></quote> in a terminal. 

<p>
When the build is finished, you should check <tt/World.Log/ to see
if there were any problems.  If there weren't any then you can install
the binaries.  
To do
the install, run ``<tt/make
install/'' and ``<tt/make install.man/''.  Make sure you have enough
space in <tt>/usr/X11R6</tt> for the install to succeed.  If you want
to install on a filesystem other than <tt>/usr</tt>, make a symbolic
link to <tt>/usr/X11R6</tt> before installing.

<sect>Reconfiguring the server (source distribution)
<p>
To build a different set of servers or servers with a different set of
drivers installed:
<enum>
<item>Make sure the source for any new drivers is in the correct place (e.g.,
driver source should be in a subdirectory of
<tt>xc/programs/Xserver/hw/xfree86/drivers</tt>).

<item>Change the settings of the server defines
in <tt/host.def/ to specify which servers you
wish to build.  Also, change the driver lists to suit your needs.

<item>From <tt>xc/programs/Xserver</tt>, run:
<tscreen><verb>
	make Makefile
	make Makefiles
        make includes
	make depend
	make
</verb></tscreen>
</enum>

<sect>Other useful make targets
<p>There are some other useful targets defined in the top level
<tt>Makefile</tt>of XFree86: 
<itemize>
<item><bf/Everything/ after a <tt>make World</tt>, <tt>make
Everything</tt>does everything a <tt>make World</tt> does, except the
cleaning of the tree. It is a way to quickly rebuild the tree after a
source patch, but it is not 100% bullet proof. There are cases were it
is better to force a full build by using <tt>make World</tt>. 


<item><bf/clean/ does a partial cleaning of the source tree. Removes
object files and generated manual pages, but leaves the Makefiles and
the generated dependencies files in place. After a <tt>make clean</tt>
you need to re-run 
<tscreen><verb>
        make includes
        make depend
        make
</verb>
</tscreen>
to rebuild the XFree86. 

<item><bf/distclean/ does a full cleaning of the source tree,
removing all generated files. After a <tt>make distclean</tt>,
<tt>make World</tt> is the only option to rebuild XFree86. 

<item><bf/includes/ generates all generated header files and in-tree
symbolic links  needed by the build. These files are removed by a
<tt>make clean</tt>. 

<item><bf/depend/ recomputes the dependencies for the various targets
in all Makefiles. Depending on the operating system, the dependencies
are stored in the Makefile, or as a separate file, called
<tt>.depend</tt>. This target needs the generated include files
produced by <tt>make includes</tt>. 

<item><bf/VerifyOS/ displays the detected operating system version. If
the numbers shown do not match your system, you probably need to set
them manually in <tt>host.def</tt> and report the problem to
XFree86@XFree86.org. 
</itemize>

<verb>
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/BUILD.sgml,v 3.5 2001/08/10 16:38:10 dawes Exp $
</verb>

</article>