<?xml version="1.0"?>
<!DOCTYPE webpage
  PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
         "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">

<webpage id="docs-x-index">
  <config param="desc" value="NetBSD Documentation: The X Window System"/>
  <config param="cvstag" 
    value="$NetBSD: index.xml,v 1.3 2010/02/01 23:08:55 snj Exp $"/>
  <config param="rcsdate" value="$Date: 2010/02/01 23:08:55 $"/>

  <head>
    <!-- Copyright (c) 1994-2005
    The NetBSD Foundation, Inc.  ALL RIGHTS RESERVED. -->

    <title>NetBSD Documentation: The X Window System</title>
  </head>

  <sect1 id="see-guide">
    <note>Please see the NetBSD Guide's
     <ulink url="../guide/en/chap-x.html">chapter on X</ulink> for more
     information about X.</note>
  </sect1>

  <sect1 role="toc">

    <sect2 id="running-x">
      <title>Running X</title>

      <sect3 id="x-keyboard-nocaps">
	<title>How do I make the Caps key another Control key</title>

	<para>For XFree 3.x (as shipped with NetBSD 1.l5), add
	  <quote><code>XkbOptions "ctrl:nocaps"</code></quote> if you
	  want the caps-lock key become a second control-key. If you
	  want to use the "Windows" keys on your keyboard, you can get
	  some useful keysyms for them by using 
	  <quote><code>XkbModel "pc105"</code></quote> instead.</para>

	<para>XFree 4.x uses a different config file format. For it,
	  put
	  <screen>Option "XkbOptions" "ctrl:nocaps"</screen>
	  into the "InputDevice" section of your XF86Config file.</para>
      </sect3>
	
      <sect3 id="bypassing_xdm">
	<title>How to bypass xdm</title>

	<para>If &man.xdm.1; is enabled but you are unable to login
	  for some reason, possibly because there is no root password,
	  and you do not have virtual consoles enabled (or they are
	  not yet supported on your port), you can either press ^C at
	  the immediately after the boot messages indicate xdm is
	  starting, or:</para>

	  <itemizedlist>
	    <listitem>Boot to single user mode - Usually this is
	      accomplished by passing '-s' at the end of the boot
	      command.</listitem>
	    <listitem>Start the shell - Press <code>ENTER</code> when
	      prompted for the shell.</listitem>
	    <listitem>Check and mount the disks using &man.fsck.8; and
	      &man.mount.8; - <code>fsck -p ; mount -vat ffs</code></listitem>
	    <listitem>Set term terminal type -
	      <code>TERM=<emphasis>vt100</emphasis> ; export TERM</code>
	      Note: you may need to use a different terminal type such
	      as 'pc3' or 'sun'.</listitem>
	    <listitem>Fix problem - Edit
	      <filename>/etc/rc.conf</filename> to disable xdm, run
	      &man.passwd.1; to set root's password, or take whatever
	      other corrective action is needed</listitem>
	  </itemizedlist>
      </sect3>

      <sect3 id="startx_not_found">
	<title>When I type '<emphasis role="bold"><code>startx</code></emphasis>' I get the message: <code>startx: Command not found.</code> What's wrong?</title>
	<para>You need to add the location of the X binaries to your
	  shell's <code>path</code> variable. For &man.csh.1; and its
	  derivatives, add <filename>/usr/X11R6/bin</filename>
	  to the line in your <filename>.cshrc</filename> file which
	  sets the <code>path</code> variable. For <code>sh</code> and
	  its derivatives, you'll need to modify you
	  <filename>.profile</filename> instead.</para>
      </sect3>
	  
      <sect3 id="xinit_not_found">
	<title>Unable to run X - '<emphasis role="bold">xinit: not found</emphasis>'</title>

	<para>You need <filename>/usr/X11R6/bin</filename> in your
	  path. As root add '<emphasis 
	    role="bold"><code>set path = ( $path /usr/X11R6/bin )</code></emphasis>'
	  to <filename>/etc/csh.cshrc</filename>, and start a new
	  shell.</para>
      </sect3>

      <sect3 id="startx_fails">
	<title>startx fails -'<emphasis role="bold">X connection to: 0.0 broken</emphasis>'</title>

	<para>To see the error messages in this case, run:

	  <itemizedlist>
	    <listitem>If your shell is &man.csh.1; or 
	      <filename role="pkg">shells/tcsh</filename>:
	      <screen>startx &gt;&amp; ~/x.log</screen></listitem>
	    <listitem>If your shell is &man.sh.1;, &man.ksh.1;, or similar:
	      <screen>startx &gt; ~/x.log 2&gt;&amp;1</screen></listitem>
	  </itemizedlist>
	  Then view <filename>~/x.log</filename></para>
      </sect3>

      <sect3 id="xconsole">
	<title>Console output (such as from 'su') garbles X display.</title>

	<para>The system is outputting a line to the console
	  indicating something has happened (such as 'su'). You should
	  really run &man.xconsole.1; or one 'xterm -C' to capture
	  this console output.</para>

	<para>You may need to ensure your kernel is compiled with the
	  following enabled:
	  <screen>options  UCONSOLE  # allow anyone to steal the virtual console</screen>
	  See <ulink 
	   url="../kernel/#how_to_build_a_kernel">How to build a kernel</ulink>
	  for details on how to build your own kernels.</para>

	<para>If you're logged in as root, and get annoying
	  <code>portmap</code> notices, you may wish to look at the
	  <ulink url="../misc/#portmap-messup">FAQ entry</ulink>
	  on how to turn those messages off.</para>
      </sect3>

      <sect3 id="xfree86-docs">
	<title><ulink url="http://www.xfree86.org/sos/resources.html">XFree86 Documentation</ulink></title>
      </sect3>

      <sect3 id="which_version">
	<title>Which version of XFree86 am I running?</title>

	<para>To quickly tell which version of the X server you are
	  running, you can use &man.xdpyinfo.1;. E.g.:
	  <screen>$ xdpyinfo | grep release
vendor release number:    335</screen>

	  In the case of XFree86, this tells us that the server
	  version is 3.3.5.</para>
      </sect3>


<sect3 id="anti_aliased">
<title>How to setup anti-aliased fonts on NetBSD for X11</title>

<note><para>
The paths below should be adjusted appropriately if using 
<filename role="pkg">pkgtools/xpkgwedge</filename>.
</para></note>

<orderedlist>

<listitem>
<para>
Install the
<filename role="pkg">fonts/ms-ttf</filename> package from pkgsrc.
If you use the pkgsrc version of X, install also the
<filename role="pkg">fonts/mkfontscale</filename> and
<filename role="pkg">fonts/fontconfig</filename> packages.
</para>
</listitem>

<listitem>

<para>
If using the XFree86 shipped with &os;, you may consider
using <filename role="pkg">fonts/fontconfig</filename> from pkgsrc
as it offers more tweaking options.  Set the variable <varname>
 PREFER.fontconfig</varname> to pkgsrc in the <filename>/etc/mk.conf
</filename> file to ensure that the pkgsrc version is used in
 favour of the shipped (or native) version:
  <screen>
  PREFER.fontconfig=pkgsrc
  </screen>
</para>

<para>
  You may also want to instruct fontconfig to never use
  <emphasis>bitmap fonts</emphasis> again:
  <screen>
  # cd /usr/pkg/etc/fontconfig/conf.d
  # ln -s ../../../share/examples/fontconfig/conf.avail/70-no-bitmaps.conf .
  </screen>
</para>

<para>
You may wish to replace the native fontconfig libraries entirely,
which is useful should you have any previously-compiled binaries
that used it.
  <screen>
  # cd /usr/X11R6/lib
  # mv libfontconfig.so.1.0 libfontconfig.so.1.0.old
  # rm libfontconfig.so.1
  # ln -s ../../pkg/lib/libfontconfig.so.1 .
  # cd /usr/X11R6/bin
  # mv fc-cache fc-cache.old
  # mv fc-list fc-list.old
  </screen>
</para>

</listitem>

<listitem>
<para>
To configure fontconfig, add the following line to your
local.conf.  This file is generally found in
<filename>/etc/fonts/local.conf</filename>.
If you installed the fonts/fontconfig package, you will
<emphasis role="bold">also</emphasis> need to add the line to
<filename>/usr/pkg/etc/fonts/local.conf</filename>
(or replace one with a symbolic link to another):
  <screen>
  &#060;dir&#062;/usr/pkg/lib/X11/fonts/TTF&#060;/dir&#062;
  </screen>
</para>

<para>
The <filename>local.conf</filename> file may look like this:
  <screen>
  &#060;?xml version="1.0"?&#062;
  &#060;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&#062;
  &#060;fontconfig&#062;
  &#060;dir&#062;/usr/pkg/lib/X11/fonts/TTF&#060;/dir&#062;
  &#060;/fontconfig&#062;
  </screen>
</para>

<para>
You can also add other directories containing fonts to the
<filename>local.conf</filename> file. The following lines are
for using teTeX-3.0 and ghostscript fonts:
  <screen>
  &#060;dir&#062;/usr/pkg/share/texmf-dist/fonts/&#060;/dir&#062;
  &#060;dir&#062;/usr/pkg/share/ghostscript/fonts&#060;/dir&#062;
  </screen>  
 </para>

</listitem>

<listitem>
<para>
  Rebuild the font cache for applications that use fontconfig
  <screen>
  # fc-cache -v
  </screen>
Depending on your hardware this may take a long time.
</para>
</listitem>

<listitem>
<para>
Run the following commands:
  <screen>
  # mkfontscale /usr/pkg/lib/X11/fonts/TTF
  # mkfontdir /usr/pkg/lib/X11/fonts/TTF
  </screen>
There should now be the files <filename>fonts.dir</filename> and
 <filename>fonts.scale</filename> in the TTF font directory.
</para>
</listitem>

<listitem>
<para>Configure the X server:
  <itemizedlist>
  <listitem>
  <para> In the <quote>Module</quote> section, make sure that the following exists:
  <screen>
  Load "type1"
  Load "freetype"
  </screen>
  </para>
  </listitem>

  <listitem>
  <para>
  In the <quote>Files</quote> section, verify the order of
  the font paths. Verify that the TTF and Type1
  font paths are before the rest:
    <screen>
    FontPath   "/usr/X11R6/lib/X11/fonts/local/"
    FontPath   "/usr/pkg/lib/X11/fonts/TTF"
    FontPath   "/usr/X11R6/lib/X11/fonts/Type1/"
    FontPath   "/usr/X11R6/lib/X11/fonts/misc/"
    FontPath   "/usr/X11R6/lib/X11/fonts/75dpi/:unscaled"
    FontPath   "/usr/X11R6/lib/X11/fonts/100dpi/:unscaled"
    FontPath   "/usr/X11R6/lib/X11/fonts/75dpi/"
    FontPath   "/usr/X11R6/lib/X11/fonts/100dpi/"</screen>
  </para>

  <para>
  To apply the changes to the current X session, instead of
  restarting X, run the following command
    <screen>
    # xset fp rehash
    </screen>
    This will examine newly added font paths for changes.
  </para>

  <para>
  Instead of adding <quote>FontPath</quote> directives to the X configuration file,
  you can run the following commands from
  <filename>~/.xinitrc</filename>
  (or <filename>~/.xsession</filename>) file:
    <screen>
    xset +fp /usr/X11R6/lib/X11/fonts/Type1
    xset +fp /usr/pkg/lib/X11/fonts/TTF
    xset +fp /usr/X11R6/lib/X11/fonts/local
    </screen>
  </para>

  </listitem>
  </itemizedlist>
</para>
</listitem>

<listitem>
<para>That's it! Run the following commands to test the configuration.
  <screen>
  $ xterm -ls -fg gray -bg black -ls -fa 'Courier New:bold' -fs 10
  </screen>
</para>

<para>
Run the command <userinput>fc-list</userinput> it should list
the fonts available, and shouldn't dump core!
</para>

<para>
While the xterm command from above only tests the fontconfig part, the following
command will test the XLFD-style access:
  <screen>
  $ xterm -fn '-monotype-Courier New-medium-r-normal--0-0-0-0-m-0-iso8859-1'
</screen>
</para>

<para>
Another test is that the following should show multiple fonts:
  <screen>
  $ xlsfonts | grep -i 'courier new'
  </screen>
</para>

</listitem>

<listitem>
<para>
  You can find other TTF font packages under pkgsrc/fonts.
  For example <filename role="pkg">fonts/vera-ttf</filename>
</para>
</listitem>

</orderedlist>

</sect3>


      <sect3 id="fc-cache">
	<title>Xft using applications eat CPU cycles, but don't appear
	to do anything!</title>

	<para>It is possible that the application in question is
	  computing the font information that should have been
	  prepared by fc-cache - re-run '<code>fc-cache -v</code>' to
	  make sure the information in the cache is up-to-date.</para>
      </sect3>

      <sect3 id="font-error">
	<title>'No fonts found' - what does this mean?</title>

	<screen>No fonts found; this probably means that the fontconfig
library is not correctly configured. You may need to
edit the fonts.conf configuration file. More information
about fontconfig can be found in the &man.fontconfig.3; manual
page and on <ulink url="http://fontconfig.org"/></screen>

	<para>You haven't run '<code>fc-cache -v</code>' like the
	  <filename role="pkg">fonts/fontconfig</filename>
	  <ulink url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/fonts/fontconfig/MESSAGE">MESSAGE</ulink>
	  suggests during installation. For details, see
	  '<code>pkg_info -D fontconfig</code>' and <ulink 
	    url="#anti_aliased">above</ulink>.</para>
      </sect3>

      <sect3 id="x_wm">
	<title>How do I change the default window manager?</title>

	<para>First thing to do is to install the window manager you
	  prefer. You can find a lot of them, ready to install, in
	  pkgsrc's <filename role="pkg">wm</filename> category. After
	  a successful installation, figure out how is the
	  binary named. It will usually match package's name.</para>

	<para>Once you know how to execute the window manager, you
	  have to configure your X session to start it up. We will be
	  using twm in our examples (which comes with X), whose binary
	  is named <code>twm</code>:</para>

	<itemizedlist>
	  <listitem>If you are using &man.startx.1;, edit the
	    <filename>~/.xinitrc</filename> file and
	    append the following line to it:
	    <code>exec twm</code></listitem>
	  <listitem>If you are using &man.xdm.1;, edit the
	    <filename>~/.xsession</filename> file and append the 
	    following line to it:
	    <code>exec twm</code></listitem>
	</itemizedlist>

	<para>You can see that the content for each file is the same,
	  so you may want to create a link between them.</para>
      </sect3>
    </sect2>

    <sect2 id="compiling-programs">
      <title>Compiling programs</title>

      <sect3 id="compile_fails_xm">
	<title>Compile fails - 'unable to locate libXm'</title>

	<para>Xm does not come with the standard X11 environment. It is
	  part of <ulink 
	    url="http://www.opengroup.org/desktop/motif/">Motif</ulink>,
	  which is a commercial graphical user interface.</para>

	<para>A freeware implementation of Motif called <ulink 
	    url="http://www.lesstif.org/">Lesstif</ulink> is also available.
	  It is available as part of the <ulink
	    url="../software/packages.html">NetBSD packages collection</ulink>,
	  under <filename role="pkg">x11/lesstif</filename>.</para>
      </sect3>

      <sect3 id="compile_fails_xpm">
	<title>Compile fails - 'unable to locate xpm.h', or '-lXpm: no match'</title>

	<para><filename>xpm.h</filename> is part of the X PixMap
	  library, used by many programs to allow more multi (than
	  two) colour icons.
	  It is available as part of the <ulink 
	    url="../software/packages.html">NetBSD packages collection</ulink>,
	  under <filename role="pkg">graphics/xpm</filename></para>
      </sect3>

      <sect3 id="compile_basic">
	<title>Compile fails to link: Undefined symbol '_XOpenDisplay'</title>

	<para>If it is a third party item of software, you should
	  check if a version is available via the <ulink
	    url="../software/packages.html">NetBSD packages collection</ulink>.
	  If you are writing you own code you need to ensure you link
	  against the necessary X libraries. In this case, add
	  <code>-L/usr/X11R6 -lX11</code> to the end of your link 
	  line.</para>
      </sect3>
    </sect2>
  </sect1>

  <parentsec url="../" text="NetBSD Documentation"/>

</webpage>

