From owner-svn-doc-all@freebsd.org Thu Oct 15 19:02:40 2015 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id F0800A155B2; Thu, 15 Oct 2015 19:02:40 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id BC9E232B; Thu, 15 Oct 2015 19:02:40 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id t9FJ2dvo001913; Thu, 15 Oct 2015 19:02:39 GMT (envelope-from wblock@FreeBSD.org) Received: (from wblock@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id t9FJ2dEt001912; Thu, 15 Oct 2015 19:02:39 GMT (envelope-from wblock@FreeBSD.org) Message-Id: <201510151902.t9FJ2dEt001912@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: wblock set sender to wblock@FreeBSD.org using -f From: Warren Block Date: Thu, 15 Oct 2015 19:02:39 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 15 Oct 2015 19:02:41 -0000 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 @@ 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: + useful. @@ -237,161 +237,540 @@ Installing <application>&xorg;</application> - &xorg; 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 - x11/xorg. A minimal distribution is located - in x11/xorg-minimal, with separate ports - available for docs, libraries, and apps. The examples in this - section install the complete &xorg; - distribution. + On &os;, &xorg; can be installed + as a package or port. - To build and install &xorg; from - the Ports Collection: + To build and install from the Ports Collection: &prompt.root; cd /usr/ports/x11/xorg &prompt.root; make install clean - - To build &xorg; in its - entirety, be sure to have at least 4 GB of free disk - space available. - - - Alternatively, &xorg; can be - installed directly from packages with this command: + The binary package can be installed more quickly but with + fewer options for customization: &prompt.root; pkg install xorg + + Either of these installations results in the complete + &xorg; system being installed. This + is the best option for most users. + + A smaller version of the X system suitable for experienced + users is available in x11/xorg-minimal. Most + of the documents, libraries, and applications will not be + installed. Some applications require these additional + components to function. - <application>&xorg;</application> Configuration + + + + Warren + Block + + Originally contributed by + + + &xorg; &xorg; - In most cases, &xorg; 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: + + Quick Start + + &xorg; supports most common + video cards, keyboards, and pointing devices. These devices + are automatically detected and do not require any manual + configuration. + + + + If &xorg; has been used on + this computer before, move or remove any existing + configuration files: - &prompt.root; mv /etc/X11/xorg.conf ~/xorg.conf.etc + &prompt.root; mv /etc/X11/xorg.conf ~/xorg.conf.etc &prompt.root; mv /usr/local/etc/X11/xorg.conf ~/xorg.conf.localetc + - To generate the configuration file and start the X system, - issue this command: + + Add the user who will run + &xorg; to the + video or + wheel group to enable 3D acceleration + when available. To add user + jru to whichever group is + available: + + &prompt.root; pw groupmod video -m jru || pw groupmod wheel -m jru + + + + The TWM window manager is included + by default. It is started when + &xorg; starts: + + &prompt.user; startx + + + + 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 + . + + + - &prompt.user; startx + + User Group for Accelerated Video - 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 - Ctrl - Alt - Fn - (F1 for the first virtual console) and press - Ctrl - C . - - If the mouse or keyboard do not work, continue with . - - Desktop environments like GNOME, - KDE or - Xfce provide graphical tools to set - parameters such as video resolution. If the default - configuration works, skip to for - examples on how to install a desktop environment. - - - The - Ctrl - Alt - Backspace - key combination may also be used to break out of - &xorg;. To enable it, you can - either type the following command from any X terminal - emulator: - - &prompt.user; setxkbmap -option terminate:ctrl_alt_bksp - - or create a keyboard configuration file for - hald called - x11-input.fdi and saved in the - /usr/local/etc/hal/fdi/policy directory. - This file should contain the following lines: + Access to /dev/dri 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 + video or wheel group. + Here, &man.pw.8; is used to add user + slurms to the + video group, or to the + wheel group if there is no + video group: - <?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> + &prompt.root; pw groupmod video -m slurms || pw groupmod wheel -m slurms + - The following line will also have to be added to - xorg.conf.new, in the - ServerLayout or - ServerFlags section: + + Kernel Mode Setting (<acronym>KMS</acronym>) - Option "DontZap" "off" - + When the computer switches from displaying the console to + a higher screen resolution for X, it must set the video + output mode. Recent versions of + &xorg; 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 + KMS 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. - - Caveats + Add this line to /boot/loader.conf + to enable &man.vt.4;: + + kern.vty=vt + - 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: + + Configuration Files - - - 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;. - + + Directory - - ATI/Radeon: 2D and 3D acceleration is supported on - most Radeon cards up to the HD6000 series. - + &xorg; looks in several + directories for configuration files. + /usr/local/etc/X11/ is the recommended + directory for these files on &os;. Using this directory + helps keep application files separate from operating system + files. + + Storing configuration files in the legacy + /etc/X11/ still works. However, this + mixes application files with the base &os; files and is not + recommended. + + + + Single or Multiple Files + + It is easier to use multiple files that each configure a + specific setting than the traditional single + xorg.conf. These files are stored in + the xorg.conf.d/ subdirectory of the + main configuration file directory. The full path is + typically + /usr/local/etc/X11/xorg.conf.d/. + + Examples of these files are shown later in this + section. + + The traditional single xorg.conf + still works, but is neither as clear nor as flexible as + multiple files in the xorg.conf.d/ + subdirectory. + + - - NVIDIA: several NVIDIA drivers are available in the - x11 category of the Ports Collection. - Install the driver that matches the video card. - + + Video Cards - - 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 BIOS option to disable one of - the graphics adapters or select a - discrete mode. - - + + + &intel; + + + 3D acceleration is supported on most &intel; + graphics, including IronLake, SandyBridge, and + IvyBridge. + + + + + &amd; Radeon + + + 2D and 3D acceleration is supported on Radeon + cards up to and including the HD6000 series. + + + + + NVIDIA + + + Several NVIDIA drivers are available in the + x11 category of the Ports + Collection. Install the driver that matches the video + card. + + + + + Hybrid Combination Graphics + + + Some notebook computers add additional graphics + processing units to those built into the chipset or + processor. Optimus combines + &intel; and NVIDIA hardware. + Switchable Graphics or + Hybrid Graphics are a combination + of &intel; and an &amd; Radeon + GPU. + + Implementations of these hybrid graphics systems + vary, and &xorg; on &os; is + not able to drive all versions of them. + + Some computers provide a BIOS + option to disable one of the graphics adapters or select + a discrete mode which can be used + with one of the standard video card drivers. For + example, it is sometimes possible to disable the NVIDIA + GPU in an Optimus system. The + &intel; video can then be used with an &intel; + driver. + + BIOS settings depend on the model + of computer. + + + + + Other Video Cards + + + Drivers for some less-common video cards can be + found in the x11-drivers directory + of the Ports Collection. + + Cards that are not supported by a specific driver + might still be usable with the + x11-drivers/xf86-video-vesa driver. + This driver is installed by x11/xorg. + It can also be installed manually as + x11-drivers/xf86-video-vesa. + &xorg; attempts to use this + driver when a specific driver is not found for the video + card. + + x11-drivers/xf86-video-scfb is a + similar nonspecialized video driver that works on many + UEFI and &arm; computers. + + + + + + + Monitors + + Almost all monitors support the Extended Display + Identification Data standard (EDID). + &xorg; uses EDID + 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. + + 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;. + + + + Using &man.xrandr.1; + + + Run &man.xrandr.1; without any parameters to see a + list of video outputs and detected monitor modes: + + &prompt.user; xrandr +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) + + This shows that the DVI-0 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 + DisplayPort-0 and + HDMI-0 connectors. + + Any of the other display modes can be selected with + &man.xrandr.1;. For example, to switch to 1280x1024 at + 60 Hz: + + &prompt.user; xrandr --mode 1280x1024 --rate 60 + + A common task is using the external video output on + a notebook computer for a video projector. + + Names and types of video connectors vary, so + &man.xrandr.1; is run without options to list the + outputs: + + &prompt.user; xrandr +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) + + Four outputs were found: the built-in panel + LVDS1, and external + VGA1, HDMI1, and + DP1 connectors. + + The projector has been connected to the + VGA1 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: + + &prompt.user; xrandr --output VGA1 --auto --right-of LVDS1 + + --auto chooses the resolution and + refresh rate detected by EDID. If + the resolution is not correctly detected, a fixed value + can be given with --mode instead of + the --auto statement. For example, + most projectors can be used with a 1024x768 resolution, + which is set with + --mode 1024x768. + + &man.xrandr.1; is often run from + .xinitrc to set the appropriate + mode when X starts. + + + + + Setting Monitor Resolution In a File + + + To set a screen resolution of 1024x768 in a + configuration file: + + Section "Screen" + Identifier "Screen0" + Device "Card0" + SubSection "Display" + Modes "1024x768" + EndSubSection +EndSection + + The few monitors that do not have + EDID can be configured by setting + HorizSync and + VertRefresh to the range of + frequencies supported by the monitor. + + + Manually Setting Monitor Frequencies + + /usr/local/etc/X11/xorg.conf.d/monitor0-freq.conf + + Section "Monitor" + Identifier "Monitor0" + HorizSync 30-83 # kHz + VertRefresh 50-76 # Hz +EndSection + + + + + + + + Input Devices + + + Keyboards + + + + Keyboard Layout + + + The standardized location of keys on a keyboard + is called a layout. Layouts and + other adjustable parameters are listed in + &man.xkeyboard-config.7;. + + A United States layout is the default. To select + an alternate layout, set the + XkbLayout and + XkbVariant options in an + InputClass. This will be applied + to all input devices that match the class. + + This example selects a French keyboard layout with + the oss variant. + + + Setting Keyboard Layout + + /usr/local/etc/X11/xorg.conf.d/keyboard-fr-oss.conf + + Section "InputClass" + Identifier "KeyboardDefaults" + Driver "keyboard" + MatchIsKeyboard "on" + Option "XkbLayout" "fr" + Option "XkbVariant" "oss" +EndSection + + + + + + Closing &xorg; From the + Keyboard + + + 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 ServerLayout and keyboard + InputDevice sections: + + + Enabling Keyboard Exit from X + + /usr/local/etc/X11/xorg.conf.d/serverlayout-enablezap.conf + + Section "ServerLayout" + Identifier "EnableZap" + Option "DontZap" "Off" +EndSection + + /usr/local/etc/X11/xorg.conf.d/keyboard-zap.conf + + Section "InputClass" + Identifier "KeyboardDefaults" + Driver "keyboard" + MatchIsKeyboard "on" + Option "XkbOptions" "terminate:ctrl_alt_bksp" +EndSection + + + + + + + + Mice and Pointing Devices + + Many mouse parameters can be adjusted with configuration + options. See &man.mousedrv.4x; for a full list. + + + + Mouse Buttons + + + The number of buttons on a mouse can be set in the + mouse InputDevice section of + xorg.conf. To set the number of + buttons to 7: + + + Setting the Number of Mouse Buttons + + /usr/local/etc/X11/xorg.conf.d/mouse0-buttons.conf + + Section "InputDevice" + Identifier "Mouse0" + Option "Buttons" "7" +EndSection + + + + + + + + + Manual Configuration + + In some cases, &xorg; + autoconfiguration does not work with particular hardware, or a + different configuration is desired. For these cases, a custom + configuration file can be created. + + A configuration file can be generated by + &xorg; based on the detected + hardware. This file is often a useful starting point for + custom configurations. + + Generating an xorg.conf: + + &prompt.root; Xorg -configure + + The configuration file is saved to + /root/xorg.conf.new. Make any changes + desired, then test that file with: + + &prompt.root; Xorg -config /root/xorg.conf.new + + After the new configuration has been adjusted and tested, + it can be split into smaller files in the normal location, + /usr/local/etc/X11/xorg.conf.d/. @@ -924,7 +1303,7 @@ DisplayManager.requestPort: 0This desktop environment can be installed from a package: - &prompt.root; pkg install gnome3 + &prompt.root; pkg install gnome2 To instead build GNOME from ports, use the following command. @@ -932,7 +1311,7 @@ DisplayManager.requestPort: 0 - &prompt.root; cd /usr/ports/x11/gnome3 + &prompt.root; cd /usr/ports/x11/gnome2 &prompt.root; make install clean For proper operation, GNOME