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

<article>
<title>Building XFree86&reg; from a Source Distribution
<author>David Dawes, Matthieu Herrb
<Date>16 March 2005

<ident>
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/BUILD.sgml,v 3.20 2006/04/12 01:39:22 dawes Exp $
</ident>

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

<toc>

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


We recommend using gcc to build XFree86, but XFree86 generally builds
with the native compiler for each OS platform.

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

The recommended way of getting the XFree86 &relvers; source is to
obtain it directly from the XFree86 CVS repository.  There are several
ways of doing that, and they are described at our <url name="CVS web page"
url="http://www.xfree86.org/cvs/">.

The CVS tag for this release is "<tt>&reltag;</tt>".  <![ %fullrel; [
The tag for the maintenance branch for this release is
"<tt>&relbranchtag;</tt>".]]>

<![ %notsnapshot; [
Another method of getting the XFree86 &relvers; source is to
either download the &fullrelvers; source tarballs from the XFree86 ftp
site<![ %updaterel; [ and the source patch that updates &fullrelvers; to
&relvers]]>.  The procedure for this is as follows:
<itemize>
  <item>The XFree86 &fullrelvers; source is contained in the files:

	<quote><tt>
	XFree86-&fullrelvers;-src-1.tgz<newline>
	XFree86-&fullrelvers;-src-2.tgz<newline>
	XFree86-&fullrelvers;-src-3.tgz<newline>
	XFree86-&fullrelvers;-src-4.tgz<newline>
	XFree86-&fullrelvers;-src-5.tgz<newline>
	XFree86-&fullrelvers;-src-6.tgz<newline>
	XFree86-&fullrelvers;-src-7.tgz<newline>
	</tt></quote>

	These can be found at <htmlurl
	name="ftp://ftp.xfree86.org/pub/XFree86/&fullrelvers;/source/"
	url="ftp://ftp.xfree86.org/pub/XFree86/&fullrelvers;/source/">.
	<tt>XFree86-&fullrelvers;-src-4.tgz</tt> and
	<tt>XFree86-&fullrelvers;-src-5.tgz</tt> contains the fonts.
	<tt>XFree86-&fullrelvers;-src-6.tgz</tt> contains the documentation
	source.
	<tt>XFree86-&fullrelvers;-src-7.tgz</tt> contains the
	hardcopy documentation.
	<tt>XFree86-&fullrelvers;-src-1.tgz</tt>,
	<tt>XFree86-&fullrelvers;-src-2.tgz</tt> and
	<tt>XFree86-&fullrelvers;-src-3.tgz</tt> contains everything
	else.

	If you do not need either the documentation or the fonts, then
	you need only <tt>XFree86-&fullrelvers;-src-1.tgz</tt>,
	<tt>XFree86-&fullrelvers;-src-2.tgz</tt> and
	<tt>XFree86-&fullrelvers;-src-3.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, with a similar amount being required for the
	compiled binaries):
	<quote><tt>
	gzip -d &lt; XFree86-&fullrelvers;-src-1.tgz | tar vxf -<newline>
	gzip -d &lt; XFree86-&fullrelvers;-src-2.tgz | tar vxf -<newline>
	gzip -d &lt; XFree86-&fullrelvers;-src-3.tgz | tar vxf -<newline>
	gzip -d &lt; XFree86-&fullrelvers;-src-4.tgz | tar vxf -<newline>
	gzip -d &lt; XFree86-&fullrelvers;-src-5.tgz | tar vxf -<newline>
	gzip -d &lt; XFree86-&fullrelvers;-src-6.tgz | tar vxf -<newline>
	gzip -d &lt; XFree86-&fullrelvers;-src-7.tgz | tar vxf -<newline>
	</tt></quote>

<![ %updaterel; [
  <item>A patch relative to &fullrelvers is available at
	<htmlurl
	name="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/patches/"
	url="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/patches/">.
	The patch file is <tt>&fullrelvers;-&relvers;.diff.gz</tt>.

	The patch is applied by running:
	<quote><tt>
	cd <em>the directory containing the xc directory</em><newline>
	gzip -d &lt; &fullrelvers;-&relvers;.diff.gz | patch -s -p0 -E 
	</tt>
	</quote>
	Look for the patching instructions in the "How to get XFree86"
	section of the <htmlurl name="README" url="README.html"> of 
	this release.
]]>
</itemize>

<![ %fullrel; [
Alternatively, if you already have a pristine copy of the XFree86
&prevfullrelvers; source, you can download patches from
<htmlurl name="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/patches/"
url="ftp://ftp.xfree86.org/pub/XFree86/&relvers;/patches/"> that will allow
you to convert it to &relvers;.  Information about which patch files to
download and how to apply them can be found in the "How to get XFree86"
section of the <htmlurl name="README" url="README.html"> for this release.
]]>
]]>

<![ %snapshot; [
<p>
Another method is that you download the source for the XFree86 &relvers;
snapshot as a tarball from <htmlurl
name="ftp://ftp.xfree86.org/pub/XFree86/develsnaps/XFree86-&relvers;.tar.bz2"
url="ftp://ftp.xfree86.org/pub/XFree86/develsnaps/XFree86-&relvers;.tar.bz2">.
This tarball can be extracted by running:

	<quote><tt>
	bzip2 -d &lt; XFree86-&relvers;.tar.bz2 | tar vxf -<newline>
	</tt></quote>

]]>

Each of the methods outlined above will produce one main source directory
called <tt>xc</tt>.


<sect>Configuring the source before building
<p>
In most cases it should not be necessary to configure anything before
building.

If you do want to make configuration changes, you should start by going
to the <tt>xc/config/cf</tt> directory, and copying the file
<tt>xf86site.def</tt> to <tt>host.def</tt>.  After that, read thoroughly
the the <tt>host.def</tt> file, which is heavily commented, and set
your configuration parameters. Usually you can find the default settings
by checking the <tt>.cf</tt> file(s) relevant to your OS.

A good rule of thumb is to only change that you understand, as it is
very easy to create build problems by changing the default configuration
unnecessarily.  Before making too many modifications, check the
configuration parameters specified in the <tt>xc/config/cf/README</tt>
file.

<!--
Another spot to check is a section <ref name="below" id="config_params">
 with information about configuration settings.
-->

<![ %notsnapshot; [
If you are using just the <tt>XFree86-&fullrelvers;-src-1.tgz</tt>,
<tt>XFree86-&fullrelvers;-src-2.tgz</tt> and
<tt>XFree86-&fullrelvers;-src-3.tgz</tt> parts 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>
We recommend that you use a shadow directory of symbolic links to do the
build of XFree86, because it allows you to keep the source directory
unmodified during the build process.  It has the following benefits:

<itemize>
<item>Foreign files not under CVS's control are not touched. 

<item>Greater flexibility in building XFree86 for several different
Operating Systems or hardware architectures from the same sources; shared
by read-only NFS mounts.

<item>Different configuration options can be created by putting a real
copy of the <tt>host.def</tt> file in each build tree and by customizing
it separately in each build tree, and then customizing it separately.

</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. This is often
created at the same level that the <tt>xc</tt> directory. 
<quote><tt>
cd <em>the directory containing the xc directory</em><newline>
mkdir build
</tt></quote>
<item>use the "<tt>lndir</tt>" command to make the shadow tree:
<quote><tt>
cd build<newline>
lndir ../xc
</tt></quote>
Note: You can refer to the <tt>xc</tt> directory by referencing it with an absolute
path also.
<p>
See the <htmlurl name="lndir(1)"
url="http://www.xfree86.org/&relvers;/lndir.1.html"> manual page for
details.
</itemize>
If the <tt>lndir</tt> command is not already available 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>

Occasionally there may be stale links in the build tree.  This happens 
when files in the source tree are either removed or renamed.  These stale links
can be cleaned by running the "<tt>cleanlinks</tt>" script from the build
directory (see the <htmlurl name="cleanlinks(1)" url="cleanlinks.1.html">
manual page for further details). 

Rarely will there be changes that require the build
tree to be re-created from scratch.  If you think that this may be the case,
look for build problems, which could indicate that this is the problem.  The best 
solution in this scenario is to remove the build tree,and then re-create it 
using the steps outlined above.

<sect>Building and installing the distribution
<p>
Before building the distribution, read through your  OS-specific
documentation in <tt>README</tt> file in
<tt>xc/programs/Xserver/hw/xfree86/doc</tt>.  After that go to your build
directory  which will either be the <tt>xc</tt> directory or the shadow
tree which was create previously, and run "<tt>make World"</tt>.

It is also advisable to that you redirect standard output <em>stdout</em>
and standard error output <em>stderr</em> to <tt>World.Log</tt>,  so that
you can track down problems that  might occur during the build.

<p> 
With Bourne-like shells (examples include the Bash, the Korn, and
<tt>zsh</tt> shells) use the following command:
<quote><tt>
make World &gt; World.log 2&gt;&amp;1
</tt></quote>
for C-shell variants (<tt>csh</tt>, <tt>tcsh</tt>, etc), use:
<quote><tt>
make World &gt;&amp; World.log
</tt></quote>

You can then follow the progress of the build by running:
<quote><tt>
tail -f World.log
</tt></quote>
in a terminal window. 

<p>
When the build is finished, you should check the <tt>World.Log</tt> file to
see if there were any problems.  If there were not, then install the binaries.  
By default "make World" stops when the first error is found.  To restart that 
same build process after correcting the various problems, run just 'make'.  

If Imakefiles or part of the build configuration were changed as part of 
correcting the problem, then either re-run "make World", or run "make Everything".

If instead, you want "make World" to continue past errors, then instead execute 
it as follows:

for Bourne-like shells:
<quote><tt>
make WORLDOPTS=-k World &gt; World.log 2&gt;&amp;1
</tt></quote>
for C-shell variants:
<quote><tt>
make WORLDOPTS=-k World &gt;&amp; World.log
</tt></quote>

For installation, run "<tt>make install</tt>" and "<tt>make install.man</tt>"
and ensure that there is enough space in the <tt>/usr/X11R6</tt> directory.

If instead you want to install XFree86 on a filesystem other than
<tt>/usr</tt>, make a symbolic link to <tt>/usr/X11R6</tt> before running the 
install process. 


<sect>Reconfiguring the server (using the source distribution)
<p>
If you would like to build several different sets of servers or server(s)
with a various sets of drivers then you should follow this procedure:

<enum>
<item>Ensure that the source for any new drivers is in the correct place (e.g.,
all driver source should be in a subdirectory of
<tt>xc/programs/Xserver/hw/xfree86/drivers</tt>).

<item>Change the settings of the server definitions 
in <tt>host.def</tt> 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: 
<descrip>
<tag>Everything</tag>
After a <tt>make World</tt>, <tt>make Everything</tt> replicates <tt>make
World</tt> except for the cleaning of the source tree. <tt>make
Everything</tt> very quickly rebuilds the tree after a source patch, but
there are times when it is better to force a full build by using <tt>make
World</tt>.


<tag>clean</tag>
This 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. 

<tag>distclean</tag>
This 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. 

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

<tag>depend</tag>
This 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>. 

<tag>VerifyOS</tag>
This 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
<email>XFree86@XFree86.org</email>.
</descrip>

<!--
<sect>Various Configuration settings<label id="config_params">
<p>

Fill in this section.
-->

</article>

