BOOK/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
 143       <para>The instructions above don't create non-wide-character Ncurses
 144       libraries since no package installed by compiling from sources would link
 145       against them at runtime. However, the only known binary-only
 146       applications that link against non-wide-character Ncurses libraries
 147       require version 5.  If you must have such libraries because of some binary-only
 148       application or to be compliant with LSB, build the package again with the
 149       following commands:</para>
 150
 151 <screen role="nodump"><userinput>make distclean
 152 ./configure --prefix=/usr    \
 153             --with-shared    \
 154             --without-normal \
 155             --without-debug  \
 156             --without-cxx-binding \
 157             --with-abi-version=5
 158 make sources libs
 159 cp -av lib/lib*.so.5* /usr/lib</userinput></screen>
 160     </note>
 161
 162   </sect2>
 163
 164   <sect2 id="contents-ncurses" role="content">
 165     <title>Contents of Ncurses</title>
 166
 167     <segmentedlist>
 168       <segtitle>Installed programs</segtitle>
 169       <segtitle>Installed libraries</segtitle>
 170       <segtitle>Installed directories</segtitle>
 171
 172       <seglistitem>
 173         <seg>
 174            captoinfo (link to tic),
 175            clear,
 176            infocmp,
 177            infotocap (link to tic),
 178            ncursesw6-config,
 179            reset (link to tset),
 180            tabs,
 181            tic,
 182            toe,
 183            tput, and
 184            tset
 185         </seg>
 186         <seg>
 187            libcursesw.so (symlink and linker script to libncursesw.so),
 188            libformw.so,
 189            libmenuw.so,
 190            libncursesw.so,
 191            libncurses++w.a,
 192            libpanelw.so, and their non-wide-character counterparts without "w"
 193               in the library names.</seg>
 194         <seg>
 195            /usr/share/tabset,
 196            /usr/share/terminfo, and
 197            /usr/share/doc/ncurses-&ncurses-version;
 198         </seg>
 199       </seglistitem>
 200     </segmentedlist>
 201
 202     <variablelist>
 203       <bridgehead renderas="sect3">Short Descriptions</bridgehead>
 204       <?dbfo list-presentation="list"?>
 205       <?dbhtml list-presentation="table"?>
 206
 207       <varlistentry id="captoinfo">
 208         <term><command>captoinfo</command></term>
 209         <listitem>
 210           <para>Converts a termcap description into a terminfo description</para>
 211           <indexterm zone="ch-system-ncurses captoinfo">
 212             <primary sortas="b-captoinfo">captoinfo</primary>
 213           </indexterm>
 214         </listitem>
 215       </varlistentry>
 216
 217       <varlistentry id="clear">
 218         <term><command>clear</command></term>
 219         <listitem>
 220           <para>Clears the screen, if possible</para>
 221           <indexterm zone="ch-system-ncurses clear">
 222             <primary sortas="b-clear">clear</primary>
 223           </indexterm>
 224         </listitem>
 225       </varlistentry>
 226
 227       <varlistentry id="infocmp">
 228         <term><command>infocmp</command></term>
 229         <listitem>
 230           <para>Compares or prints out terminfo descriptions</para>
 231           <indexterm zone="ch-system-ncurses infocmp">
 232             <primary sortas="b-infocmp">infocmp</primary>
 233           </indexterm>
 234         </listitem>
 235       </varlistentry>
 236
 237       <varlistentry id="infotocap">
 238         <term><command>infotocap</command></term>
 239         <listitem>
 240           <para>Converts a terminfo description into a termcap description</para>
 241           <indexterm zone="ch-system-ncurses infotocap">
 242             <primary sortas="b-infotocap">infotocap</primary>
 243           </indexterm>
 244         </listitem>
 245       </varlistentry>
 246
 247       <varlistentry id="ncursesw6-config">
 248         <term><command>ncursesw6-config</command></term>
 249         <listitem>
 250           <para>Provides configuration information for ncurses</para>
 251           <indexterm zone="ch-system-ncurses ncursesw6-config">
 252             <primary sortas="b-ncursesw6-config">ncursesw6-config</primary>
 253           </indexterm>
 254         </listitem>
 255       </varlistentry>
 256
 257       <varlistentry id="reset">
 258         <term><command>reset</command></term>
 259         <listitem>
 260           <para>Reinitializes a terminal to its default values</para>
 261           <indexterm zone="ch-system-ncurses reset">
 262             <primary sortas="b-reset">reset</primary>
 263           </indexterm>
 264         </listitem>
 265       </varlistentry>
 266
 267       <varlistentry id="tabs">
 268         <term><command>tabs</command></term>
 269         <listitem>
 270           <para>Clears and sets tab stops on a terminal</para>
 271           <indexterm zone="ch-system-ncurses tabs">
 272             <primary sortas="b-tabs">tabs</primary>
 273           </indexterm>
 274         </listitem>
 275       </varlistentry>
 276
 277       <varlistentry id="tic">
 278         <term><command>tic</command></term>
 279         <listitem>
 280           <para>The terminfo entry-description compiler that translates a
 281           terminfo file from source format into the binary format needed for the
 282           ncurses library routines [A terminfo file contains information on the
 283           capabilities of a certain terminal.]</para>
 284           <indexterm zone="ch-system-ncurses tic">
 285             <primary sortas="b-tic">tic</primary>
 286           </indexterm>
 287         </listitem>
 288       </varlistentry>
 289
 290       <varlistentry id="toe">
 291         <term><command>toe</command></term>
 292         <listitem>
 293           <para>Lists all available terminal types, giving the primary name and
 294           description for each</para>
 295           <indexterm zone="ch-system-ncurses toe">
 296             <primary sortas="b-toe">toe</primary>
 297           </indexterm>
 298         </listitem>
 299       </varlistentry>
 300
 301       <varlistentry id="tput">
 302         <term><command>tput</command></term>
 303         <listitem>
 304           <para>Makes the values of terminal-dependent capabilities available to
 305           the shell; it can also be used to reset or initialize a terminal or
 306           report its long name</para>
 307           <indexterm zone="ch-system-ncurses tput">
 308             <primary sortas="b-tput">tput</primary>
 309           </indexterm>
 310         </listitem>
 311       </varlistentry>
 312
 313       <varlistentry id="tset">
 314         <term><command>tset</command></term>
 315         <listitem>
 316           <para>Can be used to initialize terminals</para>
 317           <indexterm zone="ch-system-ncurses tset">
 318             <primary sortas="b-tset">tset</primary>
 319           </indexterm>
 320         </listitem>
 321       </varlistentry>
 322
 323       <varlistentry id="libcursesw">
 324         <term><filename class="libraryfile">libcursesw</filename></term>
 325         <listitem>
 326           <para>A link to <filename>libncursesw</filename></para>
 327           <indexterm zone="ch-system-ncurses libcursesw">
 328             <primary sortas="c-libcursesw">libcursesw</primary>
 329           </indexterm>
 330         </listitem>
 331       </varlistentry>
 332
 333       <varlistentry id="libncursesw">
 334         <term><filename class="libraryfile">libncursesw</filename></term>
 335         <listitem>
 336           <para>Contains functions to display text in many complex ways on a
 337           terminal screen; a good example of the use of these functions is the
 338           menu displayed during the kernel's <command>make
 339           menuconfig</command></para>
 340           <indexterm zone="ch-system-ncurses libncursesw">
 341             <primary sortas="c-libncursesw">libncursesw</primary>
 342           </indexterm>
 343         </listitem>
 344       </varlistentry>
 345
 346       <varlistentry id="libformw">
 347         <term><filename class="libraryfile">libformw</filename></term>
 348         <listitem>
 349           <para>Contains functions to implement forms</para>
 350           <indexterm zone="ch-system-ncurses libformw">
 351             <primary sortas="c-libformw">libformw</primary>
 352           </indexterm>
 353         </listitem>
 354       </varlistentry>
 355
 356       <varlistentry id="libmenuw">
 357         <term><filename class="libraryfile">libmenuw</filename></term>
 358         <listitem>
 359           <para>Contains functions to implement menus</para>
 360           <indexterm zone="ch-system-ncurses libmenuw">
 361             <primary sortas="c-libmenuw">libmenuw</primary>
 362           </indexterm>
 363         </listitem>
 364       </varlistentry>
 365
 366       <varlistentry id="libpanelw">
 367         <term><filename class="libraryfile">libpanelw</filename></term>
 368         <listitem>
 369           <para>Contains functions to implement panels</para>
 370           <indexterm zone="ch-system-ncurses libpanelw">
 371             <primary sortas="c-libpanelw">libpanelw</primary>
 372           </indexterm>
 373         </listitem>
 374       </varlistentry>
 375
 376     </variablelist>
 377
 378   </sect2>
 379
 380 </sect1>