fixed pkg install for kde
[ikiwiki.git] / docs / newhandbook / X / index.mdwn
1 # The X Window System 
2 ***Updated for X.Org's X11 server by Ken Tom and Marc Fonvieille. Updated for DragonFly by Victor Balada Diaz. Updated for 2014 pkgng by Warren Postma***
3
4 [[!toc  levels=3]]
5
6
7 ## Synopsis 
8
9 This chapter will cover the installation and some configuration of X11. For more information on the video hardware that X11 supports, check the [X.org](http://www.x.org/) web site. If you have problems configuring, just search the web. There are lots of tutorials and guides on how to set up your X properly.
10
11
12 Before reading this chapter, you should know how to install additional third-party software. Read the pkgsrc section of the documentation.
13
14
15
16
17
18 ## Understanding X 
19
20 ### The Window Manager 
21
22
23
24 X.org itself does not give you a window manager. You will have to choose one and install it yourself. There are dozens of window managers available for X. Each of these provides a different look and feel. Window managers are available in the `wm` category of the pkgsrc collection. 
25
26
27 In addition, the  **KDE**  and  **GNOME**  desktop environments both have their own window managers which integrate with the desktop.
28
29
30 Every window manager also has a different configuration mechanism. Read your manager's documentation to learn more.
31
32
33
34
35
36 ## Installing X
37
38 **X.org**  is currently available in the DragonFly dports collection.
39
40 To install:
41
42     # pkg install xorg-7.7
43
44 By the time you read this, it might be a newer version of xorg than 7.7, you can also try this general command:
45
46     # pkg install xorg
47
48
49
50 ## Configuring X
51
52
53
54           ***Contributed by Christopher Shumway. ***
55
56
57 As of version 7.3, Xorg can often work without any configuration file by simply typing at prompt:
58
59     
60
61     % startx
62
63 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:
64    
65
66     # Xorg -configure
67
68
69 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.
70
71
72
73 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:
74
75    
76
77     # Xorg -config xorg.conf.new
78
79
80 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.
81
82
83
84 **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`:
85
86         # rcenable moused
87
88
89
90 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`.
91
92     
93
94 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).
95
96
97
98
99 ## The X Display Manager 
100
101  ***Contributed by Seth Kingsley.***
102
103
104
105 ### Overview 
106
107
108
109  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.
110
111
112
113  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.
114
115
116
117 ### Using XDM 
118
119
120
121  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:
122
123
124
125      
126
127     ttyv8   "/usr/pkg/bin/xdm -nodaemon"  xterm   off secure
128
129
130
131
132
133  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.
134
135
136
137 ### Configuring XDM 
138
139
140
141  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:
142
143
144 [[!table  data="""
145 <tablestyle="width:100%">  **File**  |  **Description**
146 <tablestyle="width:100%"> `Xaccess` | Client authorization ruleset.
147 `Xresources` | Default X resource values.
148 `Xservers` | List of remote and local displays to manage.
149 `Xsession` | Default session script for logins.
150 `Xsetup_`* | Script to launch applications before the login interface.
151 `xdm-config` | Global configuration for all displays running on this machine.
152 `xdm-errors` | Errors generated by the server program.
153 `xdm-pid` | The process ID of the currently running XDM. |
154
155 """]]
156
157
158  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).
159
160
161
162  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.
163
164
165
166 #### Xaccess 
167
168
169
170  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.
171
172
173
174 #### Xresources 
175
176
177
178  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.
179
180
181
182 #### Xservers 
183
184
185
186  This is a list of the remote displays the chooser should provide as choices.
187
188
189
190 #### Xsession 
191
192
193
194  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.
195
196
197
198 #### Xsetup_* 
199
200
201
202  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`.
203
204
205
206 #### xdm-config 
207
208
209
210  This contains settings in the form of app-defaults that are applicable to every display that this installation manages.
211
212
213
214 #### xdm-errors 
215
216
217
218  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.
219
220
221
222 ### Running a Network Display Server 
223
224
225
226  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:
227
228
229
230      
231
232     ! SECURITY: do not listen for XDMCP or Chooser requests
233
234     ! Comment out this line if you want to manage X terminals with xdm
235
236     DisplayManager.requestPort:     0
237
238
239
240
241
242  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.
243
244
245
246 ### Replacements for XDM 
247
248
249
250  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.
251
252
253 ----
254
255
256
257 ## Desktop Environments 
258
259  ***Contributed by Valentino Vaschetto. ***
260
261  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** .
262
263
264
265 ### GNOME 
266
267
268
269 #### About GNOME 
270
271
272
273    **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.
274
275
276
277 #### Installing GNOME 
278
279
280
281    **GNOME**  can be easily installed from a package or from the pkgsrc framework:
282
283
284
285   To install the  **GNOME**  package from the network, simply type:
286
287     # pkg install gnome-desktop
288
289
290
291
292   To build  **GNOME**  from source, if you have the pkgsrc tree on your system:      
293
294     # cd /usr/pkgsrc/meta-pkgs/gnome
295
296     # bmake install clean
297
298
299
300   Once  **GNOME**  is installed, the X server must be told to start  **GNOME**  instead of a default window manager.
301
302
303
304   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.
305
306
307
308 **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:
309
310
311
312       
313
314     % echo "/usr/pkg/bin/gnome-session" > ~/.xinitrc
315
316
317
318
319
320   Next, type `startx`, and the  **GNOME**  desktop environment will be started.
321
322
323 **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** :
324
325
326
327         
328
329     % echo "#!/bin/sh" > ~/.xsession
330
331     % echo "/usr/pkg/bin/gnome-session" >> ~/.xsession
332
333     % chmod +x ~/.xsession
334
335
336
337
338
339   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** .
340
341
342
343 #### Anti-aliased Fonts with GNOME 
344
345
346
347   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).
348   
349   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.
350
351
352
353 ### KDE 
354
355
356
357 #### About KDE 
358
359
360
361   **KDE**  is an easy to use contemporary desktop environment. Some of the things that  **KDE**  brings to the user are:
362
363 * A beautiful contemporary desktop
364
365 * A desktop exhibiting complete network transparency
366
367 * An integrated help system allowing for convenient, consistent access to help on the use of the  **KDE**  desktop and its applications
368
369 * Consistent look and feel of all  **KDE**  applications
370
371 * Standardized menu and toolbars, keybindings, color-schemes, etc.
372
373 * Internationalization:  **KDE**  is available in more than 40 languages
374
375 * Centralized consisted dialog driven desktop configuration
376
377 * A great number of useful  **KDE**  applications
378
379   **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/).
380
381
382
383 #### Installing KDE 
384
385
386  Just as with  **GNOME**  or any other desktop environment, the easiest way to install  **KDE**  is through the pkgsrc framework or from a package:
387
388
389
390  To install the  **KDE**  4.10 package from the network, simply type:
391
392    # pkg install kde-4.10
393
394
395  To build  **KDE**  from source, using the pkgsrc framework:
396
397     # cd /usr/pkgsrc/meta-pkgs/kde3
398
399     # bmake install clean
400
401
402
403
404
405  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:
406
407
408     % echo "exec startkde" > ~/.xinitrc
409
410
411  Now, whenever the X Window System is invoked with `startx`,  **KDE**  will be the desktop.
412
413  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.
414
415
416
417 #### More Details on KDE 
418
419
420
421  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.
422
423  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.
424
425
426
427 #### The KDE Display Manager 
428
429
430
431  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.
432
433
434
435  To enable  **kdm** , the `ttyv8` entry in `/etc/ttys` has to be adapted. The line should look as follows:
436   
437
438     ttyv8 "/usr/pkg/bin/kdm -nodaemon" xterm on secure
439
440
441     
442 ### XFce 
443
444
445
446 #### About XFce 
447
448
449   **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:
450
451 * A simple, easy-to-handle desktop
452
453 * Fully configurable via mouse, with drag and drop, etc
454
455 * Main panel similar to  **CDE** , with menus, applets and applications launchers
456
457 * Integrated window manager, file manager, sound manager,  **GNOME**  compliance module, and other things
458
459 * Themeable (since it uses GTK+)
460
461 * Fast, light and efficient: ideal for older/slower machines or machines with memory limitations
462
463
464 More information on  **XFce**  can be found on the [XFce website](http://www.xfce.org/).
465
466
467
468 #### Installing XFce 
469
470
471
472  A binary package for  **XFce**  exists. To install, simply type:
473
474     # pkg install xfce4
475
476
477  Alternatively, to build from source, use the pkgsrc framework:
478
479    
480
481     # cd /usr/pkgsrc/meta-pkgs/xfce4
482
483     # bmake install clean
484
485
486
487
488  Now, tell the X server to launch  **XFce**  the next time X is started. Simply type this:
489
490     % echo "/usr/pkg/bin/startxfce4" > ~/.xinitrc
491
492
493
494  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).
495
496
497
498 <!-- XXX: FreeBSD's handbook has a nice user-oriented section about X applications here. maybe we should have one, too -->
499
500 ----