Date: Thu, 15 Oct 2015 19:02:39 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r47566 - head/en_US.ISO8859-1/books/handbook/x11 Message-ID: <201510151902.t9FJ2dEt001912@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Thu Oct 15 19:02:39 2015 New Revision: 47566 URL: https://svnweb.freebsd.org/changeset/doc/47566 Log: Rewrite the X configuration section to better suit current conditions. Reviewed by: #freebsd-xorg on IRC (some slightly earlier versions) Modified: head/en_US.ISO8859-1/books/handbook/x11/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/x11/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/x11/chapter.xml Thu Oct 15 17:45:34 2015 (r47565) +++ head/en_US.ISO8859-1/books/handbook/x11/chapter.xml Thu Oct 15 19:02:39 2015 (r47566) @@ -93,7 +93,7 @@ <para>While it is not necessary to understand all of the details of the various components in the X Window System and how they interact, some basic knowledge of these components can be - useful:</para> + useful.</para> <variablelist> <varlistentry> @@ -237,161 +237,540 @@ <sect1 xml:id="x-install"> <title>Installing <application>&xorg;</application></title> - <para><application>&xorg;</application> is the implementation of - the open source X Window System released by the X.Org - Foundation. In &os;, it can be installed as a package or port. - The meta-port for the complete distribution which includes X - servers, clients, libraries, and fonts is located in - <package>x11/xorg</package>. A minimal distribution is located - in <package>x11/xorg-minimal</package>, with separate ports - available for docs, libraries, and apps. The examples in this - section install the complete <application>&xorg;</application> - distribution.</para> + <para>On &os;, <application>&xorg;</application> can be installed + as a package or port.</para> - <para>To build and install <application>&xorg;</application> from - the Ports Collection:</para> + <para>To build and install from the Ports Collection:</para> <screen>&prompt.root; <userinput>cd /usr/ports/x11/xorg</userinput> &prompt.root; <userinput>make install clean</userinput></screen> - <note> - <para>To build <application>&xorg;</application> in its - entirety, be sure to have at least 4 GB of free disk - space available.</para> - </note> - - <para>Alternatively, <application>&xorg;</application> can be - installed directly from packages with this command:</para> + <para>The binary package can be installed more quickly but with + fewer options for customization:</para> <screen>&prompt.root; <userinput>pkg install xorg</userinput></screen> + + <para>Either of these installations results in the complete + <application>&xorg;</application> system being installed. This + is the best option for most users.</para> + + <para>A smaller version of the X system suitable for experienced + users is available in <package>x11/xorg-minimal</package>. Most + of the documents, libraries, and applications will not be + installed. Some applications require these additional + components to function.</para> </sect1> <sect1 xml:id="x-config"> - <!-- - <sect1info> - <authorgroup> - <author> - <firstname>Christopher</firstname> - <surname>Shumway</surname> - <contrib>Contributed in July 2001 by</contrib> - </author> - </authorgroup> - </sect1info> - --> <title><application>&xorg;</application> Configuration</title> + <info> + <author> + <personname> + <firstname>Warren</firstname> + <surname>Block</surname> + </personname> + <contrib>Originally contributed by</contrib> + </author> + </info> + <indexterm><primary>&xorg;</primary></indexterm> <indexterm><primary><application>&xorg;</application></primary></indexterm> - <para>In most cases, <application>&xorg;</application> is - self-configuring. Autoconfiguration is the preferred method, - and should be tried first. When X is started without a - configuration file, the video card and input devices are - automatically detected and used. If the system already has a - configuration file and you wish to create a new configuration, - save a copy of the old one first:</para> + <sect2 xml:id="x-config-quick-start"> + <title>Quick Start</title> + + <para><application>&xorg;</application> supports most common + video cards, keyboards, and pointing devices. These devices + are automatically detected and do not require any manual + configuration.</para> + + <procedure> + <step> + <para>If <application>&xorg;</application> has been used on + this computer before, move or remove any existing + configuration files:</para> - <screen>&prompt.root; <userinput>mv /etc/X11/xorg.conf ~/xorg.conf.etc</userinput> + <screen>&prompt.root; <userinput>mv /etc/X11/xorg.conf ~/xorg.conf.etc</userinput> &prompt.root; <userinput>mv /usr/local/etc/X11/xorg.conf ~/xorg.conf.localetc</userinput></screen> + </step> - <para>To generate the configuration file and start the X system, - issue this command:</para> + <step> + <para>Add the user who will run + <application>&xorg;</application> to the + <literal>video</literal> or + <literal>wheel</literal> group to enable 3D acceleration + when available. To add user + <replaceable>jru</replaceable> to whichever group is + available:</para> + + <screen>&prompt.root; <userinput>pw groupmod video -m <replaceable>jru</replaceable> || pw groupmod wheel -m <replaceable>jru</replaceable></userinput></screen> + </step> + + <step> + <para>The <acronym>TWM</acronym> window manager is included + by default. It is started when + <application>&xorg;</application> starts:</para> + + <screen>&prompt.user; <userinput>startx</userinput></screen> + </step> + + <step> + <para>On some older versions of &os;, the system console + must be set to &man.vt.4; before switching back to the + text console will work properly. See + <xref linkend="x-config-kms"/>.</para> + </step> + </procedure> + </sect2> - <screen>&prompt.user; <userinput>startx</userinput></screen> + <sect2 xml:id="x-config-user-group"> + <title>User Group for Accelerated Video</title> - <para>If a black and grey grid and an X mouse cursor appear, the - configuration was successful. Test the system by moving the - mouse and typing text into the windows. To exit the test, - switch to the virtual console used to start it by pressing - <keycombo action="simul"> <keycap>Ctrl</keycap> - <keycap>Alt</keycap> - <keycap>F<replaceable>n</replaceable></keycap> </keycombo> - (<keycap>F1</keycap> for the first virtual console) and press - <keycombo action="simul"> <keycap>Ctrl</keycap> - <keycap>C</keycap> </keycombo>.</para> - - <para>If the mouse or keyboard do not work, continue with <xref - linkend="x11-understanding"/>.</para> - - <para>Desktop environments like <application>GNOME</application>, - <application>KDE</application> or - <application>Xfce</application> provide graphical tools to set - parameters such as video resolution. If the default - configuration works, skip to <xref linkend="x11-wm"/> for - examples on how to install a desktop environment.</para> - - <note> - <para>The <keycombo action="simul"> - <keycap>Ctrl</keycap> - <keycap>Alt</keycap> - <keycap>Backspace</keycap> - </keycombo> key combination may also be used to break out of - <application>&xorg;</application>. To enable it, you can - either type the following command from any X terminal - emulator:</para> - - <screen>&prompt.user; <userinput>setxkbmap -option terminate:ctrl_alt_bksp</userinput></screen> - - <para>or create a keyboard configuration file for - <application>hald</application> called - <filename>x11-input.fdi</filename> and saved in the - <filename>/usr/local/etc/hal/fdi/policy</filename> directory. - This file should contain the following lines:</para> + <para>Access to <filename>/dev/dri</filename> is needed to allow + 3D acceleration on video cards. It is usually simplest to add + the user who will be running X to either the + <literal>video</literal> or <literal>wheel</literal> group. + Here, &man.pw.8; is used to add user + <replaceable>slurms</replaceable> to the + <literal>video</literal> group, or to the + <literal>wheel</literal> group if there is no + <literal>video</literal> group:</para> - <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.XkbOptions" type="string">terminate:ctrl_alt_bksp</merge> - </match> - </device> -</deviceinfo></programlisting> + <screen>&prompt.root; <userinput>pw groupmod video -m <replaceable>slurms</replaceable> || pw groupmod wheel -m <replaceable>slurms</replaceable></userinput></screen> + </sect2> - <para>The following line will also have to be added to - <filename>xorg.conf.new</filename>, in the - <literal>ServerLayout</literal> or - <literal>ServerFlags</literal> section:</para> + <sect2 xml:id="x-config-kms"> + <title>Kernel Mode Setting (<acronym>KMS</acronym>)</title> - <programlisting>Option "DontZap" "off"</programlisting> - </note> + <para>When the computer switches from displaying the console to + a higher screen resolution for X, it must set the video + output <emphasis>mode</emphasis>. Recent versions of + <acronym>&xorg;</acronym> use a system inside the kernel to do + these mode changes more efficiently. Older versions of &os; + use &man.sc.4;, which is not aware of the + <acronym>KMS</acronym> system. The end result is that after + closing X, the system console is blank, even though it is + still working. The newer &man.vt.4; console avoids this + problem.</para> - <sect2> - <title>Caveats</title> + <para>Add this line to <filename>/boot/loader.conf</filename> + to enable &man.vt.4;:</para> + + <programlisting>kern.vty=vt</programlisting> + </sect2> - <para>The ability to configure optimal resolution is dependent - upon the video hardware and the support provided by its - driver. At this time, driver support includes:</para> + <sect2 xml:id="x-config-files"> + <title>Configuration Files</title> - <itemizedlist> - <listitem> - <para>Intel: as of &os; 9.3 and &os; 10.1, 3D - acceleration on most Intel graphics, including IronLake, - SandyBridge, and IvyBridge, is supported. Support for - switching between X and virtual consoles is provided by - &man.vt.4;.</para> - </listitem> + <sect3 xml:id="x-config-files-directory"> + <title>Directory</title> - <listitem> - <para>ATI/Radeon: 2D and 3D acceleration is supported on - most Radeon cards up to the HD6000 series.</para> - </listitem> + <para><application>&xorg;</application> looks in several + directories for configuration files. + <filename>/usr/local/etc/X11/</filename> is the recommended + directory for these files on &os;. Using this directory + helps keep application files separate from operating system + files.</para> + + <para>Storing configuration files in the legacy + <filename>/etc/X11/</filename> still works. However, this + mixes application files with the base &os; files and is not + recommended.</para> + </sect3> + + <sect3 xml:id="x-config-files-single-or-multi"> + <title>Single or Multiple Files</title> + + <para>It is easier to use multiple files that each configure a + specific setting than the traditional single + <filename>xorg.conf</filename>. These files are stored in + the <filename>xorg.conf.d/</filename> subdirectory of the + main configuration file directory. The full path is + typically + <filename>/usr/local/etc/X11/xorg.conf.d/</filename>.</para> + + <para>Examples of these files are shown later in this + section.</para> + + <para>The traditional single <filename>xorg.conf</filename> + still works, but is neither as clear nor as flexible as + multiple files in the <filename>xorg.conf.d/</filename> + subdirectory.</para> + </sect3> + </sect2> - <listitem> - <para>NVIDIA: several NVIDIA drivers are available in the - <filename>x11</filename> category of the Ports Collection. - Install the driver that matches the video card.</para> - </listitem> + <sect2 xml:id="x-config-video-cards"> + <title>Video Cards</title> - <listitem> - <para>Optimus: currently there is no switching support - between the two graphics adapters provided by Optimus. - Optimus implementations vary, and &os; will not be able to - drive all versions of the hardware. Some computers - provide a <acronym>BIOS</acronym> option to disable one of - the graphics adapters or select a - <emphasis>discrete</emphasis> mode.</para> - </listitem> - </itemizedlist> + <variablelist> + <varlistentry xml:id="x-config-video-cards-intel"> + <term>&intel;</term> + + <listitem> + <para>3D acceleration is supported on most &intel; + graphics, including IronLake, SandyBridge, and + IvyBridge.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="x-config-video-cards-radeon"> + <term>&amd; Radeon</term> + + <listitem> + <para>2D and 3D acceleration is supported on Radeon + cards up to and including the HD6000 series.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="x-config-video-cards-nvidia"> + <term>NVIDIA</term> + + <listitem> + <para>Several NVIDIA drivers are available in the + <filename>x11</filename> category of the Ports + Collection. Install the driver that matches the video + card.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="x-config-video-cards-hybrid"> + <term>Hybrid Combination Graphics</term> + + <listitem> + <para>Some notebook computers add additional graphics + processing units to those built into the chipset or + processor. <emphasis>Optimus</emphasis> combines + &intel; and NVIDIA hardware. + <emphasis>Switchable Graphics</emphasis> or + <emphasis>Hybrid Graphics</emphasis> are a combination + of &intel; and an &amd; Radeon + <acronym>GPU</acronym>.</para> + + <para>Implementations of these hybrid graphics systems + vary, and <application>&xorg;</application> on &os; is + not able to drive all versions of them.</para> + + <para>Some computers provide a <acronym>BIOS</acronym> + option to disable one of the graphics adapters or select + a <emphasis>discrete</emphasis> mode which can be used + with one of the standard video card drivers. For + example, it is sometimes possible to disable the NVIDIA + <acronym>GPU</acronym> in an Optimus system. The + &intel; video can then be used with an &intel; + driver.</para> + + <para><acronym>BIOS</acronym> settings depend on the model + of computer.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="x-config-video-cards-other"> + <term>Other Video Cards</term> + + <listitem> + <para>Drivers for some less-common video cards can be + found in the <filename>x11-drivers</filename> directory + of the Ports Collection.</para> + + <para>Cards that are not supported by a specific driver + might still be usable with the + <package>x11-drivers/xf86-video-vesa</package> driver. + This driver is installed by <package>x11/xorg</package>. + It can also be installed manually as + <package>x11-drivers/xf86-video-vesa</package>. + <application>&xorg;</application> attempts to use this + driver when a specific driver is not found for the video + card.</para> + + <para><package>x11-drivers/xf86-video-scfb</package> is a + similar nonspecialized video driver that works on many + <acronym>UEFI</acronym> and &arm; computers.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 xml:id="x-config-monitors"> + <title>Monitors</title> + + <para>Almost all monitors support the Extended Display + Identification Data standard (<acronym>EDID</acronym>). + <application>&xorg;</application> uses <acronym>EDID</acronym> + to communicate with the monitor and detect the supported + resolutions and refresh rates. Then it selects the most + appropriate combination of settings to use with that + monitor.</para> + + <para>Other resolutions supported by the monitor can be + chosen by setting the desired resolution in configuration + files, or after the X server has been started with + &man.xrandr.1;.</para> + + <variablelist> + <varlistentry xml:id="x-config-monitors-xrandr"> + <term>Using &man.xrandr.1;</term> + + <listitem> + <para>Run &man.xrandr.1; without any parameters to see a + list of video outputs and detected monitor modes:</para> + + <screen>&prompt.user; <userinput>xrandr</userinput> +Screen 0: minimum 320 x 200, current 3000 x 1920, maximum 8192 x 8192 +DVI-0 connected primary 1920x1200+1080+0 (normal left inverted right x axis y axis) 495mm x 310mm + 1920x1200 59.95*+ + 1600x1200 60.00 + 1280x1024 85.02 75.02 60.02 + 1280x960 60.00 + 1152x864 75.00 + 1024x768 85.00 75.08 70.07 60.00 + 832x624 74.55 + 800x600 75.00 60.32 + 640x480 75.00 60.00 + 720x400 70.08 +DisplayPort-0 disconnected (normal left inverted right x axis y axis) +HDMI-0 disconnected (normal left inverted right x axis y axis)</screen> + + <para>This shows that the <literal>DVI-0</literal> output + is being used to display a screen resolution of + 1920x1200 pixels at a refresh rate of about 60 Hz. + Monitors are not attached to the + <literal>DisplayPort-0</literal> and + <literal>HDMI-0</literal> connectors.</para> + + <para>Any of the other display modes can be selected with + &man.xrandr.1;. For example, to switch to 1280x1024 at + 60 Hz:</para> + + <screen>&prompt.user; <userinput>xrandr --mode 1280x1024 --rate 60</userinput></screen> + + <para>A common task is using the external video output on + a notebook computer for a video projector.</para> + + <para>Names and types of video connectors vary, so + &man.xrandr.1; is run without options to list the + outputs:</para> + + <screen>&prompt.user; <userinput>xrandr</userinput> +Screen 0: minimum 320 x 200, current 1366 x 768, maximum 8192 x 8192 +LVDS1 connected 1366x768+0+0 (normal left inverted right x axis y axis) 344mm x 193mm + 1366x768 60.04*+ + 1024x768 60.00 + 800x600 60.32 56.25 + 640x480 59.94 +VGA1 connected (normal left inverted right x axis y axis) + 1280x1024 60.02 + 75.02 + 1280x960 60.00 + 1152x864 75.00 + 1024x768 75.08 70.07 60.00 + 832x624 74.55 + 800x600 72.19 75.00 60.32 56.25 + 640x480 75.00 72.81 66.67 60.00 + 720x400 70.08 +HDMI1 disconnected (normal left inverted right x axis y axis) +DP1 disconnected (normal left inverted right x axis y axis)</screen> + + <para>Four outputs were found: the built-in panel + <literal>LVDS1</literal>, and external + <literal>VGA1</literal>, <literal>HDMI1</literal>, and + <literal>DP1</literal> connectors.</para> + + <para>The projector has been connected to the + <literal>VGA1</literal> output. &man.xrandr.1; is now + used to set that output to the native resolution of the + projector and add the additional space to the right side + of the desktop:</para> + + <screen>&prompt.user; <userinput>xrandr --output VGA1 --auto --right-of LVDS1</userinput></screen> + + <para><literal>--auto</literal> chooses the resolution and + refresh rate detected by <acronym>EDID</acronym>. If + the resolution is not correctly detected, a fixed value + can be given with <literal>--mode</literal> instead of + the <literal>--auto</literal> statement. For example, + most projectors can be used with a 1024x768 resolution, + which is set with + <literal>--mode 1024x768</literal>.</para> + + <para>&man.xrandr.1; is often run from + <filename>.xinitrc</filename> to set the appropriate + mode when X starts.</para> + </listitem> + </varlistentry> + + <varlistentry xml:id="x-config-monitors-files"> + <term>Setting Monitor Resolution In a File</term> + + <listitem> + <para>To set a screen resolution of 1024x768 in a + configuration file:</para> + + <programlisting>Section "Screen" + Identifier "Screen0" + Device "Card0" + SubSection "Display" + Modes "1024x768" + EndSubSection +EndSection</programlisting> + + <para>The few monitors that do not have + <acronym>EDID</acronym> can be configured by setting + <literal>HorizSync</literal> and + <literal>VertRefresh</literal> to the range of + frequencies supported by the monitor.</para> + + <example> + <title>Manually Setting Monitor Frequencies</title> + + <para><filename>/usr/local/etc/X11/xorg.conf.d/monitor0-freq.conf</filename></para> + + <programlisting>Section "Monitor" + Identifier "Monitor0" + HorizSync 30-83 # kHz + VertRefresh 50-76 # Hz +EndSection</programlisting> + </example> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 xml:id="x-config-input"> + <title>Input Devices</title> + + <sect3 xml:id="x-config-input-keyboard"> + <title>Keyboards</title> + + <variablelist> + <varlistentry xml:id="x-config-input-keyboard-layout"> + <term>Keyboard Layout</term> + + <listitem> + <para>The standardized location of keys on a keyboard + is called a <emphasis>layout</emphasis>. Layouts and + other adjustable parameters are listed in + &man.xkeyboard-config.7;.</para> + + <para>A United States layout is the default. To select + an alternate layout, set the + <literal>XkbLayout</literal> and + <literal>XkbVariant</literal> options in an + <literal>InputClass</literal>. This will be applied + to all input devices that match the class.</para> + + <para>This example selects a French keyboard layout with + the <literal>oss</literal> variant.</para> + + <example> + <title>Setting Keyboard Layout</title> + + <para><filename>/usr/local/etc/X11/xorg.conf.d/keyboard-fr-oss.conf</filename></para> + + <programlisting>Section "InputClass" + Identifier "KeyboardDefaults" + Driver "keyboard" + MatchIsKeyboard "on" + Option "XkbLayout" "fr" + Option "XkbVariant" "oss" +EndSection</programlisting> + </example> + </listitem> + </varlistentry> + + <varlistentry xml:id="x-config-input-keyboard-zap"> + <term>Closing <application>&xorg;</application> From the + Keyboard</term> + + <listitem> + <para>A combination of keys is available to close the X + system. This option is disabled by default because it + conflicts with keyboard commands for some + applications. Enabling this option requires changes + to both <literal>ServerLayout</literal> and keyboard + <literal>InputDevice</literal> sections:</para> + + <example> + <title>Enabling Keyboard Exit from X</title> + + <para><filename>/usr/local/etc/X11/xorg.conf.d/serverlayout-enablezap.conf</filename></para> + + <programlisting>Section "ServerLayout" + Identifier "EnableZap" + Option "DontZap" "Off" +EndSection</programlisting> + + <para><filename>/usr/local/etc/X11/xorg.conf.d/keyboard-zap.conf</filename></para> + + <programlisting>Section "InputClass" + Identifier "KeyboardDefaults" + Driver "keyboard" + MatchIsKeyboard "on" + Option "XkbOptions" "terminate:ctrl_alt_bksp" +EndSection</programlisting> + </example> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 xml:id="x11-input-mice"> + <title>Mice and Pointing Devices</title> + + <para>Many mouse parameters can be adjusted with configuration + options. See &man.mousedrv.4x; for a full list.</para> + + <variablelist> + <varlistentry xml:id="x11-input-mice-buttons"> + <term>Mouse Buttons</term> + + <listitem> + <para>The number of buttons on a mouse can be set in the + mouse <literal>InputDevice</literal> section of + <filename>xorg.conf</filename>. To set the number of + buttons to 7:</para> + + <example> + <title>Setting the Number of Mouse Buttons</title> + + <para><filename>/usr/local/etc/X11/xorg.conf.d/mouse0-buttons.conf</filename></para> + + <programlisting>Section "InputDevice" + Identifier "Mouse0" + Option "Buttons" "7" +EndSection</programlisting> + </example> + </listitem> + </varlistentry> + </variablelist> + </sect3> + </sect2> + + <sect2 xml:id="x-config-manual-configuration"> + <title>Manual Configuration</title> + + <para>In some cases, <application>&xorg;</application> + autoconfiguration does not work with particular hardware, or a + different configuration is desired. For these cases, a custom + configuration file can be created.</para> + + <para>A configuration file can be generated by + <application>&xorg;</application> based on the detected + hardware. This file is often a useful starting point for + custom configurations.</para> + + <para>Generating an <filename>xorg.conf</filename>:</para> + + <screen>&prompt.root; <userinput>Xorg -configure</userinput></screen> + + <para>The configuration file is saved to + <filename>/root/xorg.conf.new</filename>. Make any changes + desired, then test that file with:</para> + + <screen>&prompt.root; <userinput>Xorg -config /root/xorg.conf.new</userinput></screen> + + <para>After the new configuration has been adjusted and tested, + it can be split into smaller files in the normal location, + <filename>/usr/local/etc/X11/xorg.conf.d/</filename>.</para> </sect2> </sect1> @@ -924,7 +1303,7 @@ DisplayManager.requestPort: 0</scree <para>This desktop environment can be installed from a package:</para> - <screen>&prompt.root; <userinput>pkg install gnome3</userinput></screen> + <screen>&prompt.root; <userinput>pkg install gnome2</userinput></screen> <para>To instead build <application>GNOME</application> from ports, use the following command. @@ -932,7 +1311,7 @@ DisplayManager.requestPort: 0</scree will take some time to compile, even on a fast computer.</para> - <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome3</userinput> + <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput> &prompt.root; <userinput>make install clean</userinput></screen> <para>For proper operation, <application>GNOME</application>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201510151902.t9FJ2dEt001912>