Build a Small ncurses Program with ncurses6-config

You will finish with a repeatable compile and link command for a small ncurses program, using the flags supplied by the installed ncurses6-config. The examples were checked against the Debian package libncurses-dev:amd64, version 6.4+20240113-1ubuntu2.2, whose packaged helper reports ncurses 6.4.20240113.

Allow about fifteen minutes. You need a shell, a C compiler and the development package. This guide only creates a temporary source file under /tmp; it does not install packages, modify system libraries or require elevated privileges.

1. Select the helper you actually intend to use

Start by resolving the command and checking its package. This is an ordinary read-only check:

$ command -v ncurses6-config
/usr/bin/ncurses6-config
$ dpkg-query -W -f='${Package} ${Version}\n' libncurses-dev:amd64
libncurses-dev:amd64 6.4+20240113-1ubuntu2.2
$ /usr/bin/ncurses6-config --version
6.4.20240113

Use the absolute path in the remaining examples when you are diagnosing a build. A different executable earlier in PATH can report different flags and a different ncurses release. On this machine, an unrelated Homebrew installation also provides a command with the same name, so trusting an unexamined PATH would be a real source of confusion.

Checkpoint: if command -v does not show the helper you expect, stop and inspect command -v gcc, echo "$PATH" and any environment-module or package-manager setup before compiling.

2. Ask for the compiler and linker flags

The two options needed for a normal C build are --cflags and --libs:

$ /usr/bin/ncurses6-config --cflags
-D_DEFAULT_SOURCE -D_XOPEN_SOURCE=600
$ /usr/bin/ncurses6-config --libs
-lncurses -ltinfo

--cflags prints compiler flags. --libs prints the libraries needed at link time. Keep them in their respective positions: compiler flags and source files come before the output option, while library flags normally come at the end. The helper's output is configuration data, not a command that should be executed by itself.

The installed helper also reports paths and version information. These are useful for diagnosing a mismatched development installation:

$ /usr/bin/ncurses6-config --prefix
/usr
$ /usr/bin/ncurses6-config --includedir
$ /usr/bin/ncurses6-config --libdir
$ /usr/bin/ncurses6-config --abi-version
6
$ /usr/bin/ncurses6-config --mouse-version
2

The blank --includedir and --libdir lines are valid output here. They do not mean that the package has no headers or libraries; they mean no extra directory flag is needed for this installation. Do not replace blank output with a guessed -I or -L option.

3. Create a harmless test program

Write a small program that initialises ncurses, prints one line, waits for a key and restores the terminal before exiting:

$ test_dir=$(mktemp -d /tmp/ncurses6-config.XXXXXX)
$ cat > "$test_dir/hello.c" <<'EOF'
#include <ncurses.h>

int main(void)
{
    initscr();
    printw("ncurses build works");
    refresh();
    getch();
    endwin();
    return 0;
}
EOF

This command changes only the newly created temporary directory. Do not use a path containing valuable files for this test. If you abandon the test, remove that one directory with rm -rf -- "$test_dir"; check the variable first with printf '%s\n' "$test_dir" so that a failed assignment cannot turn the command into a broad deletion.

4. Compile and link with the reported values

Capture the two outputs as shell variables and pass them to the compiler. This keeps the configuration source in one place:

$ cflags=$(/usr/bin/ncurses6-config --cflags)
$ libs=$(/usr/bin/ncurses6-config --libs)
$ gcc $cflags "$test_dir/hello.c" -o "$test_dir/hello" $libs
$ printf 'exit status: %s\n' "$?"
exit status: 0

There is no need for sudo. If the compile fails with ncurses.h: No such file or directory, check that the development package is installed and that the helper and compiler belong to the same environment. If the link fails with an unresolved ncurses symbol, inspect the exact --libs output and keep those libraries after the source and object files.

Shell word splitting is intentional for these outputs because they are compiler arguments generated by the trusted local helper. Do not use this pattern with untrusted text. For a build system, record the command or use the project's supported pkg-config integration when its build instructions provide one.

5. Run the result in a real terminal

Run the binary from an interactive terminal, not from a redirected log or a background service:

$ "$test_dir/hello"
ncurses build works

Press a key when the message appears. getch() then returns, endwin() restores the terminal and the program exits. The visible screen may be cleared or redrawn by ncurses, so the displayed line is a simple smoke test rather than a measurement of terminal capability.

Checkpoint: verify the binary's exit status immediately after it returns:

$ printf 'program status: %s\n' "$?"
program status: 0

If a test is interrupted before endwin() runs, the terminal can appear stuck in an unusual mode. Type reset and press Enter to ask the terminal to recover its display settings. That affects the terminal session only; it does not alter ncurses or the installed package.

6. Check metadata when a build does not match expectations

The helper can report the directories used by the installation, including --bindir, --datadir, --mandir and --terminfo. It can also report --terminfo-dirs, the supplemental search path for the terminal information database:

$ /usr/bin/ncurses6-config --terminfo
/etc/terminfo
$ /usr/bin/ncurses6-config --terminfo-dirs
/etc/terminfo:/lib/terminfo:/usr/share/terminfo
$ /usr/bin/ncurses6-config --help
Usage: ncurses6-config [options]

These options describe the build and its data locations. They do not change the terminal database, install a missing entry or switch the active terminal type. If a program reports an unknown terminal, inspect printf '%s\n' "$TERM" and the terminfo installation separately. Do not solve a runtime data problem by changing compiler or linker flags at random.

The manpage says that --help and --version take precedence over other options. Use one option at a time in scripts so that the command's purpose is obvious, and capture its status if a failed configuration query should stop the build.