source: chapter08/ncurses.xml@ d282f88

12.1 12.1-rc1 12.2 12.2-rc1 multilib trunk xry111/arm64 xry111/clfs-ng xry111/loongarch xry111/loongarch-12.1 xry111/loongarch-12.2 xry111/mips64el xry111/multilib xry111/update-glibc
Last change on this file since d282f88 was d282f88, checked in by Xi Ruoyao <xry111@…>, 8 months ago

ncurses: Modify the header to always use the ABI of ncursesw

instead of the 8-bit ncurses.

We don't provide the 8-bit ncurses library and we are "faking" it using
ncursesw. Thus innocent package may be compiled with the 8-bit ABI
(because it does not know what we are doing and so it does not use
the "expected" preprocessor definitions to enable the wide ABI) but
linked against ncursesw, causing a potential ABI mismatch.
  • Property mode set to 100644
File size: 14.7 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
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-fin-sbu;</seg>
35 <seg>&ncurses-fin-du;</seg>
36 </seglistitem>
37 </segmentedlist>
38
39 </sect2>
40
41 <sect2 role="installation">
42 <title>Installation of Ncurses</title>
43
44 <para>Prepare Ncurses for compilation:</para>
45
46<screen><userinput remap="configure">./configure --prefix=/usr \
47 --mandir=/usr/share/man \
48 --with-shared \
49 --without-debug \
50 --without-normal \
51 --with-cxx-shared \
52 --enable-pc-files \
53 --enable-widec \
54 --with-pkg-config-libdir=/usr/lib/pkgconfig</userinput></screen>
55
56 <variablelist>
57 <title>The meaning of the new configure options:</title>
58
59 <varlistentry>
60 <term><parameter>--with-shared</parameter></term>
61 <listitem>
62 <para>This makes Ncurses build and install shared C libraries.</para>
63 </listitem>
64 </varlistentry>
65
66 <varlistentry>
67 <term><parameter>--without-normal</parameter></term>
68 <listitem>
69 <para>This prevents Ncurses building and installing static C
70 libraries.</para>
71 </listitem>
72 </varlistentry>
73
74 <varlistentry>
75 <term><parameter>--without-debug</parameter></term>
76 <listitem>
77 <para>This prevents Ncurses building and installing debug
78 libraries.</para>
79 </listitem>
80 </varlistentry>
81
82 <varlistentry>
83 <term><parameter>--with-cxx-shared</parameter></term>
84 <listitem>
85 <para>This makes Ncurses build and install shared C++ bindings. It
86 also prevents it building and installing static C++ bindings.</para>
87 </listitem>
88 </varlistentry>
89
90 <varlistentry>
91 <term><parameter>--enable-pc-files</parameter></term>
92 <listitem>
93 <para>This switch generates and installs .pc files for pkg-config.
94 </para>
95 </listitem>
96 </varlistentry>
97
98 <varlistentry>
99 <term><parameter>--enable-widec</parameter></term>
100 <listitem>
101 <para>This switch causes wide-character libraries (e.g., <filename
102 class="libraryfile">libncursesw.so.&ncurses-version;</filename>)
103 to be built instead of normal ones (e.g., <filename
104 class="libraryfile">libncurses.so.&ncurses-version;</filename>).
105 These wide-character libraries are usable in both multibyte and
106 traditional 8-bit locales, while normal libraries work properly
107 only in 8-bit locales. Wide-character and normal libraries are
108 source-compatible, but not binary-compatible.</para>
109 </listitem>
110 </varlistentry>
111
112 </variablelist>
113
114 <para>Compile the package:</para>
115
116<screen><userinput remap="make">make</userinput></screen>
117
118 <para>This package has a test suite, but it can only be run after the
119 package has been installed. The tests reside in the
120 <filename class="directory">test/</filename> directory. See the
121 <filename>README</filename> file in that directory for further details.
122 </para>
123
124 <!-- To editors: crash of shell process was very rare but really
125 observed. We can't simply remove /usr/lib/libncursesw.so.6.x like
126 how we handle libmozjs-xx.so in BLFS because bash needs it, and
127 make will spawn new shell processes during "make install". -->
128
129 <para>The installation of this package will overwrite
130 <filename class="libraryfile">libncursesw.so.&ncurses-version;</filename>
131 in-place. It may crash the shell process which is using code and data
132 from the library file. Install the package with
133 <literal>DESTDIR</literal>, and replace the library file correctly using
134 <command>install</command> command (the header
135 <filename>curses.h</filename> is also edited to ensure the
136 wide-character ABI to be used as what we've done in
137 <xref linkend='ch-tools-ncurses'/>):</para>
138
139<screen><userinput remap="install">make DESTDIR=$PWD/dest install
140install -vm755 dest/usr/lib/libncursesw.so.&ncurses-version; /usr/lib
141rm -v dest/usr/lib/libncursesw.so.&ncurses-version;
142sed -e 's/^#if.*XOPEN.*$/#if 1/' \
143 -i dest/usr/include/curses.h
144cp -av dest/* /</userinput></screen>
145
146 <para>Many applications still expect the linker to be able to find
147 non-wide-character Ncurses libraries. Trick such applications into linking with
148 wide-character libraries by means of symlinks and linker scripts:</para>
149
150<screen><userinput remap="install">for lib in ncurses form panel menu ; do
151 rm -vf /usr/lib/lib${lib}.so
152 echo "INPUT(-l${lib}w)" &gt; /usr/lib/lib${lib}.so
153 ln -sfv ${lib}w.pc /usr/lib/pkgconfig/${lib}.pc
154done</userinput></screen>
155
156 <para>Finally, make sure that old applications that look for
157 <filename class="libraryfile">-lcurses</filename> at build time are still
158 buildable:</para>
159
160<screen><userinput remap="install">rm -vf /usr/lib/libcursesw.so
161echo "INPUT(-lncursesw)" &gt; /usr/lib/libcursesw.so
162ln -sfv libncurses.so /usr/lib/libcurses.so</userinput></screen>
163
164 <para>If desired, install the Ncurses documentation:</para>
165
166<screen><userinput remap="install">cp -v -R doc -T /usr/share/doc/ncurses-&ncurses-version;</userinput></screen>
167
168 <note>
169
170 <para>The instructions above don't create non-wide-character Ncurses
171 libraries since no package installed by compiling from sources would link
172 against them at runtime. However, the only known binary-only
173 applications that link against non-wide-character Ncurses libraries
174 require version 5. If you must have such libraries because of some binary-only
175 application or to be compliant with LSB, build the package again with the
176 following commands:</para>
177
178<screen role="nodump"><userinput>make distclean
179./configure --prefix=/usr \
180 --with-shared \
181 --without-normal \
182 --without-debug \
183 --without-cxx-binding \
184 --with-abi-version=5
185make sources libs
186cp -av lib/lib*.so.5* /usr/lib</userinput></screen>
187 </note>
188
189 </sect2>
190
191 <sect2 id="contents-ncurses" role="content">
192 <title>Contents of Ncurses</title>
193
194 <segmentedlist>
195 <segtitle>Installed programs</segtitle>
196 <segtitle>Installed libraries</segtitle>
197 <segtitle>Installed directories</segtitle>
198
199 <seglistitem>
200 <seg>
201 captoinfo (link to tic),
202 clear,
203 infocmp,
204 infotocap (link to tic),
205 ncursesw6-config,
206 reset (link to tset),
207 tabs,
208 tic,
209 toe,
210 tput, and
211 tset
212 </seg>
213 <seg>
214 libcursesw.so (symlink and linker script to libncursesw.so),
215 libformw.so,
216 libmenuw.so,
217 libncursesw.so,
218 libncurses++w.so,
219 libpanelw.so, and their non-wide-character counterparts without "w"
220 in the library names.</seg>
221 <seg>
222 /usr/share/tabset,
223 /usr/share/terminfo, and
224 /usr/share/doc/ncurses-&ncurses-version;
225 </seg>
226 </seglistitem>
227 </segmentedlist>
228
229 <variablelist>
230 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
231 <?dbfo list-presentation="list"?>
232 <?dbhtml list-presentation="table"?>
233
234 <varlistentry id="captoinfo">
235 <term><command>captoinfo</command></term>
236 <listitem>
237 <para>Converts a termcap description into a terminfo description</para>
238 <indexterm zone="ch-system-ncurses captoinfo">
239 <primary sortas="b-captoinfo">captoinfo</primary>
240 </indexterm>
241 </listitem>
242 </varlistentry>
243
244 <varlistentry id="clear">
245 <term><command>clear</command></term>
246 <listitem>
247 <para>Clears the screen, if possible</para>
248 <indexterm zone="ch-system-ncurses clear">
249 <primary sortas="b-clear">clear</primary>
250 </indexterm>
251 </listitem>
252 </varlistentry>
253
254 <varlistentry id="infocmp">
255 <term><command>infocmp</command></term>
256 <listitem>
257 <para>Compares or prints out terminfo descriptions</para>
258 <indexterm zone="ch-system-ncurses infocmp">
259 <primary sortas="b-infocmp">infocmp</primary>
260 </indexterm>
261 </listitem>
262 </varlistentry>
263
264 <varlistentry id="infotocap">
265 <term><command>infotocap</command></term>
266 <listitem>
267 <para>Converts a terminfo description into a termcap description</para>
268 <indexterm zone="ch-system-ncurses infotocap">
269 <primary sortas="b-infotocap">infotocap</primary>
270 </indexterm>
271 </listitem>
272 </varlistentry>
273
274 <varlistentry id="ncursesw6-config">
275 <term><command>ncursesw6-config</command></term>
276 <listitem>
277 <para>Provides configuration information for ncurses</para>
278 <indexterm zone="ch-system-ncurses ncursesw6-config">
279 <primary sortas="b-ncursesw6-config">ncursesw6-config</primary>
280 </indexterm>
281 </listitem>
282 </varlistentry>
283
284 <varlistentry id="reset">
285 <term><command>reset</command></term>
286 <listitem>
287 <para>Reinitializes a terminal to its default values</para>
288 <indexterm zone="ch-system-ncurses reset">
289 <primary sortas="b-reset">reset</primary>
290 </indexterm>
291 </listitem>
292 </varlistentry>
293
294 <varlistentry id="tabs">
295 <term><command>tabs</command></term>
296 <listitem>
297 <para>Clears and sets tab stops on a terminal</para>
298 <indexterm zone="ch-system-ncurses tabs">
299 <primary sortas="b-tabs">tabs</primary>
300 </indexterm>
301 </listitem>
302 </varlistentry>
303
304 <varlistentry id="tic">
305 <term><command>tic</command></term>
306 <listitem>
307 <para>The terminfo entry-description compiler that translates a
308 terminfo file from source format into the binary format needed for the
309 ncurses library routines [A terminfo file contains information on the
310 capabilities of a certain terminal.]</para>
311 <indexterm zone="ch-system-ncurses tic">
312 <primary sortas="b-tic">tic</primary>
313 </indexterm>
314 </listitem>
315 </varlistentry>
316
317 <varlistentry id="toe">
318 <term><command>toe</command></term>
319 <listitem>
320 <para>Lists all available terminal types, giving the primary name and
321 description for each</para>
322 <indexterm zone="ch-system-ncurses toe">
323 <primary sortas="b-toe">toe</primary>
324 </indexterm>
325 </listitem>
326 </varlistentry>
327
328 <varlistentry id="tput">
329 <term><command>tput</command></term>
330 <listitem>
331 <para>Makes the values of terminal-dependent capabilities available to
332 the shell; it can also be used to reset or initialize a terminal or
333 report its long name</para>
334 <indexterm zone="ch-system-ncurses tput">
335 <primary sortas="b-tput">tput</primary>
336 </indexterm>
337 </listitem>
338 </varlistentry>
339
340 <varlistentry id="tset">
341 <term><command>tset</command></term>
342 <listitem>
343 <para>Can be used to initialize terminals</para>
344 <indexterm zone="ch-system-ncurses tset">
345 <primary sortas="b-tset">tset</primary>
346 </indexterm>
347 </listitem>
348 </varlistentry>
349
350 <varlistentry id="libcursesw">
351 <term><filename class="libraryfile">libcursesw</filename></term>
352 <listitem>
353 <para>A link to <filename>libncursesw</filename></para>
354 <indexterm zone="ch-system-ncurses libcursesw">
355 <primary sortas="c-libcursesw">libcursesw</primary>
356 </indexterm>
357 </listitem>
358 </varlistentry>
359
360 <varlistentry id="libncursesw">
361 <term><filename class="libraryfile">libncursesw</filename></term>
362 <listitem>
363 <para>Contains functions to display text in many complex ways on a
364 terminal screen; a good example of the use of these functions is the
365 menu displayed during the kernel's <command>make
366 menuconfig</command></para>
367 <indexterm zone="ch-system-ncurses libncursesw">
368 <primary sortas="c-libncursesw">libncursesw</primary>
369 </indexterm>
370 </listitem>
371 </varlistentry>
372
373 <varlistentry id="libncurses__w">
374 <term><filename class="libraryfile">libncurses++w</filename></term>
375 <listitem>
376 <para>Contains C++ binding for other libraries in this package</para>
377 <indexterm zone="ch-system-ncurses libncurses__w">
378 <primary sortas="c-libncurses++w">libncurses++w</primary>
379 </indexterm>
380 </listitem>
381 </varlistentry>
382
383 <varlistentry id="libformw">
384 <term><filename class="libraryfile">libformw</filename></term>
385 <listitem>
386 <para>Contains functions to implement forms</para>
387 <indexterm zone="ch-system-ncurses libformw">
388 <primary sortas="c-libformw">libformw</primary>
389 </indexterm>
390 </listitem>
391 </varlistentry>
392
393 <varlistentry id="libmenuw">
394 <term><filename class="libraryfile">libmenuw</filename></term>
395 <listitem>
396 <para>Contains functions to implement menus</para>
397 <indexterm zone="ch-system-ncurses libmenuw">
398 <primary sortas="c-libmenuw">libmenuw</primary>
399 </indexterm>
400 </listitem>
401 </varlistentry>
402
403 <varlistentry id="libpanelw">
404 <term><filename class="libraryfile">libpanelw</filename></term>
405 <listitem>
406 <para>Contains functions to implement panels</para>
407 <indexterm zone="ch-system-ncurses libpanelw">
408 <primary sortas="c-libpanelw">libpanelw</primary>
409 </indexterm>
410 </listitem>
411 </varlistentry>
412
413 </variablelist>
414
415 </sect2>
416
417</sect1>
Note: See TracBrowser for help on using the repository browser.