Annotation of wikisrc/guide/x.mdwn, revision 1.1

1.1     ! jdf         1: # X
        !             2: 
        !             3: ## What is X?
        !             4: 
        !             5: NetBSD uses the X Window System (often referred as X11) to provide a graphical
        !             6: interface. In NetBSD 5.0, the amd64, i386, macppc, shark, sgimips, and sparc64
        !             7: ports use X.Org and the rest use XFree86.
        !             8: 
        !             9: Please note that the X Window System is a rather bare bones framework. It acts
        !            10: as a base for modern desktop environments like GNOME or KDE, but they are not
        !            11: part of the X Window System. NetBSD ships with the X Window System, but it does
        !            12: not include these desktop environments; they must be added via pkgsrc.
        !            13: 
        !            14: When you start using X you'll find many new terms which you may find confusing
        !            15: at first. The basic elements are:
        !            16: 
        !            17:  * *Video hardware*, i.e., your video card.
        !            18:  * An *X server* running on top of the hardware. The X server provides a
        !            19:    standard way to display graphics (including fonts for text display) and get
        !            20:    mouse/keyboard/other input. X is network-transparent, which means that you
        !            21:    can run X clients on one machine, and the X server (i.e., the display, with
        !            22:    video hardware) on another machine.
        !            23:  * *X clients*. These are the programs you directly interact with. They run on
        !            24:    top of the X server. A web browser like Firefox is an example of an X client.
        !            25:  * A *window manager* running on top of the X server. The window manager is a
        !            26:    special X client that is allowed to control the placement of windows. It can
        !            27:    also *decorate* windows with standard *widgets* (usually these provide
        !            28:    actions like window motion, resizing, iconifying, window killing, etc.).
        !            29:  * A *desktop environment* such as GNOME or KDE. These are suites of integrated
        !            30:    software designed to give you a well-defined range of software and a more or
        !            31:    less common interface to each program. These typically include a window
        !            32:    manager, file manager, web browser, email client, multimedia player, text
        !            33:    editor, address book, help browser, etc. As you may have guessed, a desktop
        !            34:    environment is not needed to use X, but many users will want to install one.
        !            35: 
        !            36: 
        !            37: ## Configuration
        !            38: 
        !            39: In some cases, you may be able to start using X without any configuration at
        !            40: all, and **startx** will work just fine. In many cases, however, some
        !            41: configuration of the X server is required. Depending on the port you use, this
        !            42: configuration file will be either `/etc/X11/xorg.conf` (for platforms using
        !            43: X.org) or `/etc/X11/XF86Config` (for those using XFree86). The structure of the
        !            44: configuration file is described formally in
        !            45: [xorg.conf(5)](http://netbsd.gw.com/cgi-bin/man-cgi?xorg.conf+5+NetBSD-5.0.1+i386)
        !            46: or
        !            47: [XF86Config(5)](http://netbsd.gw.com/cgi-bin/man-cgi?XF86Config+5+NetBSD-5.0.1+i386).
        !            48: 
        !            49: To generate an initial configuration file for your X server, run the command
        !            50: 
        !            51:     # X -configure
        !            52: 
        !            53: This command should create a configuration file and place it in your home
        !            54: directory. To test the generated configuration file, run, e.g.,
        !            55: 
        !            56:     # X -config ~/xorg.conf.new
        !            57: 
        !            58: If this succeeds, you should see a crosshatched background and a cursor in the
        !            59: shape of an X. Try moving the cursor around to verify that the mouse is
        !            60: functional. To quit, press `Ctrl-Alt-Backspace`.
        !            61: 
        !            62: If the above test was successful, move the file into place (as either
        !            63: `/etc/X11/xorg.conf` or `/etc/X11/XF86Config`) and you are ready to go. The
        !            64: following sections may be of interest or use, but are not required reading.
        !            65: 
        !            66: ## The mouse
        !            67: 
        !            68: PS/2 and USB mice will normally be autodetected, and a configuration entry like
        !            69: the following will be generated:
        !            70: 
        !            71:     Section "InputDevice"
        !            72:             Identifier  "Mouse0"
        !            73:             Driver      "mouse"
        !            74:             Option      "Protocol" "wsmouse"
        !            75:             Option      "Device" "/dev/wsmouse"
        !            76:             Option      "ZAxisMapping" "4 5 6 7"
        !            77:     EndSection
        !            78: 
        !            79: For a serial mouse on the first serial port, try something like:
        !            80: 
        !            81:     Section "InputDevice"
        !            82:             Identifier  "Mouse0"
        !            83:             Driver      "mouse"
        !            84:             Option      "Protocol" "auto"
        !            85:             Option      "Device" "/dev/tty00"
        !            86:     EndSection
        !            87: 
        !            88: In this example. `/dev/tty00` is the first serial port. Use `/dev/tty01` for the
        !            89: second, and so on. Protocol `auto` will try to automatically detect the protocol
        !            90: of your serial mouse. If this doesn't work, try values like `Microsoft`,
        !            91: `IntelliMouse` or `Logitech`. See
        !            92: [mousedrv(4)](http://netbsd.gw.com/cgi-bin/man-cgi?mousedrv+4+NetBSD-5.0.1+i386)
        !            93: for more information.
        !            94: 
        !            95: ## The keyboard
        !            96: 
        !            97: Even if you have already configured your keyboard for wscons (see
        !            98: [[wscons|guide/cons#wscons]]), you need to configure it for X as well, at
        !            99: least if you want to use a non-US layout.
        !           100: 
        !           101: An easy solution is to use the XKB protocol to specify the keyboard type and
        !           102: layout.
        !           103: 
        !           104: Here is an example that shows how to use a German keyboard:
        !           105: 
        !           106:     Section "InputDevice"
        !           107:             Identifier  "Keyboard0"
        !           108:             Driver      "kbd"
        !           109:             Option      "XkbRules" "xorg"
        !           110:             Option      "XkbModel" "pc105"
        !           111:             Option      "XkbLayout" "de"
        !           112:             Option      "XkbOptions" "ctrl:nocaps"
        !           113:     EndSection
        !           114: 
        !           115: If you wish to change the repeat rate of your keyboard, you can set it with the
        !           116: `AutoRepeat` option, which takes two arguments: delay and rate, respectively.
        !           117: The following example sets the initial delay to 200 milliseconds and the repeat
        !           118: rate to 30 per second:
        !           119: 
        !           120:     Option      "AutoRepeat"    "200 30"
        !           121: 
        !           122: If X is already running, the keyboard repeat rate can be changed with the
        !           123: [xset(1)](http://netbsd.gw.com/cgi-bin/man-cgi?xset+1+NetBSD-5.0.1+i386)
        !           124: command:
        !           125: 
        !           126:     $ xset r 200 30
        !           127: 
        !           128: You can also run this command in your `.xinitrc` file. See below ([[Customizing
        !           129: X|guide/x#customizing]]) for more information.
        !           130: 
        !           131: ## The monitor
        !           132: 
        !           133: If X does not run at the resolution you think it should, first run **xrandr**
        !           134: and see if the resolution you want is listed. If your preferred resolution is
        !           135: listed in that command's output, you can change resolutions with, e.g.,
        !           136: 
        !           137:     $ xrandr -s 1680x1050
        !           138: 
        !           139: If your preferred resolution is not listed, or you have issues with flickering,
        !           140: you may need to manually specify your monitor's horizontal and vertical
        !           141: frequencies. These can be set with the `HorizSync` and `VertRefresh` directives
        !           142: in the `Monitor` section. An example is provided below.
        !           143: 
        !           144:     Section "Monitor"
        !           145:             Identifier   "Monitor0"
        !           146:             VendorName   "Monitor Vendor"
        !           147:             ModelName    "Monitor Model"
        !           148:             HorizSync    30-83
        !           149:             VertRefresh  56-75
        !           150:     EndSection
        !           151: 
        !           152: Possible values for your specific monitor can often be found in the manual,
        !           153: sometimes even on the monitor itself.
        !           154: 
        !           155: ## The video card
        !           156: 
        !           157: Normally, your video card will be automatically detected. In the event that this
        !           158: autodetection fails, all available drivers can be found in
        !           159: `/usr/X11R7/lib/modules/drivers`. (Replace `X11R7` with `X11R6` if you use a
        !           160: port that has not yet switched to X.Org.) The driver can be set with the
        !           161: `Driver` directive in the `Device` section, as shown below.
        !           162: 
        !           163:     Section "Device"
        !           164:             Identifier  "Card0"
        !           165:             Driver      "intel"
        !           166:     EndSection
        !           167: 
        !           168: ## Starting X
        !           169: 
        !           170: You can start X with the following command:
        !           171: 
        !           172:     $ startx
        !           173: 
        !           174: If your basic X server configuration is correct, you are left in the X
        !           175: environment with the default window manager (twm). If you want a more advanced
        !           176: window manager or desktop environment, many are available in pkgsrc. See [[Other
        !           177: window managers or desktop
        !           178: environments|guide/x#other_window_managers_or_desktop_environments]] for
        !           179: information about adding and changing window managers.
        !           180: 
        !           181: ## Customizing X
        !           182: 
        !           183: One of the first things you will want to do is to change the programs that run
        !           184: when X is first started. The easiest way to do this is to copy the default
        !           185: `.xinitrc` file to your home directory and modify it, or create a simple new one
        !           186: from scratch. For example:
        !           187: 
        !           188:     $ cp /etc/X11/xinit/xinitrc ~/.xinitrc
        !           189:     $ vi ~/.xinitrc
        !           190: 
        !           191: The following example shows how to start the window manager (twm) and open an
        !           192: instance of the xclock and xterm programs. The screen background color is set to
        !           193: `bisque4`, which is defined in `/usr/X11R7/lib/X11/rgb.txt`.
        !           194: 
        !           195:     ...
        !           196:     # start some nice programs
        !           197:     xclock -geometry 50x50-1-1 &
        !           198:     xsetroot -solid bisque4 &
        !           199:     xterm -geometry 80x34-1+1 -bg OldLace &
        !           200:     
        !           201:     exec twm    # no '&' here
        !           202: 
        !           203: With this type of setup, to quit X you must exit the window manager, which is
        !           204: usually done by selecting `exit` from its menu.
        !           205: 
        !           206: The above example is very simple, but illustrates the basics of controlling the
        !           207: clients that are run when X is started. You can run any number of commands from
        !           208: your `.xinitrc`, including basic X configuration commands like **xset b off** to
        !           209: turn off the bell.
        !           210: 
        !           211: ## Other window managers or desktop environments
        !           212: 
        !           213: If you don't like twm, which is a very simple window manager, you can install
        !           214: another window manager or a desktop environment from pkgsrc. The following
        !           215: example uses the Openbox window manager, but there are many others available in
        !           216: `pkgsrc/wm`.
        !           217: 
        !           218: Openbox can be installed via binary packages or compiled with pkgsrc. As always,
        !           219: assuming a properly set `PKG_PATH`, the binary package method is:
        !           220: 
        !           221:     # pkg_add -v openbox
        !           222: 
        !           223: Or, with pkgin:
        !           224: 
        !           225:     # pkgin install openbox
        !           226: 
        !           227: To build it with pkgsrc, run:
        !           228: 
        !           229:     # cd /usr/pkgsrc/wm/openbox
        !           230:     # make install
        !           231: 
        !           232: Openbox is now installed; to start it you must modify your `.xinitrc` file:
        !           233: substitute the line which calls `twm` with a line which calls `openbox`. For
        !           234: example:
        !           235: 
        !           236:     # start some useful programs
        !           237:     xclock -geometry 50x50-1-1 &
        !           238:     # start window manager:
        !           239:     exec openbox   # no '&' here
        !           240: 
        !           241: The [startx(1)](http://netbsd.gw.com/cgi-bin/man-cgi?startx+1+NetBSD-current)
        !           242: command will start the X11 session with Openbox. As configured in the example
        !           243: `.xinitrc` file above, choosing `Exit` or similar from the window manager's menu
        !           244: will quit the window manager and end the X11 session.
        !           245: 
        !           246: Installing a desktop environment is almost as easy. The following example shows
        !           247: how to use the Xfce desktop environment.
        !           248: 
        !           249:     # pkg_add -v xfce4
        !           250:     # cp /usr/pkg/share/examples/rc.d/famd /etc/rc.d
        !           251:     # cp /usr/pkg/share/examples/rc.d/dbus /etc/rc.d
        !           252:     # cp /usr/pkg/share/examples/rc.d/hal /etc/rc.d
        !           253:     # echo rpcbind=YES >> /etc/rc.conf
        !           254:     # echo famd=YES >> /etc/rc.conf
        !           255:     # echo dbus=YES >> /etc/rc.conf
        !           256:     # echo hal=YES >> /etc/rc.conf
        !           257:     # /etc/rc.d/rpcbind start
        !           258:     # /etc/rc.d/famd start
        !           259:     # /etc/rc.d/dbus start
        !           260:     # /etc/rc.d/hal start
        !           261: 
        !           262: After running the above commands, edit your `.xinitrc` as above and change
        !           263: `openbox` (or `twm`) to `xfce4-session`. The next time you run `startx`, the
        !           264: Xfce desktop environment will be started.
        !           265: 
        !           266: ## Graphical login with xdm
        !           267: 
        !           268: If you always use X and the first thing you do after you log in is run `startx`,
        !           269: you can set up a graphical login to do this automatically. It is very easy:
        !           270: 
        !           271:  1. Create the `.xsession` file in your home directory. This file is similar to
        !           272:     `.xinitrc` and can, in fact, be a link to it.
        !           273: 
        !           274:         $ ln -s .xinitrc ~/.xsession
        !           275: 
        !           276:  2. Modify `/etc/rc.conf`, adding the following line:
        !           277: 
        !           278:         xdm=YES       # x11 display manager
        !           279: 
        !           280:  3. Start xdm (or reboot your system, as this will be done automatically from
        !           281:     now on):
        !           282: 
        !           283:         # /etc/rc.d/xdm start
        !           284: 
        !           285: The configuration files for xdm are in the `/etc/X11/xdm` directory. The
        !           286: `Xservers` file specifies the virtual console that X is started on. It defaults
        !           287: to `vt05`, which is the console you reach via `Ctrl+Alt+F5`. If you want to use
        !           288: a different virtual console, change vt05 as desired. In order to avoid keyboard
        !           289: contention between getty and xdm, be sure to start xdm on a virtual terminal
        !           290: where getty is disabled. For example, if in `Xservers` you have:
        !           291: 
        !           292:     :0 local /usr/X11R6/bin/X :0 vt04
        !           293: 
        !           294: Then, in `/etc/ttys` you should have:
        !           295: 
        !           296:     ttyE3   "/usr/libexec/getty Pc"         vt220   off secure
        !           297: 
        !           298: (Please note that `vt04` corresponds to `ttyE3`; In `/etc/X11/xdm/Xservers`,
        !           299: numbering starts at 1, but in `/etc/ttys`, numbering starts at 0).
        !           300: 
        !           301: If you want to change the look of your xdm login screen, you can modify the xdm
        !           302: configuration file. For example, to change the background color you can add the
        !           303: following line to the `Xsetup_0` file:
        !           304: 
        !           305:     xsetroot -solid SeaGreen
        !           306: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb