Added 3.8.2
[ikiwiki.git] / docs / newhandbook / X / index.mdwn
index 50d8bd2..edc6b36 100644 (file)
@@ -3,19 +3,16 @@
 
 [[!toc  levels=3]]
 
-
 ## Synopsis 
 
-
 This chapter will cover the installation and some configuration of the usual way of giving your Dragonfly BSD system an X-Windows style Graphical User Interface (GUI) and a modern Desktop Environment.  In Unix systems, the graphical drawing system is provided by the combination of an X11R6 compliant X-Windows Server, such as the X.org server, and other software such as Window Managers and Desktop Environments.  This multi-layered approach may be surprising to people coming from systems like the Mac or like Windows where these components are not so flexible, or provided by so many separately installed and configured pieces. 
 
 For more information on the video hardware support in X.org, check the [X.org](http://www.x.org/) web site. If you have problems configuring your X server, just search the web. There are lots of tutorials and guides on how to set up your X properly, if the information in this page is not enough for your situation.
 
 Before reading this chapter, you should know how to install additional third-party software. Read the  `dports` section of the documentation, for DragonFly 3.4 and later.
 
-
-
-
+You may find the FreeBSD X Configuration instructions apply exactly and unchanged in DragonFly BSD.
+They are found [[here|http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/x-config.html]]
 
 ## Understanding X 
 
@@ -38,27 +35,26 @@ Every desktop environment and window manager also has a different configuration
 
 Note that XFCE4 and Gnome and KDE do not require you to install any window manager as they include one automatically.
 
-
 ## Installing X
 
 **X.org**  is currently available in the DragonFly dports collection.
 
 To install:
 
-    pkg install xorg-7.7
+    pkg install xorg-7.7
 
 By the time you read this, it might be a newer version of xorg than 7.7, you can also try this general command:
 
-    # pkg install xorg
-
-
+    pkg install xorg
 
 ## Configuring X
 
+You may need to add the following lines to `/etc/rc.conf` for regular PCs but you might not want to set these two lines to NO instead on a Virtual Machine as they cause problems in Dragonfly BSD 3.4 through 3.6:
 
+    hald_enable ="YES"
+    dbus_enable= "YES" 
 
-          ***Contributed by Christopher Shumway. ***
-
+Also see below about enabling `moused` in rc.conf, which may be required for you to see your mouse pointer in X.
 
 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
 
@@ -66,87 +62,59 @@ As of version 7.3, Xorg can often work without any configuration file by simply
 
     % startx
 
-If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually. Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
+If this does not work, or if the default configuration is not acceptable, then X11 must be configured manually.  For example, if X11 does not detect your mouse then you will not get a mouse pointer, you will get a desktop (either a color or a dotted-pattern) but moving your mouse will not result in you seeing a mouse pointer move around.  Also, you might get a garbled display, or no display at all. If any of these happen to you, you need to do some manual configuration of X.org, which means a configuration text file.
+
+Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run:
    
 
     # Xorg -configure
 
-
 This will generate an X11 configuration skeleton file in the `/root` directory called `xorg.conf.new` (whether you [su(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=su&section=1) or do a direct login affects the inherited supervisor `$HOME` 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.
 
-
-
 The next step is to test the existing configuration to verify that  **X.org**  can work with the graphics hardware on the target system. To perform this task, type:
 
    
 
-    # Xorg -config xorg.conf.new
+    # Xorg -config xorg.conf.new -retro
 
+The -retro option is now required or you will only get a black desktop when testing. This retro mode is an empty X desktop with a dot pattern on the background and an X cursor in the center. If the mouse is working, you should be able to move it.
 
 If a black and grey grid and an X mouse cursor appear, the configuration was successful. To exit the test, just press  **Ctrl** + **Alt** + **Backspace**  simultaneously.
 
-
-
 **Note:** If the mouse does not work, you will need to first configure it before proceeding. This can usually be achieved by just using `/dev/sysmouse` as the input device in the config file and enabling `moused`:
 
        # rcenable moused
 
-
-
 Tune the `xorg.conf.new` configuration file to taste and move it to where [Xorg(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xorg&section=1) can find it. This is typically `/etc/X11/xorg.conf` or `/usr/pkg/xorg/lib/X11/xorg.conf`.
 
     
 
 The X11 configuration process is now complete. You can start  **X.org**  with [startx(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=startx&section=1). The X11 server may also be started with the use of [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1).
 
-
-
-
 ## The X Display Manager 
 
  ***Contributed by Seth Kingsley.***
 
-
-
 ### Overview 
 
-
-
  The X Display Manager ( **XDM** ) 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 "X Terminals", 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.  **XDM**  provides a graphical interface for choosing which display server to connect to, and entering authorization information such as a login and password combination.
 
-
-
  Think of  **XDM**  as providing the same functionality to the user as the [getty(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=getty&section=8) utility (see [ Section 17.3.2](term.html#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).  **XDM**  then waits for this program to exit, signaling that the user is done and should be logged out of the display. At this point,  **XDM**  can display the login and display chooser screens for the next user to login.
 
-
-
 ### Using XDM 
 
-
-
  The  **XDM**  daemon program is located in `/usr/pkg/bin/xdm`. This program can be run at any time as `root` and it will start managing the X display on the local machine. If  **XDM**  is to be run every time the machine boots up, a convenient way to do this is by adding an entry to `/etc/ttys`. For more information about the format and usage of this file, see [ Section 17.3.2.1](term.html#TERM-ETCTTYS). There is a line in the default `/etc/ttys` file for running the  **XDM**  daemon on a virtual terminal:
 
-
-
      
 
     ttyv8   "/usr/pkg/bin/xdm -nodaemon"  xterm   off secure
 
-
-
-
-
  By default this entry is disabled; in order to enable it change field 5 from `off` to `on` and restart [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8) using the directions in [ Section 17.3.2.2](term.html#TERM-HUP). The first field, the name of the terminal this program will manage, is `ttyv8`. This means that  **XDM**  will start running on the 9th virtual terminal.
 
-
-
 ### Configuring XDM 
 
-
-
  The  **XDM**  configuration directory is located in `/var/lib/xdm`. The sample configuration files are in `/usr/pkg/share/examples/xdm/`, in this directory there are several files used to change the behavior and appearance of  **XDM** . Typically these files will be found:
 
-
 [[!table  data="""
 <tablestyle="width:100%">  **File**  |  **Description**
 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
@@ -160,79 +128,42 @@ The X11 configuration process is now complete. You can start  **X.org**  with [s
 
 """]]
 
-
  Also in this directory are a few scripts and programs used to set up the desktop when  **XDM**  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 [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1).
 
-
-
  The default configuration is a simple rectangular login window with the hostname of the machine displayed at the top in a large font and "Login:" and "Password:" prompts below. This is a good starting point for changing the look and feel of  **XDM**  screens.
 
-
-
 #### Xaccess 
 
-
-
  The protocol for connecting to  **XDM**  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 `xdm-config` is changed to listen for remote connections. By default, it does not allow any clients to connect.
 
-
-
 #### Xresources 
 
-
-
  This is an application-defaults file for the display chooser and the login screens. This is where the appearance of the login program can be modified. The format is identical to the app-defaults file described in the X11 documentation.
 
-
-
 #### Xservers 
 
-
-
  This is a list of the remote displays the chooser should provide as choices.
 
-
-
 #### Xsession 
 
-
-
  This is the default session script for  **XDM**  to run after a user has logged in. Normally each user will have a customized session script in `~/.xsession` that overrides this script.
 
-
-
 #### Xsetup_* 
 
-
-
  These will be run automatically before displaying the chooser or login interfaces. There is a script for each display being used, named `Xsetup_` followed by the local display number (for instance `Xsetup_0`). Typically these scripts will run one or two programs in the background such as `xconsole`.
 
-
-
 #### xdm-config 
 
-
-
  This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
 
-
-
 #### xdm-errors 
 
-
-
  This contains the output of the X servers that  **XDM**  is trying to run. If a display that  **XDM**  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 `~/.xsession-errors` file on a per-session basis.
 
-
-
 ### Running a Network Display Server 
 
-
-
  In order for other clients to connect to the display server, edit the access control rules, and enable the connection listener. By default these are set to conservative values. To make  **XDM**  listen for connections, first comment out a line in the `xdm-config` file:
 
-
-
      
 
     ! SECURITY: do not listen for XDMCP or Chooser requests
@@ -241,95 +172,54 @@ The X11 configuration process is now complete. You can start  **X.org**  with [s
 
     DisplayManager.requestPort:     0
 
-
-
-
-
  and then restart  **XDM** . Remember that comments in app-defaults files begin with a "!" character, not the usual "#". More strict access controls may be desired. Look at the example entries in `Xaccess`, and refer to the [xdm(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=xdm&section=1) manual page for further information.
 
-
-
 ### Replacements for XDM 
 
-
-
  Several replacements for the default  **XDM**  program exist. One of them,  **kdm**  (bundled with  **KDE** ) is described later in this chapter. The  **kdm**  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.
 
-
 ----
 
-
-
 ## Desktop Environments 
 
  ***Contributed by Valentino Vaschetto. ***
 
  This section describes the different desktop environments available for X on FreeBSD. A ***desktop environment*** can mean anything ranging from a simple window manager to a complete suite of desktop applications, such as  **KDE**  or  **GNOME** .
 
-
-
 ### GNOME 
 
-
-
 #### About GNOME 
 
-
-
    **GNOME**  is a user-friendly desktop environment that enables users to easily use and configure their computers.  **GNOME**  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, and a 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  **GNOME**  provides.
 
-
-
 #### Installing GNOME 
 
-
-
    **GNOME**  can be easily installed from a package or from the pkgsrc framework:
 
-
-
   To install the  **GNOME**  package from the network, simply type:
 
     # pkg install gnome-desktop
 
-
-
-
   To build  **GNOME**  from source, if you have the pkgsrc tree on your system:      
 
     # cd /usr/pkgsrc/meta-pkgs/gnome
 
     # bmake install clean
 
-
-
   Once  **GNOME**  is installed, the X server must be told to start  **GNOME**  instead of a default window manager.
 
-
-
   The easiest way to start  **GNOME**  is with  **GDM** , the GNOME Display Manager.  **GDM** , which is installed as a part of the  **GNOME**  desktop (but is disabled by default), can be enabled by adding `gdm_enable="YES"` to `/etc/rc.conf`. Once you have rebooted,  **GNOME**  will start automatically once you log in -- no further configuration is necessary.
 
-
-
 **GNOME**  may also be started from the command-line by properly configuring a file named `.xinitrc`. If a custom `.xinitrc` is already in place, simply replace the line that starts the current window manager with one that starts  **/usr/pkg/bin/gnome-session**  instead. If nothing special has been done to the configuration file, then it is enough simply to type:
 
-
-
       
 
     % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
 
-
-
-
-
   Next, type `startx`, and the  **GNOME**  desktop environment will be started.
 
-
 **Note:** If an older display manager, like  **XDM** , is being used, this will not work. Instead, create an executable `.xsession` file with the same command in it. To do this, edit the file and replace the existing window manager command with  **/usr/pkg/bin/gnome-session** :
 
-
-
         
 
     % echo "#!/bin/sh" > ~/.xsession
@@ -338,32 +228,18 @@ The X11 configuration process is now complete. You can start  **X.org**  with [s
 
     % chmod +x ~/.xsession
 
-
-
-
-
   Yet another option is to configure the display manager to allow choosing the window manager at login time; the section on [ KDE details](x11-wm.html#X11-WM-KDE-DETAILS) explains how to do this for  **kdm** , the display manager of  **KDE** .
 
-
-
 #### Anti-aliased Fonts with GNOME 
 
-
-
   X11 supports anti-aliasing via its ***RENDER*** extension. GTK+ 2.0 and greater (the toolkit used by  **GNOME** ) can make use of this functionality. Configuring anti-aliasing is described in [ Section 5.5.3](x-fonts.html#ANTIALIAS).
   
   So, with up-to-date software, anti-aliasing is possible within the  **GNOME**  desktop. Just go to  **Applications->Desktop Preferences->Font** , and select either Best shapes, Best contrast, or Subpixel smoothing (LCDs). For a GTK+ application that is not part of the  **GNOME**  desktop, set the environment variable `GDK_USE_XFT` to `1` before launching the program.
 
-
-
 ### KDE 
 
-
-
 #### About KDE 
 
-
-
   **KDE**  is an easy to use contemporary desktop environment. Some of the things that  **KDE**  brings to the user are:
 
 * A beautiful contemporary desktop
@@ -384,74 +260,48 @@ The X11 configuration process is now complete. You can start  **X.org**  with [s
 
   **KDE**  comes with a web browser called  **Konqueror** , which represents a solid competitor to other existing web browsers on UNIX® systems. More information on  **KDE**  can be found on the [KDE website](http://www.kde.org/).
 
-
-
 #### Installing KDE 
 
-
  Just as with  **GNOME**  or any other desktop environment, the easiest way to install  **KDE**  is through the pkgsrc framework or from a package:
 
-
-
  To install the  **KDE**  4.10 package from the network, simply type:
 
    # pkg install kde-4.10
 
-
  To build  **KDE**  from source, using the pkgsrc framework:
 
     # cd /usr/pkgsrc/meta-pkgs/kde3
 
     # bmake install clean
 
-
-
-
-
  After  **KDE**  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 `.xinitrc` file:
 
-
     % echo "exec startkde" > ~/.xinitrc
 
-
  Now, whenever the X Window System is invoked with `startx`,  **KDE**  will be the desktop.
 
  If a display manager such as  **XDM**  is being used, the configuration is slightly different. Edit the `.xsession` file instead. Instructions for  **kdm**  are described later in this chapter.
 
-
-
 #### More Details on KDE 
 
-
-
  Now that  **KDE**  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.
 
  The best reference for  **KDE**  is the on-line documentation.  **KDE**  comes with its own web browser,  **Konqueror** , dozens of useful applications, and extensive documentation. The remainder of this section discusses the technical items that are difficult to learn by random exploration.
 
-
-
 #### The KDE Display Manager 
 
-
-
  An administrator of a multi-user system may wish to have a graphical login screen to welcome users. [ XDM](x-xdm.html) can be used, as described earlier. However,  **KDE**  includes an alternative,  **kdm** , 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 ( **KDE** ,  **GNOME** , or something else) to run after logging on.
 
-
-
  To enable  **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
   
 
     ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
 
-
     
 ### XFce 
 
-
-
 #### About XFce 
 
-
   **XFce**  is a desktop environment based on the GTK+ toolkit used by  **GNOME** , 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  **CDE** , found on commercial UNIX systems. Some of  **XFce** 's features are:
 
 * A simple, easy-to-handle desktop
@@ -466,19 +316,15 @@ The X11 configuration process is now complete. You can start  **X.org**  with [s
 
 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
 
-
 More information on  **XFce**  can be found on the [XFce website](http://www.xfce.org/).
 
-
-
 #### Installing XFce 
 
-
-
  A binary package for  **XFce**  exists. To install, simply type:
 
-    # pkg install xfce4
+    # pkg install xfce
 
+This should install the main xfce4 desktop package, and most of the required components.
 
  Alternatively, to build from source, use the pkgsrc framework:
 
@@ -488,19 +334,12 @@ More information on  **XFce**  can be found on the [XFce website](http://www.xfc
 
     # bmake install clean
 
-
-
-
  Now, tell the X server to launch  **XFce**  the next time X is started. Simply type this:
 
     % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
 
-
-
  The next time X is started,  **XFce**  will be the desktop. As before, if a display manager like  **XDM**  is being used, create an `.xsession`, as described in the section on [ GNOME](x11-wm.html#X11-WM-GNOME), but with the `/usr/pkg/bin/startxfce4` command; or, configure the display manager to allow choosing a desktop at login time, as explained in the section on [ kdm](x11-wm.html#X11-WM-KDE-KDM).
 
-
-
 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
 
 ----