chapter06/ncurses.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4   <!ENTITY % general-entities SYSTEM "../general.ent">
   5   %general-entities;
   6 ]>
   7
   8 <sect1 id="ch-system-ncurses" role="wrap">
   9   <?dbhtml filename="ncurses.html"?>
  10
  11   <sect1info condition="script">
  12     <productname>ncurses</productname>
  13     <productnumber>&ncurses-version;</productnumber>
  14     <address>&ncurses-url;</address>
  15   </sect1info>
  16
  17   <title>Ncurses-&ncurses-version;</title>
  18
  19   <indexterm zone="ch-system-ncurses">
  20     <primary sortas="a-Ncurses">Ncurses</primary>
  21   </indexterm>
  22
  23   <sect2 role="package">
  24     <title/>
  25
  26     <para>The Ncurses package contains libraries for terminal-independent
  27     handling of character screens.</para>
  28
  29     <segmentedlist>
  30       <segtitle>&buildtime;</segtitle>
  31       <segtitle>&diskspace;</segtitle>
  32
  33       <seglistitem>
  34         <seg>&ncurses-ch6-sbu;</seg>
  35         <seg>&ncurses-ch6-du;</seg>
  36       </seglistitem>
  37     </segmentedlist>
  38
  39   </sect2>
  40
  41   <sect2 role="installation">
  42     <title>Installation of Ncurses</title>
  43
  44     <para>Don't install a static library that is not handled by configure:</para>
  45
  46 <screen><userinput remap="pre">sed -i '/LIBTOOL_INSTALL/d' c++/Makefile.in</userinput></screen>
  47
  48     <para>Prepare Ncurses for compilation:</para>
  49
  50 <screen><userinput remap="configure">./configure --prefix=/usr           \
  51             --mandir=/usr/share/man \
  52             --with-shared           \
  53             --without-debug         \
  54             --without-normal        \
  55             --enable-pc-files       \
  56             --enable-widec</userinput></screen>
  57
  58     <variablelist>
  59       <title>The meaning of the new configure options:</title>
  60
  61       <varlistentry>
  62         <term><parameter>--enable-widec</parameter></term>
  63         <listitem>
  64           <para>This switch causes wide-character libraries (e.g., <filename
  65           class="libraryfile">libncursesw.so.&ncurses-version;</filename>)
  66           to be built instead of normal ones (e.g., <filename
  67           class="libraryfile">libncurses.so.&ncurses-version;</filename>).
  68           These wide-character libraries are usable in both multibyte and
  69           traditional 8-bit locales, while normal libraries work properly
  70           only in 8-bit locales. Wide-character and normal libraries are
  71           source-compatible, but not binary-compatible.</para>
  72         </listitem>
  73       </varlistentry>
  74
  75       <varlistentry>
  76         <term><parameter>--enable-pc-files</parameter></term>
  77         <listitem>
  78           <para>This switch generates and installs .pc files for pkg-config.
  79           </para>
  80         </listitem>
  81       </varlistentry>
  82
  83       <varlistentry>
  84         <term><parameter>--without-normal</parameter></term>
  85         <listitem>
  86           <para>This switch disables building and installing most static libraries.
  87           </para>
  88         </listitem>
  89       </varlistentry>
  90
  91     </variablelist>
  92
  93     <para>Compile the package:</para>
  94
  95 <screen><userinput remap="make">make</userinput></screen>
  96
  97     <para>This package has a test suite, but it can only be run after the
  98     package has been installed.  The tests reside in the
  99     <filename class="directory">test/</filename> directory.  See the
 100     <filename>README</filename> file in that directory for further details.
 101     </para>
 102
 103     <para>Install the package:</para>
 104
 105 <screen><userinput remap="install">make install</userinput></screen>
 106
 107     <para>Move the shared libraries to the
 108     <filename class="directory">/lib</filename> directory, where they are
 109     expected to reside:</para>
 110
 111 <screen><userinput remap="install">mv -v /usr/lib/libncursesw.so.6* /lib</userinput></screen>
 112
 113     <para>Because the libraries have been moved, one symlink points to
 114     a non-existent file. Recreate it:</para>
 115
 116 <screen><userinput remap="install">ln -sfv ../../lib/$(readlink /usr/lib/libncursesw.so) /usr/lib/libncursesw.so</userinput></screen>
 117
 118     <para>Many applications still expect the linker to be able to find
 119     non-wide-character Ncurses libraries. Trick such applications into linking with
 120     wide-character libraries by means of symlinks and linker scripts:</para>
 121
 122 <screen><userinput remap="install">for lib in ncurses form panel menu ; do
 123     rm -vf                    /usr/lib/lib${lib}.so
 124     echo "INPUT(-l${lib}w)" &gt; /usr/lib/lib${lib}.so
 125     ln -sfv ${lib}w.pc        /usr/lib/pkgconfig/${lib}.pc
 126 done</userinput></screen>
 127
 128     <para>Finally, make sure that old applications that look for
 129     <filename class="libraryfile">-lcurses</filename> at build time are still
 130     buildable:</para>
 131
 132 <screen><userinput remap="install">rm -vf                     /usr/lib/libcursesw.so
 133 echo "INPUT(-lncursesw)" &gt; /usr/lib/libcursesw.so
 134 ln -sfv libncurses.so      /usr/lib/libcurses.so</userinput></screen>
 135
 136     <para>If desired, install the Ncurses documentation:</para>
 137
 138 <screen><userinput remap="install">mkdir -v       /usr/share/doc/ncurses-&ncurses-version;
 139 cp -v -R doc/* /usr/share/doc/ncurses-&ncurses-version;</userinput></screen>
 140
 141     <note>
 142       <para>The instructions above don't create non-wide-character Ncurses
 143       libraries since no package installed by compiling from sources would
 144       link against them at runtime. However, the only known binary-only
 145       applications that link against non-wide-character Ncurses libraries
 146       require version 5. If you must have such libraries because
 147       of some binary-only application or to be compliant with LSB, build
 148       the package again with the following commands:</para>
 149
 150 <screen role="nodump"><userinput>make distclean
 151 ./configure --prefix=/usr    \
 152             --with-shared    \
 153             --without-normal \
 154             --without-debug  \
 155             --without-cxx-binding \
 156             --with-abi-version=5
 157 make sources libs
 158 cp -av lib/lib*.so.5* /usr/lib</userinput></screen>
 159     </note>
 160
 161   </sect2>
 162
 163   <sect2 id="contents-ncurses" role="content">
 164     <title>Contents of Ncurses</title>
 165
 166     <segmentedlist>
 167       <segtitle>Installed programs</segtitle>
 168       <segtitle>Installed libraries</segtitle>
 169       <segtitle>Installed directories</segtitle>
 170
 171       <seglistitem>
 172         <seg>
 173            captoinfo (link to tic),
 174            clear,
 175            infocmp,
 176            infotocap (link to tic),
 177            ncursesw6-config,
 178            reset (link to tset),
 179            tabs,
 180            tic,
 181            toe,
 182            tput, and
 183            tset
 184         </seg>
 185         <seg>
 186            libcursesw.so (symlink and linker script to libncursesw.so),
 187            libformw.so,
 188            libmenuw.so,
 189            libncursesw.so,
 190            libncurses++w.a,
 191            libpanelw.so, and their non-wide-character counterparts without "w"
 192               in the library names.</seg>
 193         <seg>
 194            /usr/share/tabset,
 195            /usr/share/terminfo, and
 196            /usr/share/doc/ncurses-&ncurses-version;
 197         </seg>
 198       </seglistitem>
 199     </segmentedlist>
 200
 201     <variablelist>
 202       <bridgehead renderas="sect3">Short Descriptions</bridgehead>
 203       <?dbfo list-presentation="list"?>
 204       <?dbhtml list-presentation="table"?>
 205
 206       <varlistentry id="captoinfo">
 207         <term><command>captoinfo</command></term>
 208         <listitem>
 209           <para>Converts a termcap description into a terminfo description</para>
 210           <indexterm zone="ch-system-ncurses captoinfo">
 211             <primary sortas="b-captoinfo">captoinfo</primary>
 212           </indexterm>
 213         </listitem>
 214       </varlistentry>
 215
 216       <varlistentry id="clear">
 217         <term><command>clear</command></term>
 218         <listitem>
 219           <para>Clears the screen, if possible</para>
 220           <indexterm zone="ch-system-ncurses clear">
 221             <primary sortas="b-clear">clear</primary>
 222           </indexterm>
 223         </listitem>
 224       </varlistentry>
 225
 226       <varlistentry id="infocmp">
 227         <term><command>infocmp</command></term>
 228         <listitem>
 229           <para>Compares or prints out terminfo descriptions</para>
 230           <indexterm zone="ch-system-ncurses infocmp">
 231             <primary sortas="b-infocmp">infocmp</primary>
 232           </indexterm>
 233         </listitem>
 234       </varlistentry>
 235
 236       <varlistentry id="infotocap">
 237         <term><command>infotocap</command></term>
 238         <listitem>
 239           <para>Converts a terminfo description into a termcap description</para>
 240           <indexterm zone="ch-system-ncurses infotocap">
 241             <primary sortas="b-infotocap">infotocap</primary>
 242           </indexterm>
 243         </listitem>
 244       </varlistentry>
 245
 246       <varlistentry id="ncursesw6-config">
 247         <term><command>ncursesw6-config</command></term>
 248         <listitem>
 249           <para>Provides configuration information for ncurses</para>
 250           <indexterm zone="ch-system-ncurses ncursesw6-config">
 251             <primary sortas="b-ncursesw5-config">ncursesw6-config</primary>
 252           </indexterm>
 253         </listitem>
 254       </varlistentry>
 255
 256       <varlistentry id="reset">
 257         <term><command>reset</command></term>
 258         <listitem>
 259           <para>Reinitializes a terminal to its default values</para>
 260           <indexterm zone="ch-system-ncurses reset">
 261             <primary sortas="b-reset">reset</primary>
 262           </indexterm>
 263         </listitem>
 264       </varlistentry>
 265
 266       <varlistentry id="tabs">
 267         <term><command>tabs</command></term>
 268         <listitem>
 269           <para>Clears and sets tab stops on a terminal</para>
 270           <indexterm zone="ch-system-ncurses tabs">
 271             <primary sortas="b-tabs">tabs</primary>
 272           </indexterm>
 273         </listitem>
 274       </varlistentry>
 275
 276       <varlistentry id="tic">
 277         <term><command>tic</command></term>
 278         <listitem>
 279           <para>The terminfo entry-description compiler that translates a
 280           terminfo file from source format into the binary format needed for the
 281           ncurses library routines [A terminfo file contains information on the
 282           capabilities of a certain terminal.]</para>
 283           <indexterm zone="ch-system-ncurses tic">
 284             <primary sortas="b-tic">tic</primary>
 285           </indexterm>
 286         </listitem>
 287       </varlistentry>
 288
 289       <varlistentry id="toe">
 290         <term><command>toe</command></term>
 291         <listitem>
 292           <para>Lists all available terminal types, giving the primary name and
 293           description for each</para>
 294           <indexterm zone="ch-system-ncurses toe">
 295             <primary sortas="b-toe">toe</primary>
 296           </indexterm>
 297         </listitem>
 298       </varlistentry>
 299
 300       <varlistentry id="tput">
 301         <term><command>tput</command></term>
 302         <listitem>
 303           <para>Makes the values of terminal-dependent capabilities available to
 304           the shell; it can also be used to reset or initialize a terminal or
 305           report its long name</para>
 306           <indexterm zone="ch-system-ncurses tput">
 307             <primary sortas="b-tput">tput</primary>
 308           </indexterm>
 309         </listitem>
 310       </varlistentry>
 311
 312       <varlistentry id="tset">
 313         <term><command>tset</command></term>
 314         <listitem>
 315           <para>Can be used to initialize terminals</para>
 316           <indexterm zone="ch-system-ncurses tset">
 317             <primary sortas="b-tset">tset</primary>
 318           </indexterm>
 319         </listitem>
 320       </varlistentry>
 321
 322       <varlistentry id="libcursesw">
 323         <term><filename class="libraryfile">libcursesw</filename></term>
 324         <listitem>
 325           <para>A link to <filename>libncursesw</filename></para>
 326           <indexterm zone="ch-system-ncurses libcursesw">
 327             <primary sortas="c-libcursesw">libcursesw</primary>
 328           </indexterm>
 329         </listitem>
 330       </varlistentry>
 331
 332       <varlistentry id="libncursesw">
 333         <term><filename class="libraryfile">libncursesw</filename></term>
 334         <listitem>
 335           <para>Contains functions to display text in many complex ways on a
 336           terminal screen; a good example of the use of these functions is the
 337           menu displayed during the kernel's <command>make
 338           menuconfig</command></para>
 339           <indexterm zone="ch-system-ncurses libncursesw">
 340             <primary sortas="c-libncursesw">libncursesw</primary>
 341           </indexterm>
 342         </listitem>
 343       </varlistentry>
 344
 345       <varlistentry id="libformw">
 346         <term><filename class="libraryfile">libformw</filename></term>
 347         <listitem>
 348           <para>Contains functions to implement forms</para>
 349           <indexterm zone="ch-system-ncurses libformw">
 350             <primary sortas="c-libformw">libformw</primary>
 351           </indexterm>
 352         </listitem>
 353       </varlistentry>
 354
 355       <varlistentry id="libmenuw">
 356         <term><filename class="libraryfile">libmenuw</filename></term>
 357         <listitem>
 358           <para>Contains functions to implement menus</para>
 359           <indexterm zone="ch-system-ncurses libmenuw">
 360             <primary sortas="c-libmenuw">libmenuw</primary>
 361           </indexterm>
 362         </listitem>
 363       </varlistentry>
 364
 365       <varlistentry id="libpanelw">
 366         <term><filename class="libraryfile">libpanelw</filename></term>
 367         <listitem>
 368           <para>Contains functions to implement panels</para>
 369           <indexterm zone="ch-system-ncurses libpanelw">
 370             <primary sortas="c-libpanelw">libpanelw</primary>
 371           </indexterm>
 372         </listitem>
 373       </varlistentry>
 374
 375     </variablelist>
 376
 377   </sect2>
 378
 379 </sect1>