source: chapter08/ncurses.xml@ 943f225

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

ncurses: Use symlinks instead of linker scripts

The effect will not change, but with symlinks ld can save some time
invoking open(), read(), etc. syscalls and parsing the linker scripts.

Note that I've also removed "libcursesw" symlink because this library
has never existed. Instead libcurses.so is created as a symlink
direct to libncursesw.so.
  • 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
148 linking with wide-character libraries by means of symlinks
149 (note that the <filename class='extension'>.so</filename> links are
150 only safe with <filename>curses.h</filename> edited to always use the
151 wide-character ABI):</para>
152
153<screen><userinput remap="install">for lib in ncurses form panel menu ; do
154 ln -sfv lib${lib}w.so /usr/lib/lib${lib}.so
155 ln -sfv ${lib}w.pc /usr/lib/pkgconfig/${lib}.pc
156done</userinput></screen>
157
158 <para>Finally, make sure that old applications that look for
159 <filename class="libraryfile">-lcurses</filename> at build time are still
160 buildable:</para>
161
162<screen><userinput remap="install">ln -sfv libncursesw.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 libcurses.so (symlink),
215 libform.so (symlink),
216 libformw.so,
217 libmenu.so (symlink),
218 libmenuw.so,
219 libncurses.so (symlink),
220 libncursesw.so,
221 libncurses++w.so,
222 libpanel.so (symlink),
223 and libpanelw.so,
224 </seg>
225 <seg>
226 /usr/share/tabset,
227 /usr/share/terminfo, and
228 /usr/share/doc/ncurses-&ncurses-version;
229 </seg>
230 </seglistitem>
231 </segmentedlist>
232
233 <variablelist>
234 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
235 <?dbfo list-presentation="list"?>
236 <?dbhtml list-presentation="table"?>
237
238 <varlistentry id="captoinfo">
239 <term><command>captoinfo</command></term>
240 <listitem>
241 <para>Converts a termcap description into a terminfo description</para>
242 <indexterm zone="ch-system-ncurses captoinfo">
243 <primary sortas="b-captoinfo">captoinfo</primary>
244 </indexterm>
245 </listitem>
246 </varlistentry>
247
248 <varlistentry id="clear">
249 <term><command>clear</command></term>
250 <listitem>
251 <para>Clears the screen, if possible</para>
252 <indexterm zone="ch-system-ncurses clear">
253 <primary sortas="b-clear">clear</primary>
254 </indexterm>
255 </listitem>
256 </varlistentry>
257
258 <varlistentry id="infocmp">
259 <term><command>infocmp</command></term>
260 <listitem>
261 <para>Compares or prints out terminfo descriptions</para>
262 <indexterm zone="ch-system-ncurses infocmp">
263 <primary sortas="b-infocmp">infocmp</primary>
264 </indexterm>
265 </listitem>
266 </varlistentry>
267
268 <varlistentry id="infotocap">
269 <term><command>infotocap</command></term>
270 <listitem>
271 <para>Converts a terminfo description into a termcap description</para>
272 <indexterm zone="ch-system-ncurses infotocap">
273 <primary sortas="b-infotocap">infotocap</primary>
274 </indexterm>
275 </listitem>
276 </varlistentry>
277
278 <varlistentry id="ncursesw6-config">
279 <term><command>ncursesw6-config</command></term>
280 <listitem>
281 <para>Provides configuration information for ncurses</para>
282 <indexterm zone="ch-system-ncurses ncursesw6-config">
283 <primary sortas="b-ncursesw6-config">ncursesw6-config</primary>
284 </indexterm>
285 </listitem>
286 </varlistentry>
287
288 <varlistentry id="reset">
289 <term><command>reset</command></term>
290 <listitem>
291 <para>Reinitializes a terminal to its default values</para>
292 <indexterm zone="ch-system-ncurses reset">
293 <primary sortas="b-reset">reset</primary>
294 </indexterm>
295 </listitem>
296 </varlistentry>
297
298 <varlistentry id="tabs">
299 <term><command>tabs</command></term>
300 <listitem>
301 <para>Clears and sets tab stops on a terminal</para>
302 <indexterm zone="ch-system-ncurses tabs">
303 <primary sortas="b-tabs">tabs</primary>
304 </indexterm>
305 </listitem>
306 </varlistentry>
307
308 <varlistentry id="tic">
309 <term><command>tic</command></term>
310 <listitem>
311 <para>The terminfo entry-description compiler that translates a
312 terminfo file from source format into the binary format needed for the
313 ncurses library routines [A terminfo file contains information on the
314 capabilities of a certain terminal.]</para>
315 <indexterm zone="ch-system-ncurses tic">
316 <primary sortas="b-tic">tic</primary>
317 </indexterm>
318 </listitem>
319 </varlistentry>
320
321 <varlistentry id="toe">
322 <term><command>toe</command></term>
323 <listitem>
324 <para>Lists all available terminal types, giving the primary name and
325 description for each</para>
326 <indexterm zone="ch-system-ncurses toe">
327 <primary sortas="b-toe">toe</primary>
328 </indexterm>
329 </listitem>
330 </varlistentry>
331
332 <varlistentry id="tput">
333 <term><command>tput</command></term>
334 <listitem>
335 <para>Makes the values of terminal-dependent capabilities available to
336 the shell; it can also be used to reset or initialize a terminal or
337 report its long name</para>
338 <indexterm zone="ch-system-ncurses tput">
339 <primary sortas="b-tput">tput</primary>
340 </indexterm>
341 </listitem>
342 </varlistentry>
343
344 <varlistentry id="tset">
345 <term><command>tset</command></term>
346 <listitem>
347 <para>Can be used to initialize terminals</para>
348 <indexterm zone="ch-system-ncurses tset">
349 <primary sortas="b-tset">tset</primary>
350 </indexterm>
351 </listitem>
352 </varlistentry>
353
354 <varlistentry id="libcursesw">
355 <term><filename class="libraryfile">libcursesw</filename></term>
356 <listitem>
357 <para>A link to <filename>libncursesw</filename></para>
358 <indexterm zone="ch-system-ncurses libcursesw">
359 <primary sortas="c-libcursesw">libcursesw</primary>
360 </indexterm>
361 </listitem>
362 </varlistentry>
363
364 <varlistentry id="libncursesw">
365 <term><filename class="libraryfile">libncursesw</filename></term>
366 <listitem>
367 <para>Contains functions to display text in many complex ways on a
368 terminal screen; a good example of the use of these functions is the
369 menu displayed during the kernel's <command>make
370 menuconfig</command></para>
371 <indexterm zone="ch-system-ncurses libncursesw">
372 <primary sortas="c-libncursesw">libncursesw</primary>
373 </indexterm>
374 </listitem>
375 </varlistentry>
376
377 <varlistentry id="libncurses__w">
378 <term><filename class="libraryfile">libncurses++w</filename></term>
379 <listitem>
380 <para>Contains C++ binding for other libraries in this package</para>
381 <indexterm zone="ch-system-ncurses libncurses__w">
382 <primary sortas="c-libncurses++w">libncurses++w</primary>
383 </indexterm>
384 </listitem>
385 </varlistentry>
386
387 <varlistentry id="libformw">
388 <term><filename class="libraryfile">libformw</filename></term>
389 <listitem>
390 <para>Contains functions to implement forms</para>
391 <indexterm zone="ch-system-ncurses libformw">
392 <primary sortas="c-libformw">libformw</primary>
393 </indexterm>
394 </listitem>
395 </varlistentry>
396
397 <varlistentry id="libmenuw">
398 <term><filename class="libraryfile">libmenuw</filename></term>
399 <listitem>
400 <para>Contains functions to implement menus</para>
401 <indexterm zone="ch-system-ncurses libmenuw">
402 <primary sortas="c-libmenuw">libmenuw</primary>
403 </indexterm>
404 </listitem>
405 </varlistentry>
406
407 <varlistentry id="libpanelw">
408 <term><filename class="libraryfile">libpanelw</filename></term>
409 <listitem>
410 <para>Contains functions to implement panels</para>
411 <indexterm zone="ch-system-ncurses libpanelw">
412 <primary sortas="c-libpanelw">libpanelw</primary>
413 </indexterm>
414 </listitem>
415 </varlistentry>
416
417 </variablelist>
418
419 </sect2>
420
421</sect1>
Note: See TracBrowser for help on using the repository browser.