Using Thread-Safe NCURSES with Static Linking¶

• Using Thread-Safe NCURSES with Static Linking
  • Introduction
  • How it Works
  • Building Process
    • Prerequisites
    • Enable Source Package Downloads
    • Scripted Patching
    • Manual Patching Process
    • Configure the System to Use a Custom NCURSES
    • Configure the System to Use PTHREADS Enable Feature
    • Build FWD

Introduction¶

In Linux/UNIX, the FWD native library libp2j.so depends upon a terminal functions library called NCURSES. The ChUI support implements multiple threads. The NCURSES library can be recompiled with threading support enabled. Starting in FWD v4 revision YYY, the libp2j.so library can be statically linked to the rebuilt NCURSES.

Use this approach if at all possible.

For details on the old approaches see Patching NCURSES and Patching NCURSES Using Static Linking.

How it Works¶

The NCURSES package has internal pragmas USE_PTHREADS_EINTR and USE_PTHREADS. When enabled, the code of the NCURSES has its logic protected by conditional compilation. This logic introduces and uses the mutexes objects to serialize access to I/O devices between accesses that happen across threads that call different input and output functions of the library. The standard NCURSES build included in Linux distributions usually have this feature disabled. This means by default the NCURSES library is not thread safe. Without threading enabled, the patched version of the library is required.

To enable the threading support, add the following options while rebuilding NCURSES: --with-pthread --enable-pthreads-eintr. This initializes the mutexes and makes the library's I/O mutex protected. Meaning only one thread will be able to do screen refresh in given moment. This allows elimination of the NCURSES patching.

Once recompiled, the multi-threaded version of the NCURSES library has a t suffix at the end of the library name. Linking with it statically uses the libncursest.a link library instead regular libncurses.a.

The version of NCURSES that is rebuilt can be one that is only used for building FWD. The system-wide NCURSES does not need to be rebuilt. This embeds the specially built NCURSES library inside libp2j.so so that the correct version of the functions will always be available.

In this approach the NCURSES package is building from sources on the local system and the produced libraries can be stored within the same account as the developer has for building FWD. This avoids requiring administrative rights (e.g. sudo or root access).

Since trunk revision 15728 it is possible to use this approach. It only works in NCURSES 5.7+ releases when internal mutual exclusion semaphores allow the screen synchronization to be consistent without additional patches from FWD.

Building Process¶

Prerequisites¶

Ensure that dpkg-dev package is installed on the system. The dpkg-dev package provides the development tools (including dpkg-source) required to unpack and build source packages.

sudo apt-get install dpkg-dev

Enable Source Package Downloads¶

It is important that apt has access to the source code repositories.

Run cat /etc/apt/sources.list | grep deb-src to see the status of the source repositories. Check if all of the entries are commented out (with a # character at the beginning of the line. If you see something like this:

# deb-src http://us.archive.ubuntu.com/ubuntu/ xenial main restricted
# deb-src http://us.archive.ubuntu.com/ubuntu/ xenial-updates main restricted
# deb-src http://us.archive.ubuntu.com/ubuntu/ xenial universe
# deb-src http://us.archive.ubuntu.com/ubuntu/ xenial-updates universe
# deb-src http://us.archive.ubuntu.com/ubuntu/ xenial multiverse
# deb-src http://us.archive.ubuntu.com/ubuntu/ xenial-updates multiverse
# deb-src http://security.ubuntu.com/ubuntu xenial-security main restricted
# deb-src http://security.ubuntu.com/ubuntu xenial-security universe
# deb-src http://security.ubuntu.com/ubuntu xenial-security multiverse

Then you should remove the comment character, leaving behind the rest of the line.

Before changing the file, you can back it up using this command:

sudo cp /etc/apt/sources.list /etc/apt/sources.list.orig

And here is a command to make all the replacements for you:

sudo sed --in-place 's/# deb-src/deb-src/' /etc/apt/sources.list

After this, ensure the repositories are loaded using this command:

sudo apt-get update

Scripted Patching¶

To automatically integrate the thread-safe NCURSES it is convenient to use single script (written for Ubuntu 22.04 LTS): setup_ncurses6x.sh. Just put it into a new directory for thread-safe libraries and execute.

The possible options:

Usage: ./setup_ncurses6x.sh [-p<path>] [-fsad]
Where:
p     = Use specific path instead of current directory
f     = Use patched NCURSES version, thread-safe is default
s     = Set system-wide environment instead of just current user
a     = Force setup of /etc/apt/sources.list and restore when done (requires sudo)
d     = Dry run. Just show commands.

The -f option forces using patched NCURSES. By default the thread-save version is building.

Otherwise the manual setup process is described in a sections below.

Manual Patching Process¶

This assumes the directory ~/projects/ncurses_static exists on local system.

Get the NCURSES Source Code¶

cd ~/projects/ncurses_static
apt-get source ncurses

Build the Thread-safe NCURSES¶

./configure --with-termlib CFLAGS='-fPIC -O2' --with-abi-version=6 --with-pthread --enable-pthreads-eintr
make

The -fPIC option is mandatory. Otherwise the FWD will not be statically linked with object code produced. The options --with-pthread --enable-pthreads-eintr are also mandatory, they inits internal syncronization feature for NCURSES.

After building completed the link to the ncurses.h should be created to make the FWD new build:

cd include
ln -s curses.h ncurses.h
cd ..

Configure the System to Use a Custom NCURSES¶

Before FWD can be successfully built, it is required to configure the location to search for the static libraries to the gcc linker. This can be done by defining the bash shell variable NCURSES_FWD_STATIC and exporting it for all subsequent commands.

To have this always available in your shell, add the following commands to the .bashrc session config file:

export NCURSES_FWD_STATIC="custom/path/to/patched/root/directory" 

The custom/path/to/patched/root/directory should be adjusted with current location of the patched NCURSES root directory. In our example it is: ~/projects/ncurses_static/ncurses-6.1

Configure the System to Use PTHREADS Enable Feature¶

This is very important step to instruct FWD to use thread-safe version of the NCURSES calls.

To properly build the FWD that leverages the ability to get rid of NCURSES patching the following system variable must be defined in .bashrc:

export NCURSES_FWD_PTHREADS=yes

Build FWD¶

Then open new terminal window and run FWD build as usual.

As an alternative to defining NCURSES_FWD_STATIC and NCURSES_FWD_PTHREADS in .bashrc, you can just use an "inline configuration" approach:

export NCURSES_FWD_STATIC="custom/path/to/patched/root/directory"; export NCURSES_FWD_PTHREADS=yes; <command_to_build_fwd>

---

© 2023-2025 Golden Code Development Corporation. ALL RIGHTS RESERVED.