Date: Mon, 21 Jan 2013 08:12:36 -0800 (PST) From: Dru Lavigne <dru.lavigne@att.net> To: freebsd-doc@FreeBSD.org, bcr@FreeBSD.org Subject: Re: [patch] white space fix for handbook/kernelconfig Message-ID: <1358784756.88482.YahooMailClassic@web184901.mail.gq1.yahoo.com>
index | next in thread | raw e-mail
[-- Attachment #1 --]
--- On Sat, 1/19/13, Benedict Reuschling <bcr@FreeBSD.org> wrote:
> From: Benedict Reuschling <bcr@FreeBSD.org>
> Subject: Re: [patch] white space fix for handbook/kernelconfig
> To: freebsd-doc@FreeBSD.org
> Cc: "Dru Lavigne" <dru.lavigne@att.net>
> Date: Saturday, January 19, 2013, 9:19 PM
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Am 16.01.13 20:12, schrieb Dru Lavigne:
> > This is a whitespace fix for Chapter 9 Configuring the
> FreeBSD
> > Kernel. It does not address redundant markup and word
> errors as
> > those will go into a separate content patch.
> >
> > Cheers,
> >
> > Dru
> >
>
> The patch does not apply cleanly in my working copy - not
> even a
> single hunk succeeds. Can anyone try and report back here?
This one should apply cleanly.
Cheers,
Dru
[-- Attachment #2 --]
Index: kernelconfig/chapter.xml
===================================================================
--- kernelconfig/chapter.xml (revision 40692)
+++ kernelconfig/chapter.xml (working copy)
@@ -35,11 +35,12 @@
<secondary>building a custom kernel</secondary>
</indexterm>
- <para>The kernel is the core of the &os; operating system. It is
- responsible for managing memory, enforcing security controls,
- networking, disk access, and much more. While more and more of &os;
- becomes dynamically configurable it is still occasionally necessary to
- reconfigure and recompile your kernel.</para>
+ <para>The kernel is the core of the &os; operating system. It
+ is responsible for managing memory, enforcing security controls,
+ networking, disk access, and much more. While more and more
+ of &os; becomes dynamically configurable it is still
+ occasionally necessary to reconfigure and recompile your
+ kernel.</para>
<para>After reading this chapter, you will know:</para>
@@ -49,13 +50,13 @@
</listitem>
<listitem>
- <para>How to write a kernel configuration file, or alter an existing
- configuration file.</para>
+ <para>How to write a kernel configuration file, or alter an
+ existing configuration file.</para>
</listitem>
<listitem>
- <para>How to use the kernel configuration file to create and build a
- new kernel.</para>
+ <para>How to use the kernel configuration file to create and
+ build a new kernel.</para>
</listitem>
<listitem>
@@ -67,19 +68,20 @@
</listitem>
</itemizedlist>
- <para>All of the commands listed within this chapter by way of example
- should be executed as <username>root</username> in order to
- succeed.</para>
+ <para>All of the commands listed within this chapter by way of
+ example should be executed as <username>root</username> in
+ order to succeed.</para>
</sect1>
<sect1 id="kernelconfig-custom-kernel">
<title>Why Build a Custom Kernel?</title>
<para>Traditionally, &os; has had what is called a
- <quote>monolithic</quote> kernel. This means that the kernel was one
- large program, supported a fixed list of devices, and if you wanted to
- change the kernel's behavior then you had to compile a new kernel, and
- then reboot your computer with the new kernel.</para>
+ <quote>monolithic</quote> kernel. This means that the kernel
+ was one large program, supported a fixed list of devices, and
+ if you wanted to change the kernel's behavior then you had to
+ compile a new kernel, and then reboot your computer with the
+ new kernel.</para>
<para>Today, &os; is rapidly moving to a model where much of the
kernel's functionality is contained in modules which can be
@@ -90,41 +92,43 @@
necessary when the kernel was originally compiled. This is
known as a modular kernel.</para>
- <para>Despite this, it is still necessary to carry out some static kernel
- configuration. In some cases this is because the functionality is so
- tied to the kernel that it can not be made dynamically loadable. In
- others it may simply be because no one has yet taken the time to write a
- dynamic loadable kernel module for that functionality.</para>
+ <para>Despite this, it is still necessary to carry out some
+ static kernel configuration. In some cases this is because
+ the functionality is so tied to the kernel that it can not be
+ made dynamically loadable. In others it may simply be because
+ no one has yet taken the time to write a dynamic loadable kernel
+ module for that functionality.</para>
- <para>Building a custom kernel is one of the most important rites of
- passage for advanced BSD users. This process, while
+ <para>Building a custom kernel is one of the most important rites
+ of passage for advanced BSD users. This process, while
time consuming, will provide many benefits to your &os; system.
- Unlike the <filename>GENERIC</filename> kernel, which must support a
- wide range of hardware, a custom kernel only contains support for
- <emphasis>your</emphasis> PC's hardware. This has a number of
- benefits, such as:</para>
+ Unlike the <filename>GENERIC</filename> kernel, which must
+ support a wide range of hardware, a custom kernel only contains
+ support for <emphasis>your</emphasis> PC's hardware. This has
+ a number of benefits, such as:</para>
<itemizedlist>
<listitem>
- <para>Faster boot time. Since the kernel will only probe the
- hardware you have on your system, the time it takes your system to
- boot can decrease dramatically.</para>
+ <para>Faster boot time. Since the kernel will only probe
+ the hardware you have on your system, the time it takes
+ your system to boot can decrease dramatically.</para>
</listitem>
<listitem>
- <para>Lower memory usage. A custom kernel often uses less memory
- than the <filename>GENERIC</filename> kernel by omitting unused
- features and device drivers. This is important because the kernel
- code remains resident in physical memory at all times, preventing
- that memory from being used by applications.
- For this reason, a custom kernel is especially useful
- on a system with a small amount of RAM.</para>
+ <para>Lower memory usage. A custom kernel often uses less
+ memory than the <filename>GENERIC</filename> kernel by
+ omitting unused features and device drivers. This is
+ important because the kernel code remains resident in
+ physical memory at all times, preventing that memory from
+ being used by applications. For this reason, a custom
+ kernel is especially useful on a system with a small amount
+ of RAM.</para>
</listitem>
<listitem>
- <para>Additional hardware support. A custom kernel allows you to
- add in support for devices which are not
- present in the <filename>GENERIC</filename> kernel, such as
+ <para>Additional hardware support. A custom kernel allows
+ you to add in support for devices which are not present
+ in the <filename>GENERIC</filename> kernel, such as
sound cards.</para>
</listitem>
</itemizedlist>
@@ -142,11 +146,11 @@
</sect1info>
<title>Finding the System Hardware</title>
- <para>Before venturing into kernel configuration, it would be wise
- to get an inventory of the machine's hardware. In cases where
- &os; is not the primary operating system, the inventory list may
- easily be created by viewing the current operating system
- configuration. For example, µsoft;'s
+ <para>Before venturing into kernel configuration, it would be
+ wise to get an inventory of the machine's hardware. In cases
+ where &os; is not the primary operating system, the inventory
+ list may easily be created by viewing the current operating
+ system configuration. For example, µsoft;'s
<application>Device Manager</application> normally contains
important information about installed devices. The
<application>Device Manager</application> is located in the
@@ -162,10 +166,11 @@
<para>If another operating system does not exist on the machine,
the administrator must find this information out manually. One
method is using the &man.dmesg.8; utility and the &man.man.1;
- commands. Most device drivers on &os; have a manual page, listing
- supported hardware, and during the boot probe, found hardware
- will be listed. For example, the following lines indicate that
- the <devicename>psm</devicename> driver found a mouse:</para>
+ commands. Most device drivers on &os; have a manual page,
+ listing supported hardware, and during the boot probe, found
+ hardware will be listed. For example, the following lines
+ indicate that the <devicename>psm</devicename> driver found
+ a mouse:</para>
<programlisting>psm0: <PS/2 Mouse> irq 12 on atkbdc0
psm0: [GIANT-LOCKED]
@@ -194,8 +199,8 @@
<command>pciconf <option>-lv</option></command> shows that the
<devicename>ath</devicename> driver located a wireless Ethernet
device. Using
- <command>man <replaceable>ath</replaceable></command> will return
- the &man.ath.4; manual page.</para>
+ <command>man <replaceable>ath</replaceable></command> will
+ return the &man.ath.4; manual page.</para>
<para>The <option>-k</option> flag, when passed to &man.man.1;
can also be used to provide useful information. From the
@@ -209,12 +214,13 @@
<programlisting>ath(4) - Atheros IEEE 802.11 wireless network driver
ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting>
- <para>Armed with a hardware inventory list, the process of building
- a custom kernel should appear less daunting.</para>
+ <para>Armed with a hardware inventory list, the process of
+ building a custom kernel should appear less daunting.</para>
</sect1>
<sect1 id="kernelconfig-modules">
<title>Kernel Drivers, Subsystems, and Modules</title>
+
<indexterm>
<primary>kernel</primary>
<secondary>drivers / modules / subsystems</secondary>
@@ -238,30 +244,33 @@
if_ath_load="YES"</programlisting>
- <para>As instructed, adding the <literal>if_ath_load="YES"</literal>
- line to the <filename>/boot/loader.conf</filename> file will
+ <para>As instructed, adding the
+ <literal>if_ath_load="YES"</literal> line to the
+ <filename>/boot/loader.conf</filename> file will
enable loading this module dynamically at boot time.</para>
- <para>In some cases; however, there is no associated module. This
- is mostly true for certain subsystems and very important drivers,
- for instance, the fast file system (<acronym>FFS</acronym>) is a
- required option in the kernel. As is network support (INET).
- Unfortunately the only way to tell if a driver is required is to
- check for the module itself.</para>
+ <para>In some cases; however, there is no associated module.
+ This is mostly true for certain subsystems and very important
+ drivers, for instance, the fast file system
+ (<acronym>FFS</acronym>) is a required option in the kernel.
+ As is network support (INET). Unfortunately the only way to
+ tell if a driver is required is to check for the module
+ itself.</para>
<warning>
<para>It is easy to remove support for a
- device or option and end up with a broken kernel. For example, if
- the &man.ata.4; driver is removed from the kernel configuration
- file, a system using <acronym>ATA</acronym> disk drivers may
- not boot without the module added to
- <filename>loader.conf</filename>. When in doubt, check for
- the module and then just leave support in the kernel.</para>
+ device or option and end up with a broken kernel. For
+ example, if the &man.ata.4; driver is removed from the kernel
+ configuration file, a system using <acronym>ATA</acronym>
+ disk drivers may not boot without the module added to
+ <filename>loader.conf</filename>. When in doubt, check for
+ the module and then just leave support in the kernel.</para>
</warning>
</sect1>
<sect1 id="kernelconfig-building">
<title>Building and Installing a Custom Kernel</title>
+
<indexterm>
<primary>kernel</primary>
<secondary>building / installing</secondary>
@@ -272,36 +281,38 @@
to build the kernel.</para>
</note>
- <para>First, let us take a quick tour of the kernel build directory.
- All directories mentioned will be relative to the main
- <filename>/usr/src/sys</filename> directory, which is also
- accessible through the path name <filename>/sys</filename>. There are a
- number of subdirectories here representing different parts of the
- kernel, but the most important for our purposes are
- <filename><replaceable>arch</replaceable>/conf</filename>, where you
- will edit your custom kernel configuration, and
- <filename>compile</filename>, which is the staging area where your
- kernel will be built. <replaceable>arch</replaceable> represents
- one of <filename>i386</filename>,
+ <para>First, let us take a quick tour of the kernel build
+ directory. All directories mentioned will be relative to the
+ main <filename>/usr/src/sys</filename> directory, which is
+ also accessible through the path name <filename>/sys</filename>.
+ There are a number of subdirectories here representing different
+ parts of the kernel, but the most important for our purposes
+ are <filename><replaceable>arch</replaceable>/conf</filename>,
+ where you will edit your custom kernel configuration, and
+ <filename>compile</filename>, which is the staging area where
+ your kernel will be built. <replaceable>arch</replaceable>
+ represents one of <filename>i386</filename>,
<filename>amd64</filename>, <filename>ia64</filename>,
- <filename>powerpc</filename>, <filename>sparc64</filename>, or
- <filename>pc98</filename> (an alternative development branch of PC
- hardware, popular in Japan). Everything inside a particular
- architecture's directory deals with that architecture only; the rest
- of the code is machine independent code common to all platforms to which
- &os; could potentially be ported. Notice the logical organization of the
- directory structure, with each supported device, file system, and
- option in its own subdirectory.</para>
+ <filename>powerpc</filename>, <filename>sparc64</filename>,
+ or <filename>pc98</filename> (an alternative development branch
+ of PC hardware, popular in Japan). Everything inside a
+ particular architecture's directory deals with that architecture
+ only; the rest of the code is machine independent code common
+ to all platforms to which &os; could potentially be ported.
+ Notice the logical organization of the directory structure,
+ with each supported device, file system, and option in its
+ own subdirectory.</para>
- <para>The examples in this chapter assume that you are using the i386
- architecture. If your system has a different architecture you need
- to change the path names accordingly.</para>
+ <para>The examples in this chapter assume that you are using
+ the i386 architecture. If your system has a different
+ architecture you need to change the path names
+ accordingly.</para>
<note>
<para>If the directory <filename>/usr/src/</filename> does not
- exist on your system (or if it is empty), then the sources have
- not been installed. The easiest way to install the full source
- is to use &man.csup.1; as described in <xref
+ exist on your system (or if it is empty), then the sources
+ have not been installed. The easiest way to install the full
+ source is to use &man.csup.1; as described in <xref
linkend="synching"/>. You should also create a symlink to
<filename class="directory">/usr/src/sys/</filename>:</para>
@@ -309,30 +320,34 @@
</note>
<para>Next, change to the
- <filename><replaceable>arch</replaceable>/conf</filename> directory
- and copy the <filename>GENERIC</filename> configuration file to the
- name you want to give your kernel. For example:</para>
+ <filename><replaceable>arch</replaceable>/conf</filename>
+ directory and copy the <filename>GENERIC</filename>
+ configuration file to the name you want to give your kernel.
+ For example:</para>
<screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen>
- <para>Traditionally, this name is in all capital letters and, if you
- are maintaining multiple &os; machines with different hardware,
- it is a good idea to name it after your machine's hostname. We will
- call it <filename><replaceable>MYKERNEL</replaceable></filename> for the
- purpose of this example.</para>
+ <para>Traditionally, this name is in all capital letters and,
+ if you are maintaining multiple &os; machines with different
+ hardware, it is a good idea to name it after your machine's
+ hostname. We will call it
+ <filename><replaceable>MYKERNEL</replaceable></filename> for
+ the purpose of this example.</para>
<tip>
<para>Storing your kernel configuration file directly under
<filename>/usr/src</filename> can be a bad idea. If you are
experiencing problems it can be tempting to just delete
- <filename>/usr/src</filename> and start again. After doing this,
- it usually only takes a few seconds for
+ <filename>/usr/src</filename> and start again. After doing
+ this, it usually only takes a few seconds for
you to realize that you have deleted your custom kernel
- configuration file. Also, do not edit <filename>GENERIC</filename>
- directly, as it may get overwritten the next time you
- <link linkend="updating-upgrading">update your source tree</link>, and
- your kernel modifications will be lost.</para>
+ configuration file. Also, do not edit
+ <filename>GENERIC</filename> directly, as it may get
+ overwritten the next time you
+ <link linkend="updating-upgrading">update your source
+ tree</link>,
+ and your kernel modifications will be lost.</para>
<para>You might want to keep your kernel configuration file
elsewhere, and then create a symbolic link to the file in
@@ -347,37 +362,40 @@
&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
</tip>
- <para>Now, edit <filename><replaceable>MYKERNEL</replaceable></filename>
- with your favorite text editor. If you are just starting out, the only
- editor available will probably be <application>vi</application>, which
- is too complex to explain here, but is covered well in many books in
- the <link linkend="bibliography">bibliography</link>. However, &os; does
- offer an easier editor called <application>ee</application> which, if
- you are a beginner, should be your editor of choice. Feel free to
- change the comment lines at the top to reflect your configuration or
- the changes you have made to differentiate it from
- <filename>GENERIC</filename>.</para>
+ <para>Now, edit
+ <filename><replaceable>MYKERNEL</replaceable></filename>
+ with your favorite text editor. If you are just starting out,
+ the only editor available will probably be
+ <application>vi</application>, which is too complex to explain
+ here, but is covered well in many books in the <link
+ linkend="bibliography">bibliography</link>. However, &os;
+ does offer an easier editor called <application>ee</application>
+ which, if you are a beginner, should be your editor of choice.
+ Feel free to change the comment lines at the top to reflect
+ your configuration or the changes you have made to differentiate
+ it from <filename>GENERIC</filename>.</para>
<indexterm><primary>SunOS</primary></indexterm>
<para>If you have built a kernel under &sunos; or some other BSD
- operating system, much of this file will be very familiar to you.
- If you are coming from some other operating system such as DOS, on
- the other hand, the <filename>GENERIC</filename> configuration file
- might seem overwhelming to you, so follow the descriptions in the
+ operating system, much of this file will be very familiar to
+ you. If you are coming from some other operating system such
+ as DOS, on the other hand, the <filename>GENERIC</filename>
+ configuration file might seem overwhelming to you, so follow
+ the descriptions in the
<link linkend="kernelconfig-config">Configuration File</link>
section slowly and carefully.</para>
<note>
<para>If you <link
- linkend="updating-upgrading">sync your source tree</link> with the
- latest sources of the &os; project,
- be sure to always check the file
- <filename>/usr/src/UPDATING</filename> before you perform any update
- steps. This file describes any important issues or areas
- requiring special attention within the updated source code.
- <filename>/usr/src/UPDATING</filename> always matches
- your version of the &os; source, and is therefore more up to date
- with new information than this handbook.</para>
+ linkend="updating-upgrading">sync your source tree</link>
+ with the latest sources of the &os; project, be sure to always
+ check the file <filename>/usr/src/UPDATING</filename> before
+ you perform any update steps. This file describes any
+ important issues or areas requiring special attention within
+ the updated source code.
+ <filename>/usr/src/UPDATING</filename> always matches
+ your version of the &os; source, and is therefore more up
+ to date with new information than this handbook.</para>
</note>
<para>You must now compile the source code for the kernel.</para>
@@ -386,13 +404,13 @@
<title>Building a Kernel</title>
<note>
- <para>It is required to have the full &os; source tree installed
- to build the kernel.</para>
+ <para>It is required to have the full &os; source tree
+ installed to build the kernel.</para>
</note>
<step>
<para>Change to the <filename
- class="directory">/usr/src</filename> directory:</para>
+ class="directory">/usr/src</filename> directory:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
</step>
@@ -412,10 +430,11 @@
<tip>
<para>By default, when you build a custom kernel,
- <emphasis>all</emphasis> kernel modules will be rebuilt as well.
- If you want to update a kernel faster or to build only custom
- modules, you should edit <filename>/etc/make.conf</filename>
- before starting to build the kernel:</para>
+ <emphasis>all</emphasis> kernel modules will be rebuilt as
+ well. If you want to update a kernel faster or to build only
+ custom modules, you should edit
+ <filename>/etc/make.conf</filename> before starting to build
+ the kernel:</para>
<programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
@@ -424,10 +443,10 @@
<programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting>
- <para>This variable sets up a list of top level modules to exclude
- from the build process. For other variables which you may find useful
- in the process of building kernel, refer to &man.make.conf.5;
- manual page.</para>
+ <para>This variable sets up a list of top level modules to
+ exclude from the build process. For other variables which
+ you may find useful in the process of building kernel, refer
+ to &man.make.conf.5; manual page.</para>
</tip>
<indexterm>
@@ -435,24 +454,27 @@
</indexterm>
<para>The new kernel will be copied to the <filename
- class="directory">/boot/kernel</filename> directory as
- <filename>/boot/kernel/kernel</filename> and the old kernel will be moved
- to <filename>/boot/kernel.old/kernel</filename>. Now, shutdown the
- system and reboot to use your new kernel. If something goes wrong, there
- are some <link linkend="kernelconfig-trouble">troubleshooting</link>
- instructions at the end of this chapter that you may find useful. Be
- sure to read the section which explains how to recover in case your new
- kernel <link linkend="kernelconfig-noboot">does not boot</link>.</para>
+ class="directory">/boot/kernel</filename> directory as
+ <filename>/boot/kernel/kernel</filename> and the old kernel
+ will be moved to <filename>/boot/kernel.old/kernel</filename>.
+ Now, shutdown the system and reboot to use your new kernel.
+ If something goes wrong, there are some <link
+ linkend="kernelconfig-trouble">troubleshooting</link>
+ instructions at the end of this chapter that you may find
+ useful. Be sure to read the section which explains how to
+ recover in case your new kernel <link
+ linkend="kernelconfig-noboot">does not boot</link>.</para>
<note>
<para>Other files relating to the boot process, such as the boot
&man.loader.8; and configuration are stored in
<filename>/boot</filename>. Third party or custom modules
- can be placed in <filename class="directory">/boot/kernel</filename>,
- although users should be aware that keeping modules in sync with the
- compiled kernel is very important. Modules not intended
- to run with the compiled kernel may result in instability
- or incorrectness.</para>
+ can be placed in <filename
+ class="directory">/boot/kernel</filename>,
+ although users should be aware that keeping modules in sync
+ with the compiled kernel is very important. Modules not
+ intended to run with the compiled kernel may result in
+ instability or incorrectness.</para>
</note>
</sect1>
@@ -467,6 +489,7 @@
</authorgroup>
</sect1info>
<title>The Configuration File</title>
+
<indexterm>
<primary>kernel</primary>
<secondary>NOTES</secondary>
@@ -484,19 +507,21 @@
ignored. The following sections describe each keyword, in
the order they are listed in <filename>GENERIC</filename>.
<anchor
- id="kernelconfig-options"/> For an exhaustive list of architecture
- dependent options and devices, see the <filename>NOTES</filename>
- file in the same directory as the <filename>GENERIC</filename> file. For
- architecture independent options, see
+ id="kernelconfig-options"/> For an exhaustive list of
+ architecture dependent options and devices, see the
+ <filename>NOTES</filename> file in the same directory as the
+ <filename>GENERIC</filename> file. For architecture independent
+ options, see
<filename>/usr/src/sys/conf/NOTES</filename>.</para>
<para>An <literal>include</literal> directive is
available for use in configuration files. This allows another
- configuration file to be logically included in the current one, making
- it easy to maintain small changes relative to an existing file. For
- example, if you require a <filename>GENERIC</filename> kernel with
- only a small number of additional options or drivers, this allows you
- to maintain only a delta with respect to GENERIC:</para>
+ configuration file to be logically included in the current
+ one, making it easy to maintain small changes relative to an
+ existing file. For example, if you require a
+ <filename>GENERIC</filename> kernel with only a small number
+ of additional options or drivers, this allows you to maintain
+ only a delta with respect to GENERIC:</para>
<programlisting>include GENERIC
ident MYKERNEL
@@ -504,19 +529,19 @@
options IPFIREWALL
options DUMMYNET
options IPFIREWALL_DEFAULT_TO_ACCEPT
-options IPDIVERT
-</programlisting>
+options IPDIVERT</programlisting>
- <para>Many administrators will find that this model offers significant
- benefits over the historic writing of configuration files from scratch:
- the local configuration file will express only local differences from
- a <filename>GENERIC</filename> kernel and as upgrades are performed,
- new features added to <filename>GENERIC</filename> will be added to the
- local kernel unless specifically prevented using
- <literal>nooptions</literal> or <literal>nodevice</literal>. The
- remainder of this chapter addresses the contents of a typical
- configuration file and the role various options and devices
- play.</para>
+ <para>Many administrators will find that this model offers
+ significant benefits over the historic writing of configuration
+ files from scratch: the local configuration file will express
+ only local differences from a <filename>GENERIC</filename>
+ kernel and as upgrades are performed, new features added to
+ <filename>GENERIC</filename> will be added to the local kernel
+ unless specifically prevented using
+ <literal>nooptions</literal> or <literal>nodevice</literal>.
+ The remainder of this chapter addresses the contents of a
+ typical configuration file and the role various options and
+ devices play.</para>
<note>
<para>To build a file which contains all available options,
@@ -531,9 +556,10 @@
<secondary>configuration file</secondary>
</indexterm>
- <para>The following is an example of the <filename>GENERIC</filename>
- kernel configuration file with various additional comments where needed
- for clarity. This example should match your copy in
+ <para>The following is an example of the
+ <filename>GENERIC</filename> kernel configuration file with
+ various additional comments where needed for clarity. This
+ example should match your copy in
<filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename>
fairly closely.</para>
@@ -559,13 +585,13 @@
cpu I686_CPU</programlisting>
<para>The above option specifies the type of CPU you have in your
- system. You may have multiple instances of the CPU line (if, for
- example, you are not sure whether you should use
+ system. You may have multiple instances of the CPU line (if,
+ for example, you are not sure whether you should use
<literal>I586_CPU</literal> or <literal>I686_CPU</literal>),
but for a custom kernel it is best to specify only the CPU
- you have. If you are unsure of your CPU type, you can check the
- <filename>/var/run/dmesg.boot</filename> file to view your boot
- messages.</para>
+ you have. If you are unsure of your CPU type, you can check
+ the <filename>/var/run/dmesg.boot</filename> file to view your
+ boot messages.</para>
<indexterm>
<primary>kernel options</primary>
@@ -576,12 +602,13 @@
<para>This is the identification of the kernel. You should change
this to whatever you named your kernel,
- i.e., <literal><replaceable>MYKERNEL</replaceable></literal> if you have
- followed the instructions of the previous examples. The value you put
- in the <literal>ident</literal> string will print when you boot up the
- kernel, so it is useful to give the new kernel a different name if you
- want to keep it separate from your usual kernel (e.g., you want to
- build an experimental kernel).</para>
+ i.e., <literal><replaceable>MYKERNEL</replaceable></literal>
+ if you have followed the instructions of the previous examples.
+ The value you put in the <literal>ident</literal> string will
+ print when you boot up the kernel, so it is useful to give the
+ new kernel a different name if you want to keep it separate
+ from your usual kernel (e.g., you want to build an experimental
+ kernel).</para>
<programlisting>#To statically compile in device wiring instead of /boot/device.hints
#hints "GENERIC.hints" # Default places to look for devices.</programlisting>
@@ -613,14 +640,15 @@
<para>Allows threads that are in the kernel to be preempted
by higher priority threads. It helps with interactivity and
- allows interrupt threads to run sooner rather than waiting.</para>
+ allows interrupt threads to run sooner rather than
+ waiting.</para>
<programlisting>options INET # InterNETworking</programlisting>
- <para>Networking support. Leave this in, even if you do not plan to
- be connected to a network. Most programs require at least loopback
- networking (i.e., making network connections within your PC), so
- this is essentially mandatory.</para>
+ <para>Networking support. Leave this in, even if you do not
+ plan to be connected to a network. Most programs require at
+ least loopback networking (i.e., making network connections
+ within your PC), so this is essentially mandatory.</para>
<programlisting>options INET6 # IPv6 communications protocols</programlisting>
@@ -628,18 +656,18 @@
<programlisting>options FFS # Berkeley Fast Filesystem</programlisting>
- <para>This is the basic hard drive file system. Leave it in if you
- boot from the hard disk.</para>
+ <para>This is the basic hard drive file system. Leave it in if
+ you boot from the hard disk.</para>
<programlisting>options SOFTUPDATES # Enable FFS Soft Updates support</programlisting>
<para>This option enables Soft Updates in the kernel, this will
help speed up write access on the disks. Even when this
functionality is provided by the kernel, it must be turned on
- for specific disks. Review the output from &man.mount.8; to see
- if Soft Updates is enabled for your system disks. If you do not
- see the <literal>soft-updates</literal> option then you will
- need to activate it using the &man.tunefs.8; (for existing
+ for specific disks. Review the output from &man.mount.8; to
+ see if Soft Updates is enabled for your system disks. If you
+ do not see the <literal>soft-updates</literal> option then you
+ will need to activate it using the &man.tunefs.8; (for existing
file systems) or &man.newfs.8; (for new file systems)
commands.</para>
@@ -647,12 +675,13 @@
<para>This option enables kernel support
for access control lists. This relies on the use of extended
- attributes and <acronym>UFS2</acronym>, and the feature is described
- in detail in <xref linkend="fs-acl"/>. <acronym>ACL</acronym>s are
- enabled by default and should not be
- disabled in the kernel if they have been used previously on a file
- system, as this will remove the access control lists, changing the
- way files are protected in unpredictable ways.</para>
+ attributes and <acronym>UFS2</acronym>, and the feature is
+ described in detail in <xref linkend="fs-acl"/>.
+ <acronym>ACL</acronym>s are enabled by default and should not
+ be disabled in the kernel if they have been used previously
+ on a file system, as this will remove the access control lists,
+ changing the way files are protected in unpredictable
+ ways.</para>
<programlisting>options UFS_DIRHASH # Improve performance on big directories</programlisting>
@@ -680,9 +709,9 @@
options NFSSERVER # Network Filesystem Server
options NFS_ROOT # NFS usable as /, requires NFSCLIENT</programlisting>
- <para>The network file system. Unless you plan to mount partitions
- from a &unix; file server over TCP/IP, you can comment these
- out.</para>
+ <para>The network file system. Unless you plan to mount
+ partitions from a &unix; file server over TCP/IP, you can
+ comment these out.</para>
<indexterm>
<primary>kernel options</primary>
@@ -690,10 +719,11 @@
</indexterm>
<programlisting>options MSDOSFS # MSDOS Filesystem</programlisting>
- <para>The &ms-dos; file system. Unless you plan to mount a DOS formatted
- hard drive partition at boot time, you can safely comment this out.
- It will be automatically loaded the first time you mount a DOS
- partition, as described above. Also, the excellent
+ <para>The &ms-dos; file system. Unless you plan to mount a DOS
+ formatted hard drive partition at boot time, you can safely
+ comment this out. It will be automatically loaded the first
+ time you mount a DOS partition, as described above. Also,
+ the excellent
<filename role="package">emulators/mtools</filename> software
allows you to access DOS floppies without having to mount and
unmount them (and does not require <literal>MSDOSFS</literal> at
@@ -701,10 +731,11 @@
<programlisting>options CD9660 # ISO 9660 Filesystem</programlisting>
- <para>The ISO 9660 file system for CDROMs. Comment it out if you do
- not have a CDROM drive or only mount data CDs occasionally (since it
- will be dynamically loaded the first time you mount a data CD).
- Audio CDs do not need this file system.</para>
+ <para>The ISO 9660 file system for CDROMs. Comment it out if
+ you do not have a CDROM drive or only mount data CDs
+ occasionally (since it will be dynamically loaded the first
+ time you mount a data CD). Audio CDs do not need this file
+ system.</para>
<programlisting>options PROCFS # Process filesystem (requires PSEUDOFS)</programlisting>
@@ -719,8 +750,8 @@
<programlisting>options PSEUDOFS # Pseudo-filesystem framework</programlisting>
- <para>Kernels making use of <literal>PROCFS</literal> must also
- include support for <literal>PSEUDOFS</literal>.</para>
+ <para>Kernels making use of <literal>PROCFS</literal> must
+ also include support for <literal>PSEUDOFS</literal>.</para>
<programlisting>options GEOM_PART_GPT # GUID Partition Tables.</programlisting>
@@ -732,8 +763,8 @@
<programlisting>options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
- <para>Compatibility with 4.3BSD. Leave this in; some programs will
- act strangely if you comment this out.</para>
+ <para>Compatibility with 4.3BSD. Leave this in; some programs
+ will act strangely if you comment this out.</para>
<programlisting>options COMPAT_FREEBSD4 # Compatible with &os;4</programlisting>
@@ -742,34 +773,35 @@
that use older system call interfaces. It is recommended that
this option be used on all &i386; systems that may
run older applications; platforms that gained support only in
- 5.X, such as ia64 and &sparc64;, do not require this option.</para>
+ 5.X, such as ia64 and &sparc64;, do not require this
+ option.</para>
<programlisting>options COMPAT_FREEBSD5 # Compatible with &os;5</programlisting>
<para>This option is required to
- support applications compiled on &os; 5.X versions that use
- &os; 5.X system call interfaces.</para>
+ support applications compiled on &os; 5.X versions that
+ use &os; 5.X system call interfaces.</para>
<programlisting>options COMPAT_FREEBSD6 # Compatible with &os;6</programlisting>
<para>This option is required to
- support applications compiled on &os; 6.X versions that use
- &os; 6.X system call interfaces.</para>
+ support applications compiled on &os; 6.X versions that
+ use &os; 6.X system call interfaces.</para>
<programlisting>options COMPAT_FREEBSD7 # Compatible with &os;7</programlisting>
<para>This option is required on &os; 8 and above to
- support applications compiled on &os; 7.X versions that use
- &os; 7.X system call interfaces.</para>
+ support applications compiled on &os; 7.X versions that
+ use &os; 7.X system call interfaces.</para>
<programlisting>options SCSI_DELAY=5000 # Delay (in ms) before probing SCSI</programlisting>
<para>This causes the kernel to pause for 5 seconds before probing
- each SCSI device in your system. If you only have IDE hard drives,
- you can ignore this, otherwise you can try to lower this
- number, to speed up booting. Of course, if
- you do this and &os; has trouble recognizing your SCSI devices,
- you will have to raise it again.</para>
+ each SCSI device in your system. If you only have IDE hard
+ drives, you can ignore this, otherwise you can try to lower
+ this number, to speed up booting. Of course, if you do this
+ and &os; has trouble recognizing your SCSI devices, you will
+ have to raise it again.</para>
<programlisting>options KTRACE # ktrace(1) support</programlisting>
@@ -778,11 +810,11 @@
<programlisting>options SYSVSHM # SYSV-style shared memory</programlisting>
- <para>This option provides for System V shared memory. The most
- common use of this is the XSHM extension in X, which many
- graphics-intensive programs will automatically take advantage of for
- extra speed. If you use X, you will definitely want to include
- this.</para>
+ <para>This option provides for System V shared memory.
+ The most common use of this is the XSHM extension in X, which
+ many graphics-intensive programs will automatically take
+ advantage of for extra speed. If you use X, you will definitely
+ want to include this.</para>
<programlisting>options SYSVMSG # SYSV-style message queues</programlisting>
@@ -791,12 +823,13 @@
<programlisting>options SYSVSEM # SYSV-style semaphores</programlisting>
- <para>Support for System V semaphores. Less commonly used but only
- adds a few hundred bytes to the kernel.</para>
+ <para>Support for System V semaphores. Less commonly used
+ but only adds a few hundred bytes to the kernel.</para>
<note>
- <para>The <option>-p</option> option of the &man.ipcs.1; command will
- list any processes using each of these System V facilities.</para>
+ <para>The <option>-p</option> option of the &man.ipcs.1;
+ command will list any processes using each of these
+ System V facilities.</para>
</note>
<programlisting>options _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions</programlisting>
@@ -807,30 +840,32 @@
<programlisting>options KBD_INSTALL_CDEV # install a CDEV entry in /dev</programlisting>
- <para>This option is required to allow the creation of keyboard device
- nodes in <filename>/dev</filename>.</para>
+ <para>This option is required to allow the creation of keyboard
+ device nodes in <filename>/dev</filename>.</para>
<programlisting>options ADAPTIVE_GIANT # Giant mutex is adaptive.</programlisting>
- <para>Giant is the name of a mutual exclusion mechanism (a sleep mutex)
- that protects a large set of kernel resources. Today, this is an
- unacceptable performance bottleneck which is actively being replaced
- with locks that protect individual resources. The
- <literal>ADAPTIVE_GIANT</literal> option causes Giant to be included
- in the set of mutexes adaptively spun on. That is, when a thread
- wants to lock the Giant mutex, but it is already locked by a thread
- on another CPU, the first thread will keep running and wait for the
- lock to be released. Normally, the thread would instead go back to
- sleep and wait for its next chance to run. If you are not sure,
- leave this in.</para>
+ <para>Giant is the name of a mutual exclusion mechanism (a
+ sleep mutex)that protects a large set of kernel resources.
+ Today, this is an unacceptable performance bottleneck which
+ is actively being replaced with locks that protect individual
+ resources. The <literal>ADAPTIVE_GIANT</literal> option causes
+ Giant to be included in the set of mutexes adaptively spun on.
+ That is, when a thread wants to lock the Giant mutex, but it
+ is already locked by a thread on another CPU, the first thread
+ will keep running and wait for the lock to be released.
+ Normally, the thread would instead go back to sleep and wait
+ for its next chance to run. If you are not sure, leave this
+ in.</para>
<note>
- <para>Note that on &os; 8.0-RELEASE and later versions, all mutexes are
- adaptive by default, unless explicitly set to non-adaptive by
- compiling with the <literal>NO_ADAPTIVE_MUTEXES</literal> option. As
- a result, Giant is adaptive by default now, and the
- <literal>ADAPTIVE_GIANT</literal> option has been removed from the
- kernel configuration.</para>
+ <para>Note that on &os; 8.0-RELEASE and later versions, all
+ mutexes are adaptive by default, unless explicitly set to
+ non-adaptive by compiling with the
+ <literal>NO_ADAPTIVE_MUTEXES</literal> option. As a result,
+ Giant is adaptive by default now, and the
+ <literal>ADAPTIVE_GIANT</literal> option has been removed
+ from the kernel configuration.</para>
</note>
<indexterm>
@@ -839,10 +874,11 @@
</indexterm>
<programlisting>device apic # I/O APIC</programlisting>
- <para>The apic device enables the use of the I/O APIC for interrupt
- delivery. The apic device can be used in both UP and SMP kernels, but
- is required for SMP kernels. Add <literal>options SMP</literal> to
- include support for multiple processors.</para>
+ <para>The apic device enables the use of the I/O APIC for
+ interrupt delivery. The apic device can be used in both UP
+ and SMP kernels, but is required for SMP kernels. Add
+ <literal>options SMP</literal> to include support for multiple
+ processors.</para>
<note>
<para>The apic device exists only on the i386 architecture, this
@@ -853,8 +889,8 @@
<programlisting>device eisa</programlisting>
<para>Include this if you have an EISA motherboard. This enables
- auto-detection and configuration support for all devices on the EISA
- bus.</para>
+ auto-detection and configuration support for all devices on
+ the EISA bus.</para>
<programlisting>device pci</programlisting>
@@ -870,35 +906,35 @@
<programlisting># ATA and ATAPI devices
device ata</programlisting>
- <para>This driver supports all ATA and ATAPI devices. You only need
- one <literal>device ata</literal> line for the kernel to detect all
- PCI ATA/ATAPI devices on modern machines.</para>
+ <para>This driver supports all ATA and ATAPI devices. You only
+ need one <literal>device ata</literal> line for the kernel to
+ detect all PCI ATA/ATAPI devices on modern machines.</para>
<programlisting>device atadisk # ATA disk drives</programlisting>
- <para>This is needed along with <literal>device ata</literal> for
- ATA disk drives.</para>
+ <para>This is needed along with <literal>device ata</literal>
+ for ATA disk drives.</para>
<programlisting>device ataraid # ATA RAID drives</programlisting>
- <para>This is needed along with <literal>device ata</literal> for ATA
- RAID drives.</para>
+ <para>This is needed along with <literal>device ata</literal>
+ for ATA RAID drives.</para>
<programlisting><anchor id="kernelconfig-atapi"/>
device atapicd # ATAPI CDROM drives</programlisting>
- <para>This is needed along with <literal>device ata</literal> for
- ATAPI CDROM drives.</para>
+ <para>This is needed along with <literal>device ata</literal>
+ for ATAPI CDROM drives.</para>
<programlisting>device atapifd # ATAPI floppy drives</programlisting>
- <para>This is needed along with <literal>device ata</literal> for
- ATAPI floppy drives.</para>
+ <para>This is needed along with <literal>device ata</literal>
+ for ATAPI floppy drives.</para>
<programlisting>device atapist # ATAPI tape drives</programlisting>
- <para>This is needed along with <literal>device ata</literal> for
- ATAPI tape drives.</para>
+ <para>This is needed along with <literal>device ata</literal>
+ for ATAPI tape drives.</para>
<programlisting>options ATA_STATIC_ID # Static device numbering</programlisting>
@@ -945,8 +981,9 @@
device pass # Passthrough device (direct SCSI access)
device ses # SCSI Environmental Services (and SAF-TE)</programlisting>
- <para>SCSI peripherals. Again, comment out any you do not have, or if
- you have only IDE hardware, you can remove them completely.</para>
+ <para>SCSI peripherals. Again, comment out any you do not have,
+ or if you have only IDE hardware, you can remove them
+ completely.</para>
<note>
<para>The USB &man.umass.4; driver and a few other drivers use
@@ -977,24 +1014,24 @@
device pst # Promise Supertrak SX6000
device twe # 3ware ATA RAID</programlisting>
- <para>Supported RAID controllers. If you do not have any of these,
- you can comment them out or remove them.</para>
+ <para>Supported RAID controllers. If you do not have any of
+ these, you can comment them out or remove them.</para>
<programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse
device atkbdc # AT keyboard controller</programlisting>
- <para>The keyboard controller (<literal>atkbdc</literal>) provides I/O
- services for the AT keyboard and PS/2 style pointing devices. This
- controller is required by the keyboard driver
- (<literal>atkbd</literal>) and the PS/2 pointing device driver
- (<literal>psm</literal>).</para>
+ <para>The keyboard controller (<literal>atkbdc</literal>)
+ provides I/O services for the AT keyboard and PS/2 style
+ pointing devices. This controller is required by the keyboard
+ driver (<literal>atkbd</literal>) and the PS/2 pointing device
+ driver (<literal>psm</literal>).</para>
<programlisting>device atkbd # AT keyboard</programlisting>
<para>The <literal>atkbd</literal> driver, together with
- <literal>atkbdc</literal> controller, provides access to the AT 84
- keyboard or the AT enhanced keyboard which is connected to the AT
- keyboard controller.</para>
+ <literal>atkbdc</literal> controller, provides access to the
+ AT 84 keyboard or the AT enhanced keyboard which is connected
+ to the AT keyboard controller.</para>
<programlisting>device psm # PS/2 mouse</programlisting>
@@ -1003,9 +1040,9 @@
<programlisting>device kbdmux # keyboard multiplexer</programlisting>
- <para>Basic support for keyboard multiplexing. If you do not plan
- to use more than one keyboard on the system, you can safely
- remove that line.</para>
+ <para>Basic support for keyboard multiplexing. If you do not
+ plan to use more than one keyboard on the system, you can
+ safely remove that line.</para>
<programlisting>device vga # VGA video card driver</programlisting>
@@ -1021,29 +1058,31 @@
device sc</programlisting>
<para><literal>sc</literal> is the default console driver and
- resembles a SCO console. Since most full-screen programs access the
- console through a terminal database library like
- <filename>termcap</filename>, it should not matter whether you use
- this or <literal>vt</literal>, the <literal>VT220</literal>
- compatible console driver. When you log in, set your
- <envar>TERM</envar> variable to <literal>scoansi</literal> if
- full-screen programs have trouble running under this console.</para>
+ resembles a SCO console. Since most full-screen programs
+ access the console through a terminal database library like
+ <filename>termcap</filename>, it should not matter whether
+ you use this or <literal>vt</literal>, the
+ <literal>VT220</literal> compatible console driver. When you
+ log in, set your <envar>TERM</envar> variable to
+ <literal>scoansi</literal> if full-screen programs have trouble
+ running under this console.</para>
<programlisting># Enable this for the pcvt (VT220 compatible) console driver
#device vt
#options XSERVER # support for X server on a vt console
#options FAT_CURSOR # start with block cursor</programlisting>
- <para>This is a VT220-compatible console driver, backward compatible to
- VT100/102. It works well on some laptops which have hardware
- incompatibilities with <literal>sc</literal>. Also set your
- <envar>TERM</envar> variable to <literal>vt100</literal> or
- <literal>vt220</literal> when you log in. This driver might also
- prove useful when connecting to a large number of different machines
- over the network, where <filename>termcap</filename> or
- <filename>terminfo</filename> entries for the <literal>sc</literal>
- device are often not available — <literal>vt100</literal>
- should be available on virtually any platform.</para>
+ <para>This is a VT220-compatible console driver, backward
+ compatible to VT100/102. It works well on some laptops which
+ have hardware incompatibilities with <literal>sc</literal>.
+ Also set your <envar>TERM</envar> variable to
+ <literal>vt100</literal> or <literal>vt220</literal> when you
+ log in. This driver might also prove useful when connecting
+ to a large number of different machines over the network, where
+ <filename>termcap</filename> or <filename>terminfo</filename>
+ entries for the <literal>sc</literal> device are often not
+ available — <literal>vt100</literal> should be available
+ on virtually any platform.</para>
<programlisting>device agp</programlisting>
@@ -1065,8 +1104,8 @@
<programlisting># Add suspend/resume support for the i8254.
device pmtimer</programlisting>
- <para>Timer device driver for power management events, such as APM and
- ACPI.</para>
+ <para>Timer device driver for power management events, such as
+ APM and ACPI.</para>
<programlisting># PCCARD (PCMCIA) support
# PCMCIA and cardbus bridge support
@@ -1085,24 +1124,26 @@
world.</para>
<note>
- <para>If you have an internal modem on <devicename>COM4</devicename>
- and a serial port at <devicename>COM2</devicename>, you will have
- to change the IRQ of the modem to 2 (for obscure technical reasons,
- IRQ2 = IRQ 9) in order to access it
- from &os;. If you have a multiport serial card, check the
- manual page for &man.sio.4; for more information on the proper
- values to add to your <filename>/boot/device.hints</filename>.
- Some video cards (notably those based on
- S3 chips) use IO addresses in the form of
- <literal>0x*2e8</literal>, and since many cheap serial cards do
- not fully decode the 16-bit IO address space, they clash with
- these cards making the <devicename>COM4</devicename> port
- practically unavailable.</para>
+ <para>If you have an internal modem on
+ <devicename>COM4</devicename> and a serial port at
+ <devicename>COM2</devicename>, you will have to change the
+ IRQ of the modem to 2 (for obscure technical reasons,
+ IRQ2 = IRQ 9) in order to access it from &os;. If you have
+ a multiport serial card, check the manual page for &man.sio.4;
+ for more information on the proper values to add to your
+ <filename>/boot/device.hints</filename>. Some video cards
+ (notably those based on S3 chips) use IO addresses in the
+ form of <literal>0x*2e8</literal>, and since many cheap serial
+ cards do not fully decode the 16-bit IO address space, they
+ clash with these cards making the
+ <devicename>COM4</devicename> port practically
+ unavailable.</para>
- <para>Each serial port is required to have a unique IRQ (unless you
- are using one of the multiport cards where shared interrupts are
- supported), so the default IRQs for <devicename>COM3</devicename>
- and <devicename>COM4</devicename> cannot be used.</para>
+ <para>Each serial port is required to have a unique IRQ
+ (unless you are using one of the multiport cards where shared
+ interrupts are supported), so the default IRQs for
+ <devicename>COM3</devicename> and
+ <devicename>COM4</devicename> cannot be used.</para>
</note>
<programlisting># Parallel port
@@ -1119,31 +1160,32 @@
<para>Support for parallel port printers.</para>
<note>
- <para>All three of the above are required to enable parallel printer
- support.</para>
+ <para>All three of the above are required to enable parallel
+ printer support.</para>
</note>
<programlisting>device plip # TCP/IP over parallel</programlisting>
- <para>This is the driver for the parallel network interface.</para>
+ <para>This is the driver for the parallel network
+ interface.</para>
<programlisting>device ppi # Parallel port interface device</programlisting>
- <para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284
- I/O.</para>
+ <para>The general-purpose I/O (<quote>geek port</quote>) +
+ IEEE1284 I/O.</para>
<programlisting>#device vpo # Requires scbus and da</programlisting>
<indexterm><primary>zip drive</primary></indexterm>
<para>This is for an Iomega Zip drive. It requires
- <literal>scbus</literal> and <literal>da</literal> support. Best
- performance is achieved with ports in EPP 1.9 mode.</para>
+ <literal>scbus</literal> and <literal>da</literal> support.
+ Best performance is achieved with ports in EPP 1.9 mode.</para>
<programlisting>#device puc</programlisting>
- <para>Uncomment this device if you have a <quote>dumb</quote> serial
- or parallel PCI card that is supported by the &man.puc.4; glue
- driver.</para>
+ <para>Uncomment this device if you have a <quote>dumb</quote>
+ serial or parallel PCI card that is supported by the &man.puc.4;
+ glue driver.</para>
<programlisting># PCI Ethernet NICs.
device de # DEC/Intel DC21x4x (<quote>Tulip</quote>)
@@ -1152,20 +1194,20 @@
device txp # 3Com 3cR990 (<quote>Typhoon</quote>)
device vx # 3Com 3c590, 3c595 (<quote>Vortex</quote>)</programlisting>
- <para>Various PCI network card drivers. Comment out or remove any of
- these not present in your system.</para>
+ <para>Various PCI network card drivers. Comment out or remove
+ any of these not present in your system.</para>
<programlisting># PCI Ethernet NICs that use the common MII bus controller code.
# NOTE: Be sure to keep the 'device miibus' line in order to use these NICs!
device miibus # MII bus support</programlisting>
- <para>MII bus support is required for some PCI 10/100 Ethernet NICs,
- namely those which use MII-compliant transceivers or implement
- transceiver control interfaces that operate like an MII. Adding
- <literal>device miibus</literal> to the kernel config pulls in
- support for the generic miibus API and all of the PHY drivers,
- including a generic one for PHYs that are not specifically handled
- by an individual driver.</para>
+ <para>MII bus support is required for some PCI 10/100 Ethernet
+ NICs, namely those which use MII-compliant transceivers or
+ implement transceiver control interfaces that operate like an
+ MII. Adding <literal>device miibus</literal> to the kernel
+ config pulls in support for the generic miibus API and all of
+ the PHY drivers, including a generic one for PHYs that are not
+ specifically handled by an individual driver.</para>
<programlisting>device bce # Broadcom BCM5706/BCM5708 Gigabit Ethernet
device bfe # Broadcom BCM440x 10/100 Ethernet
@@ -1241,10 +1283,11 @@
<programlisting># Pseudo devices
device loop # Network loopback</programlisting>
- <para>This is the generic loopback device for TCP/IP. If you telnet
- or FTP to <hostid>localhost</hostid> (aka <hostid
- role="ipaddr">127.0.0.1</hostid>) it will come back at you through
- this device. This is <emphasis>mandatory</emphasis>.</para>
+ <para>This is the generic loopback device for TCP/IP. If you
+ telnet or FTP to <hostid>localhost</hostid> (aka <hostid
+ role="ipaddr">127.0.0.1</hostid>) it will come back at you
+ through this device. This is
+ <emphasis>mandatory</emphasis>.</para>
<programlisting>device random # Entropy device</programlisting>
@@ -1252,37 +1295,39 @@
<programlisting>device ether # Ethernet support</programlisting>
- <para><literal>ether</literal> is only needed if you have an Ethernet
- card. It includes generic Ethernet protocol code.</para>
+ <para><literal>ether</literal> is only needed if you have an
+ Ethernet card. It includes generic Ethernet protocol
+ code.</para>
<programlisting>device sl # Kernel SLIP</programlisting>
- <para><literal>sl</literal> is for SLIP support. This has been almost
- entirely supplanted by PPP, which is easier to set up, better suited
- for modem-to-modem connection, and more powerful.</para>
+ <para><literal>sl</literal> is for SLIP support. This has been
+ almost entirely supplanted by PPP, which is easier to set up,
+ better suited for modem-to-modem connection, and more
+ powerful.</para>
<programlisting>device ppp # Kernel PPP</programlisting>
- <para>This is for kernel PPP support for dial-up connections. There
- is also a version of PPP implemented as a userland application that
- uses <literal>tun</literal> and offers more flexibility and features
- such as demand dialing.</para>
+ <para>This is for kernel PPP support for dial-up connections.
+ There is also a version of PPP implemented as a userland
+ application that uses <literal>tun</literal> and offers more
+ flexibility and features such as demand dialing.</para>
<programlisting>device tun # Packet tunnel.</programlisting>
<para>This is used by the userland PPP software.
See
- the <link linkend="userppp">PPP</link> section of this book for more
- information.</para>
+ the <link linkend="userppp">PPP</link> section of this book
+ for more information.</para>
<programlisting><anchor id="kernelconfig-ptys"/>
device pty # Pseudo-ttys (telnet etc)</programlisting>
- <para>This is a <quote>pseudo-terminal</quote> or simulated login port.
- It is used by incoming <command>telnet</command> and
- <command>rlogin</command> sessions,
- <application>xterm</application>, and some other applications such
- as <application>Emacs</application>.</para>
+ <para>This is a <quote>pseudo-terminal</quote> or simulated
+ login port. It is used by incoming <command>telnet</command>
+ and <command>rlogin</command> sessions,
+ <application>xterm</application>, and some other applications
+ such as <application>Emacs</application>.</para>
<programlisting>device md # Memory <quote>disks</quote></programlisting>
@@ -1290,9 +1335,9 @@
<programlisting>device gif # IPv6 and IPv4 tunneling</programlisting>
- <para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling,
- IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. The
- <literal>gif</literal> device is
+ <para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6
+ tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6
+ tunneling. The <literal>gif</literal> device is
<quote>auto-cloning</quote>, and will create device nodes as
needed.</para>
@@ -1306,16 +1351,16 @@
# Note that 'bpf' is required for DHCP.
device bpf # Berkeley packet filter</programlisting>
- <para>This is the Berkeley Packet Filter. This pseudo-device allows
- network interfaces to be placed in promiscuous mode, capturing every
- packet on a broadcast network (e.g., an Ethernet). These packets
- can be captured to disk and or examined with the &man.tcpdump.1;
- program.</para>
+ <para>This is the Berkeley Packet Filter. This pseudo-device
+ allows network interfaces to be placed in promiscuous mode,
+ capturing every packet on a broadcast network (e.g., an
+ Ethernet). These packets can be captured to disk and or
+ examined with the &man.tcpdump.1; program.</para>
<note>
<para>The &man.bpf.4; device is also used by
- &man.dhclient.8; to obtain the IP address of the default router
- (gateway) and so on. If you use DHCP, leave this
+ &man.dhclient.8; to obtain the IP address of the default
+ router (gateway) and so on. If you use DHCP, leave this
uncommented.</para>
</note>
@@ -1357,8 +1402,9 @@
<sect2>
<title>Large Memory Configurations (<acronym>PAE</acronym>)</title>
+
<indexterm>
- <primary>Physical Address Extensions
+ <primary>Physical Address Extensions
(<acronym>PAE</acronym>)</primary>
<secondary>large memory</secondary>
</indexterm>
@@ -1367,7 +1413,8 @@
more than the 4 gigabyte limit on User+Kernel Virtual
Address (<acronym>KVA</acronym>) space. Due to this
limitation, Intel added support for 36-bit physical address
- space access in the &pentium; Pro and later line of CPUs.</para>
+ space access in the &pentium; Pro and later line of
+ CPUs.</para>
<para>The Physical Address Extension (<acronym>PAE</acronym>)
capability of the &intel; &pentium; Pro and later CPUs
@@ -1375,10 +1422,10 @@
&os; provides support for this capability via the
<option>PAE</option> kernel configuration option, available
in all current release versions of &os;. Due to
- the limitations of the Intel memory architecture, no distinction
- is made for memory above or below 4 gigabytes. Memory allocated
- above 4 gigabytes is simply added to the pool of available
- memory.</para>
+ the limitations of the Intel memory architecture, no
+ distinction is made for memory above or below 4 gigabytes.
+ Memory allocated above 4 gigabytes is simply added to the
+ pool of available memory.</para>
<para>To enable <acronym>PAE</acronym> support in the kernel,
simply add the following line to your kernel configuration
@@ -1394,7 +1441,8 @@
quality compared to other stable features of &os;.</para>
</note>
- <para><acronym>PAE</acronym> support in &os; has a few limitations:</para>
+ <para><acronym>PAE</acronym> support in &os; has a few
+ limitations:</para>
<itemizedlist>
<listitem>
@@ -1419,9 +1467,9 @@
tunables can unnecessarily over-allocate due to the
large memory nature of a <acronym>PAE</acronym> system.
One such example is the <option>kern.maxvnodes</option>
- sysctl, which controls the maximum number of vnodes allowed
- in the kernel. It is advised to adjust this and other
- such tunables to a reasonable value.</para>
+ sysctl, which controls the maximum number of vnodes
+ allowed in the kernel. It is advised to adjust this
+ and other such tunables to a reasonable value.</para>
</listitem>
<listitem>
@@ -1429,8 +1477,8 @@
address (<acronym>KVA</acronym>) space or to reduce the
amount of specific kernel resource that is heavily used
(see above) in order to avoid <acronym>KVA</acronym>
- exhaustion. The <option>KVA_PAGES</option> kernel option
- can be used for increasing the
+ exhaustion. The <option>KVA_PAGES</option> kernel
+ option can be used for increasing the
<acronym>KVA</acronym> space.</para>
</listitem>
</itemizedlist>
@@ -1473,12 +1521,13 @@
<term><command>make</command> fails:</term>
<listitem>
- <para>If the <command>make</command> command fails, it usually
- signals an error in your kernel description which is not severe
- enough for &man.config.8; to catch. Again, look
- over your configuration, and if you still cannot resolve the
- problem, send mail to the &a.questions; with your kernel
- configuration, and it should be diagnosed quickly.</para>
+ <para>If the <command>make</command> command fails, it
+ usually signals an error in your kernel description which
+ is not severe enough for &man.config.8; to catch. Again,
+ look over your configuration, and if you still cannot
+ resolve the problem, send mail to the &a.questions; with
+ your kernel configuration, and it should be diagnosed
+ quickly.</para>
</listitem>
</varlistentry>
@@ -1488,37 +1537,42 @@
<listitem>
<para>If your new kernel does not boot, or fails to
- recognize your devices, do not panic! Fortunately, &os; has
- an excellent mechanism for recovering from incompatible
- kernels. Simply choose the kernel you want to boot from at
- the &os; boot loader. You can access this when the system
- boot menu appears. Select the <quote>Escape to a loader
- prompt</quote> option, number six. At the prompt, type
- <command>boot <replaceable>kernel.old</replaceable></command>,
+ recognize your devices, do not panic! Fortunately, &os;
+ has an excellent mechanism for recovering from
+ incompatible kernels. Simply choose the kernel you want
+ to boot from at the &os; boot loader. You can access this
+ when the system boot menu appears. Select the
+ <quote>Escape to a loader prompt</quote> option, number
+ six. At the prompt, type
+ <command>boot
+ <replaceable>kernel.old</replaceable></command>,
or the name of any other kernel that will boot properly.
- When reconfiguring a kernel, it is always a good idea to keep
- a kernel that is known to work on hand.</para>
+ When reconfiguring a kernel, it is always a good idea to
+ keep a kernel that is known to work on hand.</para>
- <para>After booting with a good kernel you can check over your
- configuration file and try to build it again. One helpful
- resource is the <filename>/var/log/messages</filename> file
- which records, among other things, all of the kernel messages
- from every successful boot. Also, the &man.dmesg.8; command
- will print the kernel messages from the current boot.</para>
+ <para>After booting with a good kernel you can check over
+ your configuration file and try to build it again. One
+ helpful resource is the
+ <filename>/var/log/messages</filename> file which records,
+ among other things, all of the kernel messages from every
+ successful boot. Also, the &man.dmesg.8; command will
+ print the kernel messages from the current boot.</para>
<note>
- <para>If you are having trouble building a kernel, make sure
- to keep a <filename>GENERIC</filename>, or some other kernel
- that is known to work on hand as a different name that will
- not get erased on the next build. You cannot rely on
- <filename>kernel.old</filename> because when installing a
- new kernel, <filename>kernel.old</filename> is overwritten
- with the last installed kernel which may be non-functional.
- Also, as soon as possible, move the working kernel to the
- proper <filename class="directory">/boot/kernel</filename>
- location or commands such
- as &man.ps.1; may not work properly. To do this, simply
- rename the directory containing the good kernel:</para>
+ <para>If you are having trouble building a kernel, make
+ sure to keep a <filename>GENERIC</filename>, or some
+ other kernel that is known to work on hand as a
+ different name that will not get erased on the next
+ build. You cannot rely on
+ <filename>kernel.old</filename> because when installing
+ a new kernel, <filename>kernel.old</filename> is
+ overwritten with the last installed kernel which may
+ be non-functional. Also, as soon as possible, move
+ the working kernel to the proper <filename
+ class="directory">/boot/kernel</filename>
+ location or commands such as &man.ps.1; may not work
+ properly. To do this, simply rename the directory
+ containing the good kernel:</para>
<screen>&prompt.root; <userinput>mv /boot/kernel <replaceable>/boot/kernel.bad</replaceable></userinput>
&prompt.root; <userinput>mv /boot/<replaceable>kernel.good</replaceable> /boot/kernel</userinput></screen>
@@ -1532,15 +1586,16 @@
any more:</term>
<listitem>
- <para>If you have installed a different version of the kernel
- from the one that the system utilities have been built with,
- for example, a -CURRENT kernel on a -RELEASE, many system-status
- commands like &man.ps.1; and &man.vmstat.8; will not work any
- more. You should <link linkend="makeworld">recompile and install
- a world</link> built with the same version of the source tree as
- your kernel. This is one reason it is
- not normally a good idea to use a different version of the
- kernel from the rest of the operating system.</para>
+ <para>If you have installed a different version of the
+ kernel from the one that the system utilities have been
+ built with, for example, a -CURRENT kernel on a -RELEASE,
+ many system-status commands like &man.ps.1; and
+ &man.vmstat.8; will not work any more. You should
+ <link linkend="makeworld">recompile and install a
+ world</link> built with the same version of the
+ source tree as your kernel. This is one reason it is
+ not normally a good idea to use a different version of
+ the kernel from the rest of the operating system.</para>
</listitem>
</varlistentry>
</variablelist>
Index: x11/chapter.xml
===================================================================
--- x11/chapter.xml (revision 40692)
+++ x11/chapter.xml (working copy)
@@ -11,323 +11,131 @@
<author>
<firstname>Ken</firstname>
<surname>Tom</surname>
- <contrib>Updated for X.Org's X11 server by </contrib>
</author>
<author>
<firstname>Marc</firstname>
<surname>Fonvieille</surname>
</author>
+ <author>
+ <firstname>Dru</firstname>
+ <surname>Lavigne</surname>
+ </author>
</authorgroup>
</chapterinfo>
<title>The X Window System</title>
- <sect1 id="x11-synopsis">
- <title>Synopsis</title>
+ <sect1>
+ <title>Introduction</title>
- <para>FreeBSD uses X11 to provide users with
- a powerful graphical user interface. X11
- is a freely available version of the X Window System that
- is implemented in <application>&xorg;</application>
- (and other software packages not discussed here). The
- default and official flavor of X11 in &os; is
- <application>&xorg;</application>, the X11 server developed by
- the X.Org Foundation under a license very similar to the one
- used by &os;. Commercial X servers for &os; are also
- available.</para>
+ <para>An installation of &os; using
+ <application>bsdinstall</application> does not
+ automatically install a graphical user interface. This chapter
+ describes how to install and configure
+ <application>&xorg;</application>, which provides the X Window
+ System needed to provide a graphical environment. It then
+ describes how to find and install a desktop environment
+ or window manager.</para>
- <para>For more information on the video hardware that X11
- supports, check the <ulink
- url="http://www.x.org/">&xorg;</ulink>; web site.</para>
+ <note>
+ <para>FreeBSD users looking for an installation method that
+ automatically configures the X Window System and offers a
+ choice of window managers during installation should take a
+ look at <ulink
+ url="http://www.pcbsd.org/">PC-BSD.</ulink></para>;
+ </note>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
- <para>The various components of the X Window System, and how
- they interoperate.</para>
+ <para>The terms associated with the X Window System.</para>
</listitem>
<listitem>
- <para>How to install and configure X11.</para>
+ <para>How to install and configure
+ <application>Xorg</application>.</para>
</listitem>
<listitem>
- <para>How to install and use different window managers.</para>
+ <para>How to install and configure a desktop
+ environment.</para>
</listitem>
<listitem>
- <para>How to use &truetype; fonts in X11.</para>
+ <para>How to configure a display manager.</para>
</listitem>
<listitem>
- <para>How to set up your system for graphical logins
- (<application>XDM</application>).</para>
+ <para>How to configure fonts.</para>
</listitem>
- </itemizedlist>
- <para>Before reading this chapter, you should:</para>
-
- <itemizedlist>
<listitem>
- <para>Know how to install additional third-party
- software (<xref linkend="ports"/>).</para>
+ <para>How to troubleshoot the <application>Xorg</application>
+ configuration.</para>
</listitem>
</itemizedlist>
</sect1>
- <sect1 id="x-understanding">
- <title>Understanding X</title>
+ <sect1>
+ <title>Terminology</title>
- <para>Using X for the first time can be somewhat of a shock to
- someone familiar with other graphical environments, such as
- µsoft.windows; or &macos;.</para>
+ <para>The X Window System is designed as a network protocol
+ and uses a client-server model. The
+ <quote>X server</quote> runs on the computer that has the
+ keyboard, monitor, and mouse attached. The X server is
+ responsible for managing the display and for handling input
+ from the keyboard, mouse, or other input devices such as a
+ video projector. The <quote>X client</quote> is a running
+ application such as an <application>XTerm</application> or
+ <application>firefox</application>. An X client sends
+ messages to the X server such as <quote>Please draw a window
+ at these coordinates</quote>, and the server sends back
+ messages such as <quote>The user just clicked on the OK
+ button.</quote></para>
- <para>While it is not necessary to understand all of the details
- of various X components and how they interact, some basic
- knowledge makes it possible to take advantage of X's
- strengths.</para>
+ <para>Typically, the X server and the X clients run on the same
+ computer. However, it is possible to run the X server on a
+ less powerful computer, and run the X clients on a more
+ powerful system. In this scenario, the communication between
+ the X client and server takes place over the network.</para>
- <sect2>
- <title>Why X?</title>
+ <para>A <quote>window manager</quote> controls the placement
+ and appearance of windows within the graphical environment.
+ There are over a hundred different window managers available
+ within the <filename>x11-wm</filename> category of the &os;
+ Ports Collection. Each window manager provides a different
+ look and feel. Some support virtual desktops, customized
+ keystrokes to manage the desktop, or themes.</para>
- <para>X is not the first window system written for &unix;, but
- it is the most popular of them. X's original development team
- had worked on another window system prior to writing X. That
- system's name was <quote>W</quote> (for
- <quote>Window</quote>). X was just the next letter in the
- Roman alphabet.</para>
+ <para>A <quote>desktop environment</quote> is a window
+ manager that provides its own suite of applications.
+ Applications can include configuration utilities, editors,
+ games, web browsers, and file managers.
+ <application>KDE</application> and
+ <application>GNOME</application> are considered to be desktop
+ environments.</para>
- <para>X can be called <quote>X</quote>, <quote>X Window
- System</quote>, <quote>X11</quote>, and a number of other
- terms. You may find that using the term <quote>X
- Windows</quote> to describe X11 can be offensive to some
- people; for a bit more insight on this, see &man.X.7;.</para>
- </sect2>
+ <para>The <quote>focus policy</quote> determines which window
+ receives user input. For example, a
+ <quote>click-to-focus</quote> policy will activate a window
+ when it is clicked. The window manager enforces the focus
+ policy and different window managers support different focus
+ methods. All window managers support click-to-focus, and most
+ window managers support several types of focus methods.</para>
- <sect2>
- <title>The X Client/Server Model</title>
-
- <para>X was designed from the beginning to be network-centric,
- and adopts a <quote>client-server</quote> model.</para>
-
- <para>In the X model, the
- <quote>X server</quote> runs on the computer that has the
- keyboard, monitor, and mouse attached. The server's
- responsibility includes tasks such as managing the
- display, handling input from the keyboard and mouse, and
- other input or output devices (i.e., a <quote>tablet</quote>
- can be used as an input device, and a video projector
- may be an alternative output device). Each X application
- (such as <application>XTerm</application>, or
- <application>&netscape;</application>) is a
- <quote>client</quote>. A client sends messages to the server
- such as <quote>Please draw a window at these
- coordinates</quote>, and the server sends back messages such
- as <quote>The user just clicked on the OK
- button</quote>.</para>
-
- <para>In a home or small office environment, the X server and
- the X clients commonly run on the same computer. However, it
- is perfectly possible to run the X server on a less powerful
- desktop computer, and run X applications (the clients) on,
- say, the powerful and expensive machine that serves the
- office. In this scenario the communication between the X
- client and server takes place over the network.</para>
-
- <para>This confuses some people, because the X terminology is
- exactly backward to what they expect. They expect the
- <quote>X server</quote> to be the big powerful machine down
- the hall, and the <quote>X client</quote> to be the machine
- on their desk.</para>
-
- <para>It is important to remember that the X server is the
- machine with the monitor and keyboard, and the X clients are
- the programs that display the windows.</para>
-
- <para>There is nothing in the protocol that forces the client
- and server machines to be running the same operating system,
- or even to be running on the same type of computer. It is
- certainly possible to run an X server on µsoft.windows;
- or Apple's &macos;, and there are various free and commercial
- applications available that do exactly that.</para>
- </sect2>
-
- <sect2>
- <title>The Window Manager</title>
-
- <para>The X design philosophy is much like the &unix; design
- philosophy, <quote>tools, not policy</quote>. This means
- that X does not try to dictate how a task is to be
- accomplished. Instead, tools are provided to the user, and
- it is the user's responsibility to decide how to use those
- tools.</para>
-
- <para>This philosophy extends to X not dictating what windows
- should look like on screen, how to move them around with the
- mouse, what keystrokes should be used to move between windows
- (i.e.,
- <keycombo action="simul">
- <keycap>Alt</keycap>
- <keycap>Tab</keycap>
- </keycombo>, in the case of µsoft.windows;), what the
- title bars on each window should look like, whether or not
- they have close buttons on them, and so on.</para>
-
- <para>Instead, X delegates this responsibility to an
- application called a <quote>Window Manager</quote>. There
- are dozens of window managers available for X:
- <application>AfterStep</application>,
- <application>Blackbox</application>,
- <application>ctwm</application>,
- <application>Enlightenment</application>,
- <application>fvwm</application>,
- <application>Sawfish</application>,
- <application>twm</application>,
- <application>Window Maker</application>, and more. Each of
- these window managers provides a different look and feel;
- some of them support <quote>virtual desktops</quote>; some
- of them allow customized keystrokes to manage the desktop;
- some have a <quote>Start</quote> button or similar device;
- some are <quote>themeable</quote>, allowing a complete change
- of look-and-feel by applying a new theme. These window
- managers, and many more, are available in the
- <filename>x11-wm</filename> category of the Ports
- Collection.</para>
-
- <para>In addition, the <application>KDE</application> and
- <application>GNOME</application> desktop environments both
- have their own window managers which integrate with the
- desktop.</para>
-
- <para>Each window manager also has a different configuration
- mechanism; some expect configuration file written by hand,
- others feature GUI tools for most of the configuration tasks;
- at least one (<application>Sawfish</application>) has a
- configuration file written in a dialect of the Lisp
- language.</para>
-
- <note>
- <title>Focus Policy</title>
-
- <para>Another feature the window manager is responsible for
- is the mouse <quote>focus policy</quote>. Every windowing
- system needs some means of choosing a window to be actively
- receiving keystrokes, and should visibly indicate which
- window is active as well.</para>
-
- <para>A familiar focus policy is called
- <quote>click-to-focus</quote>. This is the model utilized
- by µsoft.windows;, in which a window becomes active
- upon receiving a mouse click.</para>
-
- <para>X does not support any particular focus policy.
- Instead, the window manager controls which window has the
- focus at any one time. Different window managers will
- support different focus methods. All of them support
- click to focus, and the majority of them support several
- others.</para>
-
- <para>The most popular focus policies are:</para>
-
- <variablelist>
- <varlistentry>
- <term>focus-follows-mouse</term>
-
- <listitem>
- <para>The window that is under the mouse pointer is
- the window that has the focus. This may not
- necessarily be the window that is on top of all the
- other windows. The focus is changed by pointing at
- another window, there is no need to click in it as
- well.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>sloppy-focus</term>
-
- <listitem>
- <para>This policy is a small extension to
- focus-follows-mouse. With focus-follows-mouse, if
- the mouse is moved over the root window (or
- background) then no window has the focus, and
- keystrokes are simply lost. With sloppy-focus, focus
- is only changed when the cursor enters a new
- window, and not when exiting the current
- window.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>click-to-focus</term>
-
- <listitem>
- <para>The active window is selected by mouse click.
- The window may then be <quote>raised</quote>, and
- appear in front of all other windows. All keystrokes
- will now be directed to this window, even if the
- cursor is moved to another window.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Many window managers support other policies, as well
- as variations on these. Be sure to consult the
- documentation for the window manager itself.</para>
- </note>
- </sect2>
-
- <sect2>
- <title>Widgets</title>
-
- <para>The X approach of providing tools and not policy
- extends to the widgets seen on screen in each
- application.</para>
-
- <para><quote>Widget</quote> is a term for all the items in
- the user interface that can be clicked or manipulated in
- some way; buttons, check boxes, radio buttons, icons, lists,
- and so on. µsoft.windows; calls these
- <quote>controls</quote>.</para>
-
- <para>µsoft.windows; and Apple's &macos; both have a
- very rigid widget policy. Application developers are
- supposed to ensure that their applications share a common
- look and feel. With X, it was not considered sensible to
- mandate a particular graphical style, or set of widgets to
- adhere to.</para>
-
- <para>As a result, do not expect X applications to have a
- common look and feel. There are several popular widget sets
- and variations, including the original Athena widget set from
- MIT, <application>&motif;</application> (on which the widget
- set in µsoft.windows; was modeled, all bevelled edges and
- three shades of grey), <application>OpenLook</application>,
- and others.</para>
-
- <para>Most newer X applications today will use a
- modern-looking widget set, either Qt, used by
- <application>KDE</application>, or GTK+, used by the
- <application>GNOME</application> project. In this respect,
- there is some convergence in look-and-feel of the &unix;
- desktop, which certainly makes things easier for the novice
- user.</para>
- </sect2>
+ <para><quote>Widget set</quote> is a term representing all of
+ the items in the graphical interface that can be clicked or
+ manipulated in some way, such as check boxes, radio buttons,
+ and icons. Different window managers use different widget
+ sets. Examples of widget sets include Qt, used by
+ <application>KDE</application>, and GTK+, used by
+ <application>GNOME</application>.</para>
</sect1>
<sect1 id="x-install">
- <title>Installing X11</title>
+ <title>Installing Xorg</title>
- <para><application>&xorg;</application> is the default X11
- implementation for &os;. <application>&xorg;</application>
- is the X server of the open source X Window System
- implementation released by the X.Org Foundation.
- <application>&xorg;</application> is based on the code of
- <application>&xfree86; 4.4RC2</application> and X11R6.6.
- The version of <application>&xorg;</application> currently
- available in the &os; Ports Collection is &xorg.version;.</para>
-
<para>To build and install <application>&xorg;</application>
from the Ports Collection:</para>
@@ -340,33 +148,16 @@
available.</para>
</note>
- <para>Alternatively, X11
- can be installed directly from packages.
- Binary packages to use with &man.pkg.add.1; tool are also
- available for X11. When the remote fetching feature of
- &man.pkg.add.1; is used, the version number of the package
- must be removed. &man.pkg.add.1; will automatically fetch
- the latest version of the application.</para>
+ <para>Alternatively, to install the complete
+ <application>&xorg;</application> binary package which
+ includes all of the X servers, clients, and fonts:</para>
- <para>So to fetch and install the package of
- <application>&xorg;</application>, simply type:</para>
-
<screen>&prompt.root; <userinput>pkg_add -r xorg</userinput></screen>
- <note><para>The examples above will install the complete
- X11 distribution including the
- servers, clients, fonts etc. Separate packages and ports of X11
- are also
- available.</para>
-
- <para>To install a minimal X11 distribution you can
- alternatively install
- <filename role="package">x11/xorg-minimal</filename>.</para>
- </note>
-
- <para>The rest of this chapter will explain how to configure
- X11, and how to set up a productive desktop
- environment.</para>
+ <para>To instead install a minimal
+ <application>&xorg;</application> distribution, use the
+ <filename role="package">x11/xorg-minimal</filename> port or
+ package.</para>
</sect1>
<sect1 id="x-config">
@@ -380,123 +171,90 @@
</author>
</authorgroup>
</sect1info>
- <title>X11 Configuration</title>
+ <title>Xorg Configuration</title>
-
<indexterm><primary>&xorg;</primary></indexterm>
<indexterm><primary>X11</primary></indexterm>
- <sect2>
- <title>Before Starting</title>
+ <para>Xorg is often self-configuring. However, depending upon
+ the video hardware and the support provided by its driver, it
+ may or may not be possible to configure optimal resolution for
+ the hardware. At this time, driver support is as
+ follows:</para>
- <para>In most cases, X11 is self-configuring. Those with older
- or unusual equipment may find it helpful to gather some
- hardware information before beginning configuration.</para>
+ <itemizedlist>
+ <listitem>
+ <para>NVIDIA: several NVIDIA drivers are
+ available in the <filename>x11</filename> category of the
+ &os; Ports Collection. Install the driver that matches the
+ model of the NVIDIA hardware.</para>
+ </listitem>
+ <listitem>
+ <para>Intel: as of &os; 9.1, 3D acceleration on
+ most Intel graphics, including IronLake, SandyBridge,
+ and IvyBridge, is supported. Due to the current KMS
+ implementation, it is not possible to switch between the
+ graphical console and a virtual console using
+ <userinput>Crtl+Alt+F#.</userinput></para>
+ </listitem>
+ <listitem>
+ <para>ATI/Radeon: 3D acceleration will not work on
+ ATI or Radeon cards until &os; completes its TTM work.
+ These cards will need to be configured with the 2D driver,
+ and if that does not work, with the Vesa
+ driver.</para>
+ </listitem>
+ <listitem>
+ <para>Optimus: currently there is no switching
+ support between the two graphics adapters provided by
+ Optimus. Optimus implementations vary, so &os; may or may
+ not be able to successfully load a graphics driver on all
+ hardware. If you get a blank screen, check if the BIOS has
+ an option to disable one of the graphics adapters or to set
+ <quote>discrete</quote> mode.</para>
+ </listitem>
+ </itemizedlist>
- <itemizedlist>
- <listitem><para>Monitor sync frequencies</para></listitem>
- <listitem><para>Video card chipset</para></listitem>
- <listitem><para>Video card memory</para></listitem>
- </itemizedlist>
+ <para>The video card chipset should be autodetected and used to
+ select the proper video driver. It is beneficial for the user
+ to be aware of which chipset is installed should
+ autodetection not provide the desired result. Additionally,
+ video card memory and the driver determine the maximum
+ resolution and color depth which can be displayed.</para>
- <indexterm>
- <primary>horizontal sync frequency</primary>
- </indexterm>
- <indexterm>
- <primary>horizontal scan rate</primary>
- <see>horizontal sync frequency</see>
- </indexterm>
- <indexterm><primary>refresh rate</primary></indexterm>
- <indexterm>
- <primary>vertical sync frequency</primary>
- <see>refresh rate</see>
- </indexterm>
- <indexterm>
- <primary>vertical scan rate</primary>
- <see>refresh rate</see>
- </indexterm>
+ <para><application>&xorg;</application>
+ uses <acronym>HAL</acronym> to autodetect keyboards and mice.
+ The <filename role="package">sysutils/hal</filename> and
+ <filename role="package">devel/dbus</filename> ports are
+ installed as dependencies of <filename
+ role="package">x11/xorg</filename>, but must be enabled by
+ adding these entries to
+ <filename>/etc/rc.conf</filename>:</para>
- <para>Screen resolution and refresh rate are determined by the
- monitor's horizontal and vertical sync frequencies. Almost
- all monitors support electronic autodetection of these values.
- A few monitors do not provide these values, and the
- specifications must be determined from the printed manual
- or manufacturer web site.</para>
-
- <para>The video card chipset is also autodetected, and used to
- select the proper video driver. It is beneficial for the user
- to be aware of which chipset is installed for when
- autodetection does not provide the desired result.</para>
-
- <para>Video card memory determines the maximum resolution and
- color depth which can be displayed.</para>
- </sect2>
-
- <sect2>
- <title>Configuring X11</title>
-
- <para><application>&xorg;</application>
- uses <acronym>HAL</acronym> to autodetect keyboards and mice.
- The <filename role="package">sysutils/hal</filename> and
- <filename role="package">devel/dbus</filename> ports are
- installed as dependencies of <filename
- role="package">x11/xorg</filename>, but must be enabled by
- the following entries in the
- <filename>/etc/rc.conf</filename> file:</para>
-
<programlisting>hald_enable="YES"
dbus_enable="YES"</programlisting>
- <para>These services should be started (either manually or by
- rebooting) before further <application>&xorg;</application>
- configuration or use is attempted.</para>
+ <para>These services should be started before attempting
+ <application>&xorg;</application>
+ configuration:</para>
- <para><application>&xorg;</application> can
- often work without any further configuration steps by
- simply typing at prompt:</para>
+ <screen>&prompt.root; <userinput>service hald start</userinput>
+&prompt.root; <userinput>service dbus start</userinput></screen>
- <screen>&prompt.user; <userinput>startx</userinput></screen>
+ <para>Once these services are started, check if
+ <application>&xorg;</application> auto-configures itself by
+ typing:</para>
- <para>The automatic configuration may fail to work with some
- hardware, or may not set things up quite as desired. In
- these cases, manual configuration will be necessary.</para>
+ <screen>&prompt.root; <userinput>Xorg -configure</userinput></screen>
- <note>
- <para>Desktop environments like
- <application>GNOME</application>,
- <application>KDE</application> or
- <application>Xfce</application> have tools allowing the user
- to easily set the screen parameters such as the resolution.
- So if the default configuration is not acceptable and you
- planned to install a desktop environment then just continue
- with the installation of the desktop environment and use the
- appropriate screen settings tool.</para>
- </note>
-
- <para>Configuration of X11 is a multi-step process. The first
- step is to build an initial configuration file. As the super
- user, simply run:</para>
-
- <screen>&prompt.root; <userinput>Xorg -configure</userinput></screen>
-
- <para>This will generate an
- X11 configuration skeleton file in the
+ <para>This will generate a configuration file in the
<filename>/root</filename> directory called
- <filename>xorg.conf.new</filename> (whether you &man.su.1; or
- do a direct login affects the inherited supervisor
- <envar>$HOME</envar> directory variable). The
- X11 program will attempt to probe
- the graphics hardware on the system and write a
- configuration file to load the proper drivers for the detected
- hardware on the target system.</para>
+ <filename>xorg.conf.new</filename>. Next, test that the
+ automatically generated configuration file works with the
+ graphics hardware by typing:</para>
- <para>The next step is to test the existing
- configuration to verify that <application>&xorg;</application>
- can work with the graphics
- hardware on the target system. Type:</para>
+ <screen>&prompt.root; <userinput>Xorg -config /root/xorg.conf.new </userinput></screen>
- <screen>&prompt.root; <userinput>Xorg -config xorg.conf.new -retro</userinput></screen>
-
<para>If a black and grey grid and an X mouse cursor appear,
the configuration was successful. To exit the test, switch
to the virtual console used to start it by pressing
@@ -552,407 +310,492 @@
<programlisting>Option "DontZap" "off"</programlisting>
</note>
- <para>If the mouse does not work, you will need to first
- configure it before proceeding. See <xref linkend="mouse"/>
- in the &os; install chapter. In recent
- <application>Xorg</application> versions,
- the <literal>InputDevice</literal> sections in
- <filename>xorg.conf</filename> are ignored in favor of the
- autodetected devices. To restore the old behavior, add the
- following line to the <literal>ServerLayout</literal> or
- <literal>ServerFlags</literal> section of this file:</para>
+ <para>If the test is unsuccessful, skip ahead to the
+ <link linkend="x11-understanding">troubleshooting
+ section</link>. Once the test is successful, copy the
+ configuration file to
+ <filename>/etc/X11/xorg.conf</filename>:</para>
- <programlisting>Option "AutoAddDevices" "false"</programlisting>
+ <screen>&prompt.root; <userinput>cp xorg.conf.new /etc/X11/xorg.conf</userinput></screen>
- <para>Input devices may then be configured as in previous
- versions, along with any other options needed (e.g.,
- keyboard layout switching).</para>
+ <para> The next step is to install a window manager or desktop
+ environment as described in the next section.</para>
+ </sect1>
- <note>
- <para>As previously explained
- the <application>hald</application> daemon will, by default,
- automatically detect your keyboard. There are chances that
- your keyboard layout or model will not be correct, desktop
- environments like <application>GNOME</application>,
- <application>KDE</application> or
- <application>Xfce</application> provide tools to configure
- the keyboard. However, it is possible to set the keyboard
- properties directly either with the help of the
- &man.setxkbmap.1; utility or with a
- <application>hald</application>'s configuration rule.</para>
+ <sect1 id="x11-wm">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Valentino</firstname>
+ <surname>Vaschetto</surname>
+ <contrib>Contributed by </contrib>
+ </author>
+ <!-- June 2001 -->
+ </authorgroup>
+ </sect1info>
- <para>For example if one wants to use a PC 102 keys keyboard
- coming with a french layout, we have to create a keyboard
- configuration file for <application>hald</application>
- called <filename>x11-input.fdi</filename> and saved in the
- <filename
- class="directory">/usr/local/etc/hal/fdi/policy</filename>
- directory. This file should contain the following
- lines:</para>
+ <title>Installing a Desktop Environment</title>
- <programlisting><?xml version="1.0" encoding="iso-8859-1"?>
-<deviceinfo version="0.2">
- <device>
- <match key="info.capabilities" contains="input.keyboard">
- <merge key="input.x11_options.XkbModel" type="string">pc102</merge>
- <merge key="input.x11_options.XkbLayout" type="string">fr</merge>
- </match>
- </device>
-</deviceinfo></programlisting>
+ <para>This section describes how to install some of the available
+ desktop environments on &os;. The next section will
+ demonstrate how to start an installed desktop environment or
+ window manager using a display manager.</para>
- <para>If this file already exists, just copy and add to your
- file the lines regarding the keyboard configuration.</para>
+ <sect2 id="x11-wm-gnome">
+ <title>GNOME</title>
- <para>You will have to reboot your machine to force
- <application>hald</application> to read this file.</para>
+ <indexterm><primary>GNOME</primary></indexterm>
+ <para><application>GNOME</application> is an easy-to-use
+ desktop environment which includes a panel for starting
+ applications, a desktop where data and applications can be
+ placed, and a set of standard desktop tools and
+ applications. Two versions of GNOME are available, GNOME2
+ and GNOME3, and the user interface differs significantly
+ between the two versions. GNOME2 is available for &os; and
+ GNOME3 is currently being ported to &os;. More information
+ about installing, configuring, and managing
+ <application>GNOME</application> and the status of the
+ GNOME3 porting project can be found at the web site of the
+ <ulink url="http://www.FreeBSD.org/gnome">&os; GNOME
+ Project.</ulink></para>
- <para>It is possible to do the same configuration from an X
- terminal or a script with this command line:</para>
+ <para>To install the <application>GNOME</application>
+ binary package, type:</para>
- <screen>&prompt.user; <userinput>setxkbmap -model pc102 -layout fr</userinput></screen>
+ <screen>&prompt.root; <userinput>pkg_add -r gnome2</userinput></screen>
- <para>The
- <filename>/usr/local/share/X11/xkb/rules/base.lst</filename>
- file lists the various keyboard, layouts and options
- available.</para>
- </note>
+ <para>Alternately, to build the
+ <application>GNOME</application> port:</para>
- <indexterm><primary>X11 tuning</primary></indexterm>
+ <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
- <para>The <filename>xorg.conf.new</filename>
- configuration file may now be tuned to taste. Open the
- file in a text editor such as &man.emacs.1; or &man.ee.1;.
- If the monitor is an older or unusual model that does not
- support autodetection of sync frequencies, those settings
- can be added to <filename>xorg.conf.new</filename>
- under the <literal>"Monitor"</literal> section:</para>
+ <para><application>GNOME</application>
+ requires the <filename>/proc</filename> filesystem to be
+ mounted. Add this line to <filename>/etc/fstab</filename>
+ to mount &man.procfs.5; automatically during system
+ boot:</para>
- <programlisting>Section "Monitor"
- Identifier "Monitor0"
- VendorName "Monitor Vendor"
- ModelName "Monitor Model"
- HorizSync 30-107
- VertRefresh 48-120
-EndSection</programlisting>
+ <programlisting>proc /proc procfs rw 0 0</programlisting>
- <para>Most monitors support sync frequency autodetection,
- making manual entry of these values unnecessary. For the
- few monitors that do not support autodetection, avoid
- potential damage by only entering values provided by the
- manufacturer.</para>
+ <para>To mount <filename>/proc</filename> without rebooting,
+ type:</para>
- <para>X allows DPMS (Energy Star) features to be used with
- capable monitors. The &man.xset.1; program controls the
- time-outs and can force standby, suspend, or off modes. If
- you wish to enable DPMS features for your monitor, you must
- add the following line to the monitor section:</para>
+<screen>&prompt.root; <userinput>mount -t procfs proc /proc</userinput></screen>
+ </sect2>
- <programlisting>Option "DPMS"</programlisting>
+ <sect2 id="x11-wm-kde">
+ <title>KDE</title>
- <indexterm>
- <primary><filename>xorg.conf</filename></primary>
- </indexterm>
+ <indexterm><primary>KDE</primary></indexterm>
- <para>While the <filename>xorg.conf.new</filename>
- configuration file is still open in an editor, select
- the default resolution and color depth desired. This is
- defined in the <literal>"Screen"</literal> section:</para>
+ <para><application>KDE</application> is an easy-to-use
+ desktop environment which includes an integrated help
+ system, internationalization, centralized desktop
+ configuration utilities, and a web browser called
+ <application>Konqueror</application>. More information on
+ <application>KDE</application> can be found at the <ulink
+ url="http://www.kde.org/">KDE website</ulink>. &os;
+ specific information and resources can be found at the
+ <ulink url="http://freebsd.kde.org/">KDE/&os;
+ initiative</ulink> website.</para>
- <programlisting>Section "Screen"
- Identifier "Screen0"
- Device "Card0"
- Monitor "Monitor0"
- DefaultDepth 24
- SubSection "Display"
- Viewport 0 0
- Depth 24
- Modes "1024x768"
- EndSubSection
-EndSection</programlisting>
+ <para>Two versions of <application>KDE</application> are
+ available for &os;. While version 3 is still available, it
+ is unmaintained and partially broken. Version 4 is the
+ recommended choice as it is punctually updated. KDE4
+ is the version that is discussed in this section.</para>
- <para>The <literal>DefaultDepth</literal> keyword describes
- the color depth to run at by default. This can be overridden
- with the <option>-depth</option> command line switch to
- &man.Xorg.1;.
- The <literal>Modes</literal> keyword
- describes the resolution to run at for the given color depth.
- Note that only VESA standard modes are supported as defined by
- the target system's graphics hardware.
- In the example above, the default color depth is twenty-four
- bits per pixel. At this color depth, the accepted
- resolution is 1024 by 768 pixels.</para>
+ <para>To install the <application>KDE 4</application>
+ binary package, type:</para>
- <para>Finally, write the configuration file and test it using
- the test mode given above.</para>
+ <screen>&prompt.root; <userinput>pkg_add -r kde4</userinput></screen>
- <note>
- <para>One of the tools available to assist you during
- troubleshooting process are the X11 log files, which
- contain information on each device that the X11 server
- attaches to. <application>&xorg;</application> log file
- names are in the format of
- <filename>/var/log/Xorg.0.log</filename>. The exact name
- of the log can vary from <filename>Xorg.0.log</filename>
- to <filename>Xorg.8.log</filename> and so forth.</para>
- </note>
+ <para>To instead build <application>KDE 4</application> from
+ ports, type:</para>
- <para>If all is well, the configuration
- file needs to be installed in a common location where
- &man.Xorg.1; can find it.
- This is typically <filename>/etc/X11/xorg.conf</filename> or
- <filename>/usr/local/etc/X11/xorg.conf</filename>.</para>
+ <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde4</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+ </sect2>
- <screen>&prompt.root; <userinput>cp xorg.conf.new /etc/X11/xorg.conf</userinput></screen>
+ <sect2 id="x11-wm-xfce">
+ <title>Xfce</title>
- <para>The X11 configuration process is now
- complete. <application>&xorg;</application> may be now
- started with the &man.startx.1; utility.
- The X11 server may also be started with the use of
- &man.xdm.1;.</para>
+ <para><application>Xfce</application> is a lightweight desktop
+ environment meant for those with older hardware or who want
+ a simple, efficient desktop which is easy to use and
+ configure. Some of <application>Xfce</application>'s
+ features include a main panel with menus, applets and
+ application launchers, a file manager, and a sound manager.
+ More information on <application>Xfce</application>
+ can be found on the <ulink url="http://www.xfce.org/">Xfce
+ website</ulink>.</para>
+
+ <para>To install the <application>Xfce</application> binary
+ package, type:</para>
+
+ <screen>&prompt.root; <userinput>pkg_add -r xfce4</userinput></screen>
+
+ <para>Alternatively, to build the port:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce4</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
</sect2>
+ </sect1>
+ <sect1 id="x-xdm">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Seth</firstname>
+ <surname>Kingsley</surname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ </sect1info>
+ <title>Display Managers</title>
+
+ <para>Several display managers are available for &os;. A
+ Display manager provides a graphical login screen and
+ automatically loads a window manager once the user successfully
+ inputs their username and password.</para>
+
+ <para>This section demonstrates how to configure the Gnome
+ Display Manager (GDM), KDE Display Manager (KDM), and X Display
+ Manager (XDM). It also describes how a user can manually start
+ their preferred window manager using
+ <application>startx</application>.</para>
+
<sect2>
- <title>Advanced Configuration Topics</title>
+ <title>GDM</title>
- <sect3>
- <title>Configuration with &intel; <literal>i810</literal>
- Graphics Chipsets</title>
+ <para>The GNOME Display Manager (<application>GDM</application>)
+ is installed as part of the <application>GNOME</application>
+ desktop, although it is disabled by default. It can be
+ configured to start at system boot by adding this line to
+ <filename>/etc/rc.conf</filename>:</para>
- <indexterm><primary>Intel i810 graphic chipset</primary></indexterm>
+ <programlisting>gdm_enable="YES"</programlisting>
- <para>Configuration with &intel; i810 integrated chipsets
- requires the <devicename>agpgart</devicename>
- AGP programming interface for X11
- to drive the card. See the &man.agp.4; driver manual page
- for more information.</para>
+ <para>To start the service now, type:</para>
- <para>This will allow configuration of the hardware as any
- other graphics board. Note on systems without the
- &man.agp.4; driver compiled in the kernel, trying to load
- the module with &man.kldload.8; will not work. This
- driver has to be in the kernel at boot time through being
- compiled in or using
- <filename>/boot/loader.conf</filename>.</para>
- </sect3>
+ <screen>&prompt.root; <userinput>service gdm start</userinput></screen>
- <sect3>
- <title>Adding a Widescreen Flatpanel to the Mix</title>
+ <para>It is often desirable to start all
+ <application>GNOME</application> services together with
+ <application>GDM</application>. To achieve this, add the
+ following line to <filename>/etc/rc.conf</filename>:</para>
- <indexterm><primary>widescreen flatpanel configuration</primary></indexterm>
+ <programlisting>gnome_enable="YES"</programlisting>
+ </sect2>
+ <sect2>
+ <title>KDM</title>
- <para>This section assumes a bit of advanced configuration
- knowledge. If attempts to use the standard configuration
- tools above have not resulted in a working configuration,
- there is information enough in the log files to be of use
- in getting the setup working. Use of a text editor will
- be necessary.</para>
+ <indexterm><primary>KDE</primary>
+ <secondary>display manager</secondary></indexterm>
+ <para>The installation of <application>KDE</application>
+ includes the <application>KDM</application> login manager.
+ In addition to starting <application>KDE</application>,
+ <application>KDM</application> can be configured to start
+ other installed window managers. During login, users can
+ choose which window manager to log into.</para>
- <para>Current widescreen (WSXGA, WSXGA+, WUXGA, WXGA,
- WXGA+, et.al.) formats support 16:10 and 10:9 formats or
- aspect ratios that can be problematic. Examples of some
- common screen resolutions for 16:10 aspect ratios
- are:</para>
+ <para>To configure <application>KDM</application>, mount
+ &man.procfs.5; then add the following line to
+ <filename>/etc/rc.conf</filename>: MORE CONFIGURATION
+ NEEDED?</para>
- <itemizedlist>
- <listitem><para>2560x1600</para></listitem>
- <listitem><para>1920x1200</para></listitem>
- <listitem><para>1680x1050</para></listitem>
- <listitem><para>1440x900</para></listitem>
- <listitem><para>1280x800</para></listitem>
- </itemizedlist>
+ <programlisting>kdm4_enable="YES"</programlisting>
+ </sect2>
+ <sect2>
+ <title>XDM</title>
- <para>At some point, it will be as easy as adding one of these
- resolutions as a possible <literal>Mode</literal> in the
- <literal>Section "Screen"</literal> as such:</para>
+ <indexterm><primary>X Display Manager</primary></indexterm>
- <programlisting>Section "Screen"
-Identifier "Screen0"
-Device "Card0"
-Monitor "Monitor0"
-DefaultDepth 24
-SubSection "Display"
- Viewport 0 0
- Depth 24
- Modes "1680x1050"
-EndSubSection
-EndSection</programlisting>
+ <para>The X Display Manager (<application>XDM</application>)
+ provides a graphical interface for choosing an X server to log
+ into.</para>
- <para><application>&xorg;</application> is smart enough to
- pull the resolution information from the widescreen via
- I2C/DDC information so it knows what the monitor can
- handle as far as frequencies and resolutions.</para>
+ <para><application>XDM</application> can be installed using
+ the <filename role="package">x11/xdm</filename> binary
+ package or port. Once installed, the
+ <filename>/usr/local/bin/xdm</filename>
+ program can be run at any time as <username>root</username>
+ in order to start managing the X display on the local machine.
+ To configure <application>XDM</application> to run at system
+ boot, edit this line in <filename>/etc/ttys</filename>:</para>
- <para>If those <literal>ModeLines</literal> do not exist in
- the drivers, one might need to give
- <application>&xorg;</application> a little hint. Using
- <filename>/var/log/Xorg.0.log</filename> one can extract
- enough information to manually create a
- <literal>ModeLine</literal> that will work. Simply look
- for information resembling this:</para>
+ <screen>ttyv8 "/usr/local/bin/xdm -nodaemon" xterm off secure</screen>
- <programlisting>(II) MGA(0): Supported additional Video Mode:
-(II) MGA(0): clock: 146.2 MHz Image Size: 433 x 271 mm
-(II) MGA(0): h_active: 1680 h_sync: 1784 h_sync_end 1960 h_blank_end 2240 h_border: 0
-(II) MGA(0): v_active: 1050 v_sync: 1053 v_sync_end 1059 v_blanking: 1089 v_border: 0
-(II) MGA(0): Ranges: V min: 48 V max: 85 Hz, H min: 30 H max: 94 kHz, PixClock max 170 MHz</programlisting>
+ <para>Change the <literal>off</literal> to
+ <literal>on</literal> and restart &man.init.8; using the
+ directions in <xref linkend="term-hup"/>. The first field,
+ <literal>ttyv8</literal>, indicates that
+ <application>XDM</application> will start on the ninth
+ virtual terminal which can be accessed using
+ <keycap>Ctrl</keycap>
+ <keycap>Alt</keycap>
+ <keycap>F9</keycap>.</para>
- <para>This information is called EDID information. Creating a
- <literal>ModeLine</literal> from this is just a matter of
- putting the numbers in the correct order:</para>
+ <para>The <application>XDM</application> configuration directory
+ is located in <filename>/usr/local/lib/X11/xdm</filename>.
+ In this directory there are several files used to change the
+ behavior and appearance of <application>XDM</application>.
+ The syntax and usage of the following files are described in
+ more detail in &man.xdm.1;.</para>
- <programlisting>ModeLine <name> <clock> <4 horiz. timings> <4 vert. timings></programlisting>
+ <itemizedlist>
+ <listitem>
+ <para><filename>Xaccess</filename></para>
+ <para>Client authorization ruleset for controlling XDMCP
+ connections from remote machines. The protocol for
+ connecting to <application>XDM</application>-controlled
+ displays is called the X Display Manager Connection
+ Protocol (XDMCP). This file is ignored unless
+ <filename>xdm-config</filename> is changed to listen
+ for remote connections. By default, this file does not
+ allow any clients to connect.</para>
+ </listitem>
+ <listitem>
+ <para><filename>Xresources</filename></para>
+ <para>Default X resource values for configuring the
+ appearance of the display chooser and login screens.
+ The format is identical to
+ <filename>app-defaults</filename> described in the
+ <application>Xorg</application> documentation.</para>
+ </listitem>
- <para>So that the <literal>ModeLine</literal> in
- <literal>Section "Monitor"</literal>
- for this example would look like this:</para>
+ <listitem>
+ <para><filename>Xservers</filename></para>
+ <para>List of remote and local displays the login menu
+ should provide as choices.</para>
+ </listitem>
- <programlisting>Section "Monitor"
-Identifier "Monitor1"
-VendorName "Bigname"
-ModelName "BestModel"
-ModeLine "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089
-Option "DPMS"
-EndSection</programlisting>
+ <listitem>
+ <para><filename>Xsession</filename></para>
+ <para>Default session script which
+ <application>XDM</application> runs after a user has
+ logged in. Normally each user will have a customized
+ session script in <filename>~/.xsession</filename> that
+ overrides this script.</para>
+ </listitem>
- <para>Now having completed these simple editing steps, X
- should start on your new widescreen monitor.</para>
+ <listitem>
+ <para><filename>Xsetup_</filename>*</para>
+ <para>Script to indicate which applications
+ automatically run when launching the user's graphical
+ environment. There is a script for each display being
+ used, named <filename>Xsetup_</filename> followed by
+ the local display number. Typically these scripts
+ will run one or two programs such as
+ <application>xconsole</application>.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>xdm-config</filename></para>
+ <para>Global configuration for all displays running
+ on this machine. This file contains settings, in the
+ form of <filename>app-defaults</filename>, which are
+ applicable to every display.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>xdm-errors</filename></para>
+ <para>Errors generated by the X server program. If a
+ display that <application>XDM</application> is trying
+ to start hangs, this is a good place to look for error
+ messages. These messages are also written to the
+ user's <filename>~/.xsession-errors</filename> on
+ a per-session basis.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>xdm-pid</filename></para>
+ <para>The process ID of the currently running XDM.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The default configuration is a simple rectangular login
+ window with the hostname of the machine displayed at the
+ top in a large font and <quote>Login:</quote> and
+ <quote>Password:</quote> prompts below.</para>
+
+ <para>To start <application>GNOME</application> using
+ the <application>XDM</application> display manager, create
+ or edit <filename>.xsession</filename> in your home
+ directory so that it contains these lines:</para>
+
+ <screen>#!/bin/sh</screen>
+
+ <screen>/usr/local/bin/gnome-session</screen>
+
+ <para> Make sure that the file is executable by running this
+ command:</para>
+
+ <screen>&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
+
+ <para>To start <application>Xfce</application> using the
+ <application>XDM</application> display manager, instead use
+ this as the second line in your
+ <filename>.xsession</filename>:</para>
+
+ <screen>/usr/local/bin/startxfce4</screen>
+
+ <sect3>
+ <title>Running a Network Display Server</title>
+
+ <para>To configure other clients to connect to the X
+ server over the network, edit the access control rules and
+ enable the connection listener. To configure
+ <application>XDM</application> to listen for all network
+ connections, quote out this line in
+ <filename>xdm-config</filename> by adding a
+ <keycap>!</keycap> at the beginning of the line:</para>
+
+ <screen>DisplayManager.requestPort: 0</screen>
+
+ <para>Examples of stricter access controls can be found in the
+ example entries in <filename>Xaccess</filename> and
+ &man.xdm.1;. After saving the configuration changes which
+ are appropriate to your network, restart
+ <application>XDM</application> to apply the new
+ configuration.</para>
</sect3>
</sect2>
- </sect1>
- <sect1 id="x-fonts">
- <sect1info>
- <authorgroup>
- <author>
- <firstname>Murray</firstname>
- <surname>Stokely</surname>
- <contrib>Contributed by </contrib>
- </author>
- </authorgroup>
- </sect1info>
- <title>Using Fonts in X11</title>
+ <sect2>
+ <title>Using <application>startx</application></title>
- <sect2 id="type1">
- <title>Type1 Fonts</title>
+ <para>A display manager is not required as any window manager
+ can be started from the command line using
+ <application>startx</application>. To configure
+ <application>startx</application>, create a file named
+ <filename>.xinitrc</filename> in the home directory of your
+ regular user account. If that file already exists, replace
+ the line that starts the current window manager with one
+ that starts the desired window manager.</para>
- <para>The default fonts that ship with X11 are less than ideal
- for typical desktop publishing applications. Large
- presentation fonts show up jagged and unprofessional looking,
- and small fonts in <application>&netscape;</application> are
- almost completely unintelligible. However, there are several
- free, high quality Type1 (&postscript;) fonts available which
- can be readily used with X11. For instance, the URW font
- collection (<filename
- role="package">x11-fonts/urwfonts</filename>) includes high
- quality versions of standard type1 fonts (<trademark
- class="registered">Times Roman</trademark>,
- <trademark class="registered">Helvetica</trademark>, <trademark
- class="registered">Palatino</trademark> and others). The
- Freefonts collection (<filename
- role="package">x11-fonts/freefonts</filename>) includes
- many more fonts, but most of them are intended for use in
- graphics software such as the <application>Gimp</application>,
- and are not complete enough to serve as screen fonts. In
- addition, X11 can be configured to use &truetype; fonts with
- a minimum of effort. For more details on this, see the
- &man.X.7; manual page or the <link linkend="truetype">section
- on &truetype; fonts</link>.</para>
+ <para>For example, to start <application>GNOME</application>,
+ use this line:</para>
- <para>To install the above Type1 font collections from the
- Ports Collection, run the following commands:</para>
+ <programlisting>/usr/local/bin/gnome-session</programlisting>
- <screen>&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput>
-&prompt.root; <userinput>make install clean</userinput></screen>
+ <para> To start <application>KDE</application>, use this
+ line:</para>
- <para>And likewise with the freefont or other collections. To
- have the X server detect these fonts, add an appropriate line
- to the X server configuration file
- (<filename>/etc/X11/xorg.conf</filename>), which reads:</para>
+<programlisting>exec /usr/local/kde4/bin/startkde</programlisting>
+ <para>To start <application>Xfce</application>,use
+ this line:</para>
+
+ <programlisting>/usr/local/bin/startxfce4</programlisting>
+
+ <para>To configure any other window manager, determine the
+ full path to the window manager's executable and add that as
+ the line.</para>
+
+ <para>To start the window manager listed in
+ <filename>~/.xinitrc</filename>, type
+ <application>startx</application>.</para>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="x-fonts">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Murray</firstname>
+ <surname>Stokely</surname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ </sect1info>
+ <title>Configuring Fonts</title>
+
+ <para>This section demonstrates how to install and configure
+ Type1, &truetype;, and anti-aliased fonts on &os;.</para>
+
+ <sect2 id="type1">
+ <title>Type1 Fonts</title>
+
+ <para>The default fonts provided by
+ <application>Xorg</application> are less than ideal for
+ desktop use. There are several free, high quality Type1
+ &postscript; fonts which can be installed using &os; binary
+ packages or ports. For instance, the URW font collection
+ (<filename role="package">x11-fonts/urwfonts</filename>)
+ includes high quality versions of the <trademark
+ class="registered">Times Roman</trademark>,
+ <trademark class="registered">Helvetica</trademark>, and
+ <trademark class="registered">Palatino</trademark> fonts.
+ The Freefonts collection (<filename
+ role="package">x11-fonts/freefonts</filename>) includes
+ many fonts suited for use in graphics software such as the
+ <application>Gimp</application>. Many more fonts are
+ available in the <filename>x11-fonts</filename> category of
+ the Ports Collection</para>
+
+ <para>After installing the desired fonts, configure the X server
+ to detect the new fonts when it starts up. Add a line to
+ <filename>/etc/X11/xorg.conf</filename> containing the
+ full path to the fonts directory. As an example, the
+ following line adds the path to the installed <filename
+ role="package">x11-fonts/urwfonts</filename>:</para>
+
<programlisting>FontPath "/usr/local/lib/X11/fonts/URW/"</programlisting>
- <para>Alternatively, at the command line in the X session
- run:</para>
+ <para>To tell the X server to use the new fonts now, run this
+ command as the superuser:</para>
<screen>&prompt.user; <userinput>xset fp+ /usr/local/lib/X11/fonts/URW</userinput>
&prompt.user; <userinput>xset fp rehash</userinput></screen>
- <para>This will work but will be lost when the X session is
- closed, unless it is added to the startup file
- (<filename>~/.xinitrc</filename> for a normal
- <command>startx</command> session, or
- <filename>~/.xsession</filename> when logging in through a
- graphical login manager like <application>XDM</application>).
- A third way is to use the new
- <filename>/usr/local/etc/fonts/local.conf</filename> file: see
- the section on <link
- linkend="antialias">anti-aliasing</link>.</para>
</sect2>
<sect2 id="truetype">
- <title>&truetype; Fonts</title>
+ <title>&truetype; Fonts</title>
- <indexterm><primary>TrueType Fonts</primary></indexterm>
- <indexterm><primary>fonts</primary>
- <secondary>TrueType</secondary>
- </indexterm>
+ <indexterm><primary>TrueType Fonts</primary></indexterm>
+ <indexterm><primary>fonts</primary>
+ <secondary>TrueType</secondary>
+ </indexterm>
- <para><application>&xorg;</application> has built in support
- for rendering &truetype; fonts. There are two different
- modules that can enable this functionality. The freetype
- module is used in this example because it is more consistent
- with the other font rendering back-ends. To enable the
- freetype module just add the following line to the
- <literal>"Module"</literal> section of the
- <filename>/etc/X11/xorg.conf</filename> file.</para>
+ <para><application>&xorg;</application> can be configured to
+ render &unix; and &windows; &truetype; fonts. To
+ enable the freetype module, add the following line to the
+ <literal>"Module"</literal> section of
+ <filename>/etc/X11/xorg.conf</filename>:</para>
- <programlisting>Load "freetype"</programlisting>
+ <programlisting>Load "freetype"</programlisting>
- <para>Now make a directory for the &truetype; fonts (for
- example,
- <filename>/usr/local/lib/X11/fonts/TrueType</filename>)
- and copy all of the &truetype; fonts into this directory.
- Keep in mind that &truetype; fonts cannot be directly taken
- from a &macintosh;; they must be in &unix;/&ms-dos;/&windows;
- format for use by X11. Once the files have been copied into
- this directory, use <application>ttmkfdir</application> to
- create a <filename>fonts.dir</filename> file, so that the X
- font renderer knows that these new files have been installed.
- <command>ttmkfdir</command> is available from the FreeBSD
+ <para>Next, make a subdirectory of
+ <filename>/usr/local/lib/X11/fonts/TrueType/</filename>
+ and copy the &truetype; fonts into the subdirectory. Then,
+ run the following <application>ttmkfdir</application> command
+ to create <filename>fonts.dir</filename> so that the X font
+ renderer knows that new fonts have been installed.
+ <application>ttmkfdir</application> is available from the &os;
Ports Collection as
<filename role="package">x11-fonts/ttmkfdir</filename>.</para>
<screen>&prompt.root; <userinput>cd /usr/local/lib/X11/fonts/TrueType</userinput>
&prompt.root; <userinput>ttmkfdir -o fonts.dir</userinput></screen>
- <para>Now add the &truetype; directory to the font
- path. This is just the same as described above for <link
- linkend="type1">Type1</link> fonts, that is, use</para>
-
- <screen>&prompt.user; <userinput>xset fp+ /usr/local/lib/X11/fonts/TrueType</userinput>
-&prompt.user; <userinput>xset fp rehash</userinput></screen>
-
- <para>or add a <literal>FontPath</literal> line to the
- <filename>xorg.conf</filename> file.</para>
-
- <para>That's it. Now <application>&netscape;</application>,
- <application>Gimp</application>,
- <application>&staroffice;</application>, and all of the
- other X applications should now recognize the installed
- &truetype; fonts. Extremely small fonts (as with text in a
- high resolution display on a web page) and extremely large
- fonts (within <application>&staroffice;</application>) will
- look much better now.</para>
+ <para>To load the new fonts whenever the X server starts, add
+ the &truetype; path to <filename>/etc/X11/xorg.conf</filename>
+ as described above for <link linkend="type1">Type1</link>
+ fonts.</para>
</sect2>
<sect2 id="antialias">
- <sect2info>
- <authorgroup>
- <author>
- <firstname>Joe Marcus</firstname>
- <surname>Clarke</surname>
- <contrib>Updated by </contrib>
- <!-- May 2003 -->
+ <sect2info>
+ <authorgroup>
+ <author>
+ <firstname>Joe Marcus</firstname>
+ <surname>Clarke</surname>
+ <contrib>Updated by </contrib>
+ <!-- May 2003 -->
</author>
</authorgroup>
</sect2info>
@@ -962,8 +805,9 @@
<indexterm><primary>fonts</primary>
<secondary>anti-aliased</secondary></indexterm>
- <para>All fonts in X11 that are found
- in <filename>/usr/local/lib/X11/fonts/</filename> and
+ <para>The X FreeType (Xft) library is used by the freetype module
+ to provide anti-aliased fonts. All fonts within
+ <filename>/usr/local/lib/X11/fonts/</filename> and
<filename>~/.fonts/</filename> are automatically
made available for anti-aliasing to Xft-aware applications.
Most recent applications are Xft-aware, including
@@ -972,13 +816,10 @@
<application>Firefox</application>.</para>
<para>In order to control which fonts are anti-aliased, or to
- configure anti-aliasing properties, create (or edit, if it
- already exists) the file
+ configure anti-aliasing properties, create or edit
<filename>/usr/local/etc/fonts/local.conf</filename>. Several
advanced features of the Xft font system can be tuned using
- this file; this section describes only some simple
- possibilities. For more details, please see
- &man.fonts-conf.5;.</para>
+ this file. For more examples, see &man.fonts-conf.5;.</para>
<indexterm><primary>XML</primary></indexterm>
@@ -988,33 +829,24 @@
definition, and then the <literal><fontconfig></literal>
tag:</para>
- <programlisting>
- <?xml version="1.0"?>
- <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
- <fontconfig></programlisting>
+ <para>If you wish to add another directory outside of the two
+ default font directory trees, add a line containing the full
+ path to
+ <filename>/usr/local/etc/fonts/local.conf</filename>
+ using this format:</para>
- <para>As previously stated, all fonts in
- <filename>/usr/local/lib/X11/fonts/</filename> as well as
- <filename>~/.fonts/</filename> are already made available to
- Xft-aware applications. If you wish to add another directory
- outside of these two directory trees, add a line similar to the
- following to
- <filename>/usr/local/etc/fonts/local.conf</filename>:</para>
+<programlisting><dir>/path/to/my/fonts</dir></programlisting>
- <programlisting><dir>/path/to/my/fonts</dir></programlisting>
+ <para>After adding new font directories, run the following command
+ to rebuild the font caches:</para>
- <para>After adding new fonts, and especially new font directories,
- you should run the following command to rebuild the font
- caches:</para>
-
<screen>&prompt.root; <userinput>fc-cache -f</userinput></screen>
<para>Anti-aliasing makes borders slightly fuzzy, which makes
- very small text more readable and removes
- <quote>staircases</quote> from large text, but can cause
- eyestrain if applied to normal text. To exclude font sizes
- smaller than 14 point from anti-aliasing, include these
- lines:</para>
+ very small text more readable and removes staircases from large
+ text, but can cause eyestrain if applied to normal text. To
+ exclude font sizes smaller than 14 point from anti-aliasing,
+ add these lines:</para>
<programlisting> <match target="font">
<test name="size" compare="less">
@@ -1039,10 +871,11 @@
<para>Spacing for some monospaced fonts may also be inappropriate
with anti-aliasing. This seems to be an issue with
<application>KDE</application>, in particular. One possible
- fix for this is to force the spacing for such fonts to be 100.
- Add the following lines:</para>
+ fix is to force the spacing for such fonts to be 100 by
+ adding the following lines:</para>
- <programlisting> <match target="pattern" name="family">
+ <programlisting> <match target="pattern"
+name="family">
<test qual="any" name="family">
<string>fixed</string>
</test>
@@ -1057,12 +890,9 @@
<edit name="family" mode="assign">
<string>mono</string>
</edit>
- </match></programlisting>
+ </match>
- <para>(this aliases the other common names for fixed fonts as
- <literal>"mono"</literal>), and then add:</para>
-
- <programlisting> <match target="pattern" name="family">
+ <match target="pattern" name="family">
<test qual="any" name="family">
<string>mono</string>
</test>
@@ -1074,11 +904,10 @@
<para>Certain fonts, such as Helvetica, may have a problem when
anti-aliased. Usually this manifests itself as a font that
seems cut in half vertically. At worst, it may cause
- applications to
- crash. To avoid this, consider adding the following to
- <filename>local.conf</filename>:</para>
+ applications to crash. To avoid this, consider adding the
+ following lines:</para>
- <programlisting> <match target="pattern" name="family">
+<programlisting> <match target="pattern" name="family">
<test qual="any" name="family">
<string>Helvetica</string>
</test>
@@ -1087,30 +916,16 @@
</edit>
</match> </programlisting>
- <para>Once you have finished editing
- <filename>local.conf</filename> make sure you end the file
- with the <literal></fontconfig></literal> tag. Not
- doing this will cause your changes to be ignored.</para>
+ <indexterm><primary>LCD screen</primary></indexterm>
+ <indexterm><primary>Fonts</primary>
+ <secondary>LCD screen</secondary></indexterm>
- <para>Finally, users can add their own settings via their
- personal <filename>.fonts.conf</filename> files. To do
- this, each user should simply create a
- <filename>~/.fonts.conf</filename>. This file must also be
- in XML format.</para>
+ <para>When using an LCD screen, sub-pixel sampling may be
+ desired as it treats the horizontally separated red, green
+ and blue components separately to improve horizontal
+ resolution. To enable this, add these lines:</para>
- <indexterm><primary>LCD screen</primary></indexterm>
- <indexterm><primary>Fonts</primary>
- <secondary>LCD screen</secondary></indexterm>
-
- <para>One last point: with an LCD screen, sub-pixel sampling
- may be desired. This basically treats the (horizontally
- separated) red, green and blue components separately to
- improve the horizontal resolution; the results can be
- dramatic. To enable this, add the line somewhere in the
- <filename>local.conf</filename> file:</para>
-
- <programlisting>
- <match target="font">
+ <programlisting> <match target="font">
<test qual="all" name="rgba">
<const>unknown</const>
</test>
@@ -1119,692 +934,230 @@
</edit>
</match></programlisting>
- <note>
- <para>Depending on the sort of display,
- <literal>rgb</literal> may need to be changed to
- <literal>bgr</literal>, <literal>vrgb</literal> or
- <literal>vbgr</literal>: experiment and see which works
- best.</para>
- </note>
- </sect2>
- </sect1>
+ <para>Depending on the display, <literal>rgb</literal> may
+ need to be changed to <literal>bgr</literal>,
+ <literal>vrgb</literal> or <literal>vbgr</literal>.</para>
- <sect1 id="x-xdm">
- <sect1info>
- <authorgroup>
- <author>
- <firstname>Seth</firstname>
- <surname>Kingsley</surname>
- <contrib>Contributed by </contrib>
- </author>
- </authorgroup>
- </sect1info>
- <title>The X Display Manager</title>
- <sect2>
+ <para>Before saving your edits, make sure the file ends
+ with the <literal></fontconfig></literal> tag. Not
+ doing this will cause the changes to be ignored.</para>
- <title>Overview</title>
-
- <indexterm><primary>X Display Manager</primary></indexterm>
- <para>The X Display Manager (<application>XDM</application>)
- is an optional part of the X Window System that is used for
- login session management. This is useful for several types
- of situations, including minimal <quote>X Terminals</quote>,
- desktops, and large network display servers. Since the X
- Window System is network and protocol independent, there are
- a wide variety of possible configurations for running X
- clients and servers on different machines connected by a
- network. <application>XDM</application> provides a graphical
- interface for choosing which display server to connect to,
- and entering authorization information such as a login and
- password combination.</para>
-
- <para>Think of <application>XDM</application> as
- providing the same functionality to the user as the
- &man.getty.8; utility (see <xref linkend="term-config"/> for
- details). That is, it performs system logins to the display
- being connected to and then runs a session manager on
- behalf of the user (usually an X window manager).
- <application>XDM</application> then waits for this program to
- exit, signaling that the user is done and should be logged out
- of the display. At this point, <application>XDM</application>
- can display the login and display chooser screens for the next
- user to login.</para>
+ <para>Users can add their own settings by creating
+ <filename>.fonts.conf</filename> in their home
+ directory.</para>
</sect2>
+ </sect1>
- <sect2>
- <title>Using XDM</title>
+ <sect1 id="x11-understanding">
+ <title>Troubleshooting</title>
- <para>To start using <application>XDM</application>, install
- the <filename role="package">x11/xdm</filename> port (it is
- not installed by default in recent versions of
- <application>&xorg;</application>). The
- <application>XDM</application> daemon program may then be
- found in <filename>/usr/local/bin/xdm</filename>. This
- program can be run at any time as <username>root</username>
- and it will start managing the X display on the local machine.
- If <application>XDM</application> is to be run every
- time the machine boots up, a convenient way to do this is by
- adding an entry to <filename>/etc/ttys</filename>. For more
- information about the format and usage of this file, see <xref
- linkend="term-etcttys"/>. There is a line in the default
- <filename>/etc/ttys</filename> file for running the
- <application>XDM</application> daemon on a virtual
- terminal:</para>
+ <para>This section describes some common troubleshooting scenarios
+ for when <filename>Xorg</filename> does not automatically detect
+ and configure the hardware.</para>
- <screen>ttyv8 "/usr/local/bin/xdm -nodaemon" xterm off secure</screen>
-
- <para>By default this entry is disabled; in order to enable it
- change field 5 from <literal>off</literal> to
- <literal>on</literal> and restart &man.init.8; using the
- directions in <xref linkend="term-hup"/>. The first field,
- the name of the terminal this program will manage, is
- <literal>ttyv8</literal>. This means that
- <application>XDM</application> will start running on the 9th
- virtual terminal.</para>
- </sect2>
-
<sect2>
- <title>Configuring XDM</title>
+ <title>Mouse</title>
- <para>The <application>XDM</application> configuration directory
- is located in <filename>/usr/local/lib/X11/xdm</filename>.
- In this directory there are several files used to change the
- behavior and appearance of
- <application>XDM</application>. Typically these files will
- be found:</para>
+ <para>If the mouse does not work, configure it first using the
+ instructions in <xref linkend="mouse"/> of the &os; install
+ chapter. In recent <application>Xorg</application> versions,
+ the <literal>InputDevice</literal> sections in
+ <filename>/etc/X11/xorg.conf</filename> are ignored in favor
+ of the autodetected devices. To force the old behavior, add
+ the following line to the <literal>ServerLayout</literal> or
+ <literal>ServerFlags</literal> section of this file:</para>
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>File</entry>
- <entry>Description</entry>
- </row>
- </thead>
+ <programlisting>Option "AutoAddDevices" "false"</programlisting>
- <tbody>
- <row>
- <entry><filename>Xaccess</filename></entry>
- <entry>Client authorization ruleset.</entry>
- </row>
-
- <row>
- <entry><filename>Xresources</filename></entry>
- <entry>Default X resource values.</entry>
- </row>
-
- <row>
- <entry><filename>Xservers</filename></entry>
- <entry>List of remote and local displays to
- manage.</entry>
- </row>
-
- <row>
- <entry><filename>Xsession</filename></entry>
- <entry>Default session script for logins.</entry>
- </row>
-
- <row>
- <entry><filename>Xsetup_</filename>*</entry>
- <entry>Script to launch applications before the login
- interface.</entry>
- </row>
-
- <row>
- <entry><filename>xdm-config</filename></entry>
- <entry>Global configuration for all displays running
- on this machine.</entry>
- </row>
-
- <row>
- <entry><filename>xdm-errors</filename></entry>
- <entry>Errors generated by the server program.</entry>
- </row>
-
- <row>
- <entry><filename>xdm-pid</filename></entry>
- <entry>The process ID of the currently running
- XDM.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>Also in this directory are a few scripts and programs
- used to set up the desktop when <application>XDM</application>
- is running. The purpose of each of these files will be
- briefly described. The exact syntax and usage of all of
- these files is described in &man.xdm.1;.</para>
-
- <para>The default configuration is a simple rectangular login
- window with the hostname of the machine displayed at the
- top in a large font and <quote>Login:</quote> and
- <quote>Password:</quote> prompts below. This is a good
- starting point for changing the look and feel of
- <application>XDM</application> screens.</para>
-
- <sect3>
- <title>Xaccess</title>
-
- <para>The protocol for connecting to
- <application>XDM</application>-controlled displays is
- called the X Display Manager Connection Protocol (XDMCP).
- This file is a ruleset for controlling XDMCP connections
- from remote machines. It is ignored unless the
- <filename>xdm-config</filename> is changed to listen for
- remote connections. By default, it does not allow any
- clients to connect.</para>
- </sect3>
-
- <sect3>
- <title>Xresources</title>
-
- <para>This is an application-defaults file for the display
- chooser and login screens. In it, the appearance
- of the login program can be modified. The format is
- identical to the app-defaults file described in the
- X11 documentation.</para>
- </sect3>
-
- <sect3>
- <title>Xservers</title>
-
- <para>This is a list of the remote displays the chooser should
- provide as choices.</para>
- </sect3>
-
- <sect3>
- <title>Xsession</title>
-
- <para>This is the default session script for
- <application>XDM</application> to run after a user has
- logged in. Normally each user will have a customized
- session script in <filename>~/.xsession</filename> that
- overrides this script.</para>
- </sect3>
-
- <sect3>
- <title>Xsetup_*</title>
-
- <para>These will be run automatically before displaying the
- chooser or login interfaces. There is a script for each
- display being used, named <filename>Xsetup_</filename>
- followed by the local display number (for instance
- <filename>Xsetup_0</filename>). Typically these scripts
- will run one or two programs in the background such as
- <command>xconsole</command>.</para>
- </sect3>
-
- <sect3>
- <title>xdm-config</title>
-
- <para>This contains settings in the form of app-defaults
- that are applicable to every display that this installation
- manages.</para>
- </sect3>
-
- <sect3>
- <title>xdm-errors</title>
-
- <para>This contains the output of the X servers that
- <application>XDM</application> is trying to run. If a
- display that <application>XDM</application> is trying to
- start hangs for some reason, this is a good place to look
- for error messages. These messages are also written to the
- user's <filename>~/.xsession-errors</filename> file on a
- per-session basis.</para>
- </sect3>
+ <para>Input devices may then be configured manually within
+ the file.</para>
</sect2>
-
<sect2>
- <title>Running a Network Display Server</title>
+ <title>Keyboard</title>
- <para>In order for other clients to connect to the display
- server, you must edit the access control rules and enable
- the connection listener. By default these are set to
- conservative values. To make <application>XDM</application>
- listen for connections, first comment out a line in the
- <filename>xdm-config</filename> file:</para>
+ <para>If <application>hald</application> incorrectly detects
+ the keyboard layout or model, use the graphical tools provided
+ by desktop environments like <application>GNOME</application>,
+ <application>KDE</application> or
+ <application>Xfce</application> to configure the keyboard.
+ It is also possible to set the keyboard properties directly
+ using the &man.setxkbmap.1; utility or with a
+ <application>hald</application> configuration rule.</para>
- <screen>! SECURITY: do not listen for XDMCP or Chooser requests
-! Comment out this line if you want to manage X terminals with xdm
-DisplayManager.requestPort: 0</screen>
+ <para>For example, to set a PC 102 keys keyboard with a French
+ layout, create or edit the keyboard configuration file for
+ <application>hald</application> called <filename
+class="directory">/usr/local/etc/hal/fdi/policy/x11-input.fdi</filename>.
+ This file should contain the following lines:</para>
- <para>and then restart <application>XDM</application>.
- Remember that comments in app-defaults files begin with a
- <quote>!</quote> character, not the usual <quote>#</quote>.
- More strict access controls may be desired — look at the
- example entries in <filename>Xaccess</filename>, and refer to
- the &man.xdm.1; manual page for further information.</para>
- </sect2>
+ <programlisting><?xml version="1.0"
+encoding="iso-8859-1"?>
+<deviceinfo version="0.2">
+ <device>
+ <match key="info.capabilities" contains="input.keyboard">
+ <merge key="input.x11_options.XkbModel" type="string">pc102</merge>
+ <merge key="input.x11_options.XkbLayout" type="string">fr</merge>
+ </match>
+ </device>
+</deviceinfo></programlisting>
- <sect2>
- <title>Replacements for XDM</title>
+ <para>Reboot the system to test the configuration.</para>
- <para>Several replacements for the default
- <application>XDM</application> program exist. One of them,
- <application>KDM</application> (bundled with
- <application>KDE</application>) is described later in this
- chapter. The <application>KDM</application> display
- manager offers many visual improvements and cosmetic frills,
- as well as the functionality to allow users to choose their
- window manager of choice at login time.</para>
- </sect2>
- </sect1>
+ <para>Alternately, you can temporarily configure this
+ setting for the current session by typing this command:</para>
- <sect1 id="x11-wm">
- <sect1info>
- <authorgroup>
- <author>
- <firstname>Valentino</firstname>
- <surname>Vaschetto</surname>
- <contrib>Contributed by </contrib>
- </author>
- <!-- June 2001 -->
- </authorgroup>
- </sect1info>
+ <screen>&prompt.user; <userinput>setxkbmap -model pc102 -layout fr</userinput></screen>
- <title>Desktop Environments</title>
+ <para>
+ <filename>/usr/local/share/X11/xkb/rules/base.lst</filename>
+ lists the available keyboard, layouts, and options.</para>
+ </sect2>
+ <sect2>
+ <title>Monitor</title>
- <para>This section describes the different desktop environments
- available for X on FreeBSD. A <quote>desktop
- environment</quote> can mean anything ranging from a simple
- window manager to a complete suite of desktop applications, such
- as <application>KDE</application> or
- <application>GNOME</application>.</para>
+ <indexterm><primary>X11 tuning</primary></indexterm>
- <sect2 id="x11-wm-gnome">
- <title>GNOME</title>
+ <para>Most monitors support sync frequency autodetection. If
+ the monitor is an older or unusual model that does not
+ support autodetection, those settings can be manually added
+ under the <literal>"Monitor"</literal> section. To avoid
+ potential damage, only enter the values provided by the
+ manufacturer. </para>
- <sect3 id="x11-wm-gnome-about">
- <title>About GNOME</title>
+ <programlisting>Section "Monitor"
+ Identifier "Monitor0"
+ VendorName "Monitor Vendor"
+ ModelName "Monitor Model"
+ HorizSync 30-107
+ VertRefresh 48-120
+EndSection</programlisting>
- <indexterm><primary>GNOME</primary></indexterm>
- <para><application>GNOME</application> is a user-friendly
- desktop environment that enables users to easily use and
- configure their computers. <application>GNOME</application>
- includes a panel (for starting applications and displaying
- status), a desktop (where data and applications can be
- placed), a set of standard desktop tools and applications,
- anda set of conventions that make it easy for applications
- to cooperate and be consistent with each other. Users of
- other operating systems or environments should feel right
- at home using the powerful graphics-driven environment that
- <application>GNOME</application> provides. More
- information regarding <application>GNOME</application> on
- FreeBSD can be found on the <ulink
- url="http://www.FreeBSD.org/gnome">FreeBSD GNOME
- Project</ulink>'s web site. The web site also contains
- fairly comprehensive FAQs about installing, configuring,
- and managing <application>GNOME</application>.</para>
- </sect3>
+ <para><application>Xorg</application> allows DPMS (Energy Star)
+ features to be used with capable monitors. The &man.xset.1;
+ program controls the time-outs and can force standby, suspend,
+ or off modes. To enable DPMS, add the following line to the
+ <literal>"Monitor"</literal> section:</para>
- <sect3 id="x11-wm-gnome-install">
- <title>Installing GNOME</title>
+ <programlisting>Option "DPMS"</programlisting>
- <para>The software can be easily installed from a package
- or the Ports Collection:</para>
+ <indexterm>
+ <primary><filename>xorg.conf</filename></primary>
+ </indexterm>
- <para>To install the <application>GNOME</application> package
- from the network, simply type:</para>
+ <para>Then, define the resolution and color depth in the
+ <literal>"Screen"</literal> section:</para>
- <screen>&prompt.root; <userinput>pkg_add -r gnome2</userinput></screen>
+ <programlisting>Section "Screen"
+ Identifier "Screen0"
+ Device "Card0"
+ Monitor "Monitor0"
+ DefaultDepth 24
+ SubSection "Display"
+ Viewport 0 0
+ Depth 24
+ Modes "1024x768"
+ EndSubSection
+EndSection</programlisting>
- <para>To build <application>GNOME</application> from source,
- use the ports tree:</para>
+ <para>The <literal>DefaultDepth</literal> keyword describes
+ the color depth to run by default. This can be overridden
+ with the <option>-depth</option> command line switch to
+ &man.Xorg.1;. The <literal>Modes</literal> keyword describes
+ the resolution to run for the given color depth. Note that only
+ VESA standard modes are supported as defined by the graphics
+ hardware. In the example above, the default color depth is
+ twenty-four bits per pixel. At this color depth, the accepted
+ resolution is 1024 by 768 pixels.</para>
+ </sect2>
+ <sect2>
+ <title>Configuration with &intel; <literal>i810</literal>
+ Graphics Chipsets</title>
- <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
-&prompt.root; <userinput>make install clean</userinput></screen>
+ <indexterm><primary>Intel i810 graphic chipset</primary></indexterm>
- <para>For proper operation, <application>GNOME</application>
- requires the <filename>/proc</filename> filesystem to be
- mounted. Add</para>
+ <para>&intel; i810 integrated chipsets
+ require the &man.agp.4; driver to be compiled in the kernel.
+ The <filename>GENERIC</filename> kernel includes this driver
+ so this is only a consideration for custom kernels.</para>
+ </sect2>
- <programlisting>proc /proc procfs rw 0 0</programlisting>
+ <sect2>
+ <title>Configuring a Widescreen Flatpanel</title>
- <para>to <filename>/etc/fstab</filename> to mount
- &man.procfs.5; automatically during
- startup.</para>
+ <indexterm><primary>widescreen flatpanel configuration</primary></indexterm>
- <para>Once <application>GNOME</application> is installed,
- the X server must be told to start
- <application>GNOME</application> instead of a default window
- manager.</para>
+ <para>Widescreen formats such as WSXGA, WSXGA+, WUXGA, WXGA, and
+ WXGA+ support 16:10 and 10:9 formats or aspect ratios that
+ may need to be manually configured. Examples of common screen
+ resolutions for 16:10 aspect ratios include:</para>
- <para>The easiest way to start
- <application>GNOME</application> is with
- <application>GDM</application>, the GNOME Display Manager.
- <application>GDM</application> is installed as part
- of the <application>GNOME</application> desktop, although
- it is disabled by default. It can be enabled by adding this
- line to <filename>/etc/rc.conf</filename>:</para>
+ <itemizedlist>
+ <listitem><para>2560x1600</para></listitem>
+ <listitem><para>1920x1200</para></listitem>
+ <listitem><para>1680x1050</para></listitem>
+ <listitem><para>1440x900</para></listitem>
+ <listitem><para>1280x800</para></listitem>
+ </itemizedlist>
- <programlisting>gdm_enable="YES"</programlisting>
+ <para>These resolutions can be added as a possible
+ <literal>Mode</literal> in the <literal>Section
+ "Screen"</literal>:</para>
- <para>Once you have rebooted,
- <application>GDM</application> will start
- automatically.</para>
+ <programlisting>Section "Screen"
+Identifier "Screen0"
+Device "Card0"
+Monitor "Monitor0"
+DefaultDepth 24
+SubSection "Display"
+ Viewport 0 0
+ Depth 24
+ Modes "1680x1050"
+EndSubSection
+EndSection</programlisting>
- <para>It is often desirable to start all
- <application>GNOME</application> services together with
- <application>GDM</application>. To achieve this, add the
- following line to <filename>/etc/rc.conf</filename>:</para>
+ <para><application>&xorg;</application> can detect the
+ widescreen's I2C/DDC information so that it knows which
+ frequencies and resolutions the monitor can handle.</para>
- <programlisting>gnome_enable="YES"</programlisting>
+ <para>If those <literal>ModeLines</literal> do not exist in
+ the driver, use <filename>/var/log/Xorg.0.log</filename> to
+ extract the information to manually create a working
+ <literal>ModeLine</literal> entry. Look
+ for information resembling this:</para>
- <para><application>GNOME</application> may also be started
- from the command-line by properly configuring a file named
- <filename>.xinitrc</filename>.
- If a custom <filename>.xinitrc</filename> is already in
- place, simply replace the line that starts the current
- window manager with one that starts
- <application>/usr/local/bin/gnome-session</application>
- instead. If nothing special has been done to the
- configuration file, then it is enough simply to type:</para>
+ <programlisting>(II) MGA(0): Supported additional Video Mode:
+(II) MGA(0): clock: 146.2 MHz Image Size: 433 x 271 mm
+(II) MGA(0): h_active: 1680 h_sync: 1784 h_sync_end 1960 h_blank_end 2240 h_border: 0
+(II) MGA(0): v_active: 1050 v_sync: 1053 v_sync_end 1059 v_blanking: 1089 v_border: 0
+(II) MGA(0): Ranges: V min: 48 V max: 85 Hz, H min: 30 H max: 94 kHz, PixClock max 170 MHz</programlisting>
- <screen>&prompt.user; <userinput>echo "/usr/local/bin/gnome-session" > ~/.xinitrc</userinput></screen>
+ <para>This information is called EDID information. Creating a
+ <literal>ModeLine</literal> from this is a matter of putting
+ the numbers in the correct order:</para>
- <para>Next, type <command>startx</command>, and the
- <application>GNOME</application> desktop environment will
- be started.</para>
+ <programlisting>ModeLine <name> <clock> <4 horiz. timings> <4 vert. timings></programlisting>
- <note><para>If an older display manager, like
- <application>XDM</application>, is being used, this will
- not work. Instead, create an executable
- <filename>.xsession</filename> file with the same command
- in it. To do this, edit the file and replace the existing
- window manager command with
- <application>/usr/local/bin/gnome-session</application>:
- </para></note>
+ <para>The <literal>ModeLine</literal> in
+ <literal>Section "Monitor"</literal> for this example would
+ look like this:</para>
- <screen>&prompt.user; <userinput>echo "#!/bin/sh" > ~/.xsession</userinput>
-&prompt.user; <userinput>echo "/usr/local/bin/gnome-session" >> ~/.xsession</userinput>
-&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
+ <programlisting>Section "Monitor"
+Identifier "Monitor1"
+VendorName "Bigname"
+ModelName "BestModel"
+ModeLine "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089
+Option "DPMS"
+EndSection</programlisting>
+ </sect2>
+ <sect2>
+ <title>Testing <filename>/etc/X11/xorg.conf</filename> Changes</title>
- <para>Yet another option is to configure the display manager
- to allow choosing the window manager at login time; the
- section on
- <link linkend="x11-wm-kde-details">KDE details</link>
- explains how to do this for <application>KDM</application>,
- the display manager of
- <application>KDE</application>.</para>
- </sect3>
- </sect2>
+ <para>Whenever you make a configuration change to
+ <filename>/etc/X11/xorg.conf></filename>, restart the X server
+ to test the configuraiton change.</para>
- <sect2 id="x11-wm-kde">
- <title>KDE</title>
-
- <indexterm><primary>KDE</primary></indexterm>
- <sect3 id="x11-wm-kde-about">
- <title>About KDE</title>
-
- <para><application>KDE</application> is an easy to use
- contemporary desktop environment. Some of the things
- that <application>KDE</application> brings to the user
- are:</para>
-
- <itemizedlist>
- <listitem>
- <para>A beautiful contemporary desktop</para>
- </listitem>
-
- <listitem>
- <para>A desktop exhibiting complete network
- transparency</para>
- </listitem>
-
- <listitem>
- <para>An integrated help system allowing for convenient,
- consistent access to help on the use of the
- <application>KDE</application> desktop and its
- applications</para>
- </listitem>
-
- <listitem>
- <para>Consistent look and feel of all
- <application>KDE</application> applications</para>
- </listitem>
-
- <listitem>
- <para>Standardized menu and toolbars, keybindings,
- color-schemes, etc.</para>
- </listitem>
-
- <listitem>
- <para>Internationalization: <application>KDE</application>
- is available in more than 55 languages</para>
- </listitem>
-
- <listitem>
- <para>Centralized, consistent, dialog-driven desktop
- configuration</para>
- </listitem>
-
- <listitem>
- <para>A great number of useful
- <application>KDE</application> applications</para>
- </listitem>
- </itemizedlist>
-
- <para><application>KDE</application> comes with a web
- browser called <application>Konqueror</application>, which
- is a solid competitor to other existing web browsers on
- &unix; systems. More information on
- <application>KDE</application> can be found on the <ulink
- url="http://www.kde.org/">KDE website</ulink>. For FreeBSD
- specific information and resources on
- <application>KDE</application>, consult the <ulink
- url="http://freebsd.kde.org/">KDE/FreeBSD
- initiative</ulink>'s website.</para>
-
- <para>There are two versions of
- <application>KDE</application> available on FreeBSD.
- Version 3 has been around for a long time, and is still
- available in the Ports Collection though it's now
- unmaintained and partially broken. Version 4 is
- punctually updated and is the default choice for
- <application>KDE</application> users. They can even be
- installed side by side.</para>
- </sect3>
-
- <sect3 id="x11-wm-kde-install">
- <title>Installing KDE</title>
-
- <para>Just as with <application>GNOME</application> or any
- other desktop environment, the software can be easily
- installed from a package or the Ports Collection:</para>
-
- <para>To install the <application>KDE 3</application> package
- from the network, type:</para>
-
- <screen>&prompt.root; <userinput>pkg_add -r kde</userinput></screen>
-
- <para>To install the <application>KDE 4</application> package
- from the network, type:</para>
-
- <screen>&prompt.root; <userinput>pkg_add -r kde4</userinput></screen>
-
- <para>&man.pkg.add.1; will automatically fetch the latest
- version of the application.</para>
-
- <para>To build <application>KDE 3</application> from source,
- use the ports tree:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde3</userinput>
-&prompt.root; <userinput>make install clean</userinput></screen>
-
- <para>To build <application>KDE 4</application> from source,
- use the ports tree:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde4</userinput>
-&prompt.root; <userinput>make install clean</userinput></screen>
-
- <para>After <application>KDE</application> has been installed,
- the X server must be told to launch this application
- instead of the default window manager. This is accomplished
- by editing the <filename>.xinitrc</filename> file:</para>
-
- <para>For <application>KDE 3</application>:</para>
-
- <screen>&prompt.user; <userinput>echo "exec startkde" > ~/.xinitrc</userinput></screen>
-
- <para>For <application>KDE 4</application>:</para>
-
- <screen>&prompt.user; <userinput>echo "exec /usr/local/kde4/bin/startkde" > ~/.xinitrc</userinput></screen>
-
- <para>Now, whenever the X Window System is invoked with
- <command>startx</command>,
- <application>KDE</application> will be the desktop.</para>
-
- <para>If a display manager such as
- <application>XDM</application> is being used, the
- configuration is slightly different. Edit the
- <filename>.xsession</filename> file instead. Instructions
- for <application>KDM</application> are described later in
- this chapter.</para>
- </sect3>
- </sect2>
-
- <sect2 id="x11-wm-kde-details">
- <title>More Details on KDE</title>
-
- <para>Now that <application>KDE</application> is installed
- on the system, most things can be discovered through the
- help pages, or just by pointing and clicking at various
- menus. &windows; or &mac; users will feel quite at
- home.</para>
-
- <para>The best reference for <application>KDE</application>
- is the on-line documentation.
- <application>KDE</application> comes with its own web
- browser, <application>Konqueror</application>, dozens of
- useful applications, and extensive documentation. The
- remainder of this section discusses the technical items
- that are difficult to learn by random exploration.</para>
-
- <sect3 id="x11-wm-kde-kdm">
- <title>The KDE Display Manager</title>
-
- <indexterm><primary>KDE</primary>
- <secondary>display manager</secondary></indexterm>
- <para>An administrator of a multi-user system may wish to
- have a graphical login screen to welcome users.
- <link linkend="x-xdm">XDM</link> can be used, as described
- earlier. However, <application>KDE</application> includes
- an alternative, <application>KDM</application>, which is
- designed to look more attractive and include more login-time
- options. In particular, users can easily choose (via a
- menu) which desktop environment
- (<application>KDE</application>,
- <application>GNOME</application>, or something else) to
- run after logging on.</para>
-
- <para>To enable <application>KDM</application>, different
- files need to be edited depending on the version of
- <application>KDE</application>.</para>
-
- <para>For <application>KDE 3</application>, the
- <literal>ttyv8</literal> entry in
- <filename>/etc/ttys</filename> has to be adapted as
- follows:</para>
-
- <programlisting>ttyv8 "/usr/local/bin/kdm -nodaemon" xterm on secure</programlisting>
-
- <para>For <application>KDE 4</application>, you have to mount
- &man.procfs.5; and add the following line to
- <filename>/etc/rc.conf</filename>:</para>
-
- <programlisting>kdm4_enable="YES"</programlisting>
- </sect3>
-
- </sect2>
-
- <sect2 id="x11-wm-xfce">
- <title>Xfce</title>
- <sect3 id="x11-wm-xfce-about">
-
- <title>About Xfce</title>
-
- <para><application>Xfce</application> is a desktop environment
- based on the GTK+
- toolkit used by <application>GNOME</application>, but is
- much more lightweight and meant for those who want a simple,
- efficient desktop which is nevertheless easy to use and
- configure. Visually, it looks very much like
- <application>CDE</application>, found on commercial &unix;
- systems. Some of <application>Xfce</application>'s features
- are:</para>
-
- <itemizedlist>
- <listitem>
- <para>A simple, easy-to-handle desktop</para>
- </listitem>
-
- <listitem>
- <para>Fully configurable via mouse, with drag and
- drop, etc.</para>
- </listitem>
-
- <listitem>
- <para>Main panel similar to
- <application>CDE</application>, with menus, applets
- and applications launchers</para>
- </listitem>
-
- <listitem>
- <para>Integrated window manager, file manager, sound
- manager, <application>GNOME</application> compliance
- module, and more</para>
- </listitem>
-
- <listitem>
- <para>Themeable (since it uses GTK+)</para>
- </listitem>
-
- <listitem>
- <para>Fast, light and efficient: ideal for older/slower
- machines or machines with memory limitations</para>
- </listitem>
- </itemizedlist>
-
- <para>More information on <application>Xfce</application>
- can be found on the <ulink url="http://www.xfce.org/">Xfce
- website</ulink>.</para>
- </sect3>
-
- <sect3 id="x11-wm-xfce-install">
- <title>Installing Xfce</title>
-
- <para>A binary package for <application>Xfce</application>
- exists (at the time of writing). To install, simply
- type:</para>
-
- <screen>&prompt.root; <userinput>pkg_add -r xfce4</userinput></screen>
-
- <para>Alternatively, to build from source, use the
- Ports Collection:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce4</userinput>
-&prompt.root; <userinput>make install clean</userinput></screen>
-
- <para>Now, tell the X server to launch
- <application>Xfce</application> the next time X is started.
- Simply type this:</para>
-
- <screen>&prompt.user; <userinput>echo "/usr/local/bin/startxfce4" > ~/.xinitrc</userinput></screen>
-
- <para>The next time X is started,
- <application>Xfce</application> will be the desktop.
- As before, if a display manager like
- <application>XDM</application> is being used, create an
- <filename>.xsession</filename>, as described in the
- section on <link linkend="x11-wm-gnome">GNOME</link>, but
- with the <filename>/usr/local/bin/startxfce4</filename>
- command; or, configure the display manager to allow
- choosing a desktop at login time, as explained in
- the section on
- <link linkend="x11-wm-kde-kdm">kdm</link>.</para>
- </sect3>
- </sect2>
- </sect1>
+ <para>If your change did not work as expected, look for errors in
+ <filename>/var/log/Xorg.0.log</filename>.</para>
+ </sect2>
+</sect1>
</chapter>
Index: x11/Makefile
===================================================================
--- x11/Makefile (revision 40692)
+++ x11/Makefile (working copy)
@@ -1,15 +1,108 @@
#
-# Build the Handbook with just the content from this chapter.
-#
# $FreeBSD$
#
+# Build the FreeBSD Handbook.
+#
-CHAPTERS= x11/chapter.xml
+# ------------------------------------------------------------------------
+#
+# Handbook-specific variables
+#
+# WITH_PGPKEYS The print version of the handbook only prints PGP
+# fingerprints by default. If you would like for the
+# entire key to be displayed, then set this variable.
+# This option has no affect on the HTML formats.
+#
+# Handbook-specific targets
+#
+# pgpkeyring This target will read the contents of
+# pgpkeys/chapter.xml and will extract all of
+# the pgpkeys to standard out. This output can then
+# be redirected into a file and distributed as a
+# public keyring of FreeBSD developers that can
+# easily be imported into PGP/GPG.
+#
+# ------------------------------------------------------------------------
+#
+# To add a new chapter to the Handbook:
+#
+# - Update this Makefile, chapters.ent and book.xml
+# - Add a descriptive entry for the new chapter in preface/preface.xml
+#
+# ------------------------------------------------------------------------
-VPATH= ..
+.PATH: ${.CURDIR}/../../share/xml/glossary
-MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+MAINTAINER= doc@FreeBSD.org
-DOC_PREFIX?= ${.CURDIR}/../../../..
+DOC?= book
-.include "../Makefile"
+FORMATS?= html
+
+HAS_INDEX= true
+USE_PS2PDF= yes
+
+INSTALL_COMPRESSED?= gz
+INSTALL_ONLY_COMPRESSED?=
+
+# SRCS lists the individual XML files that make up the document. Changes
+# to any of these files will force a rebuild
+#
+
+# XML content
+SRCS+= x11/chapter.xml
+
+# Entities
+SRCS+= chapters.ent
+
+SYMLINKS= ${DESTDIR} index.html handbook.html
+
+# Turn on all the chapters.
+CHAPTERS?= ${SRCS:M*chapter.xml}
+
+XMLFLAGS+= ${CHAPTERS:S/\/chapter.xml//:S/^/-i chap./}
+XMLFLAGS+= -i chap.freebsd-glossary
+
+pgpkeyring: pgpkeys/chapter.xml
+ ${JADE} -V nochunks ${OTHERFLAGS} ${JADEOPTS} -d ${DSLPGP} -t sgml ${XMLDECL} ${MASTERDOC}
+
+#
+# Handbook-specific variables
+#
+.if defined(WITH_PGPKEYS)
+JADEFLAGS+= -V withpgpkeys
+.endif
+
+URL_RELPREFIX?= ../../../..
+DOC_PREFIX?= ${.CURDIR}/../../..
+
+#
+# rules generating lists of mirror site from XML database.
+#
+XMLDOCS= mirrors-ftp:::mirrors.xml.ftp.inc \
+ mirrors-cvsup:::mirrors.xml.cvsup.inc \
+ eresources:::eresources.xml.www.inc
+DEPENDSET.DEFAULT= transtable mirror
+XSLT.DEFAULT= ${XSL_MIRRORS}
+XML.DEFAULT= ${XML_MIRRORS}
+NO_TIDY.DEFAULT= yes
+
+PARAMS.mirrors-ftp+= --param 'type' "'ftp'" \
+ --param 'proto' "'ftp'" \
+ --param 'target' "'handbook/mirrors/chapter.xml'"
+PARAMS.mirrors-cvsup+= --param 'type' "'cvsup'" \
+ --param 'proto' "'cvsup'" \
+ --param 'target' "'handbook/mirrors/chapter.xml'"
+PARAMS.eresources+= --param 'type' "'www'" \
+ --param 'proto' "'http'" \
+ --param 'target' "'handbook/eresources/chapter.xml'"
+
+SRCS+= mirrors.xml.ftp.inc \
+ mirrors.xml.cvsup.inc \
+ eresources.xml.www.inc
+
+CLEANFILES+= mirrors.xml.ftp.inc \
+ mirrors.xml.cvsup.inc \
+ eresources.xml.www.inc
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?1358784756.88482.YahooMailClassic>