Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DRessedAlarm184/LWXGL/llms.txt

Use this file to discover all available pages before exploring further.

LWXGL ships as a single shared library, libLWXGL.so, built from one C++ translation unit (src/main.cc). The repository includes a minimal Makefile with two targets — build and install — that handle compilation and system-wide deployment. This page covers every step from installing build dependencies through verifying the installation, plus instructions for keeping libLWXGL.so local if you prefer not to install it system-wide.
Running graphical applications built with LWXGL requires a live X11 display server. Make sure the DISPLAY environment variable is set before launching your application (e.g. DISPLAY=:0 ./myapp). This is set automatically when you are logged into a graphical desktop session, but may be absent in SSH or headless environments.

​
Prerequisites

You need a C++ compiler, the Xlib development headers, and GNU Make. Debian/Ubuntu: 
sudo apt install build-essential libx11-dev
Fedora/RHEL: 
sudo dnf install gcc-c++ libX11-devel make
Confirm that g++ and make are available after installation: 
g++ --version
make --version

​
Building

1

Clone the repository

git clone https://github.com/DRessedAlarm184/LWXGL.git
cd LWXGL
2

Compile the shared library

make build
This runs the following command internally:
g++ -fPIC -shared -O2 -o libLWXGL.so src/main.cc -lX11 -fvisibility=hidden
Key flags explained:
FlagPurpose
-fPICEmit position-independent code, required for shared libraries loaded at arbitrary addresses.
-sharedProduce a shared object (.so) rather than an executable.
-O2Enable standard optimizations for release performance.
-lX11Link against the system Xlib shared library.
-fvisibility=hiddenHide all symbols by default; only functions marked with EXPORT in the source are exposed in the public ABI.
On success, libLWXGL.so is created in the repository root.

​
Installing

Once the library is built, install it system-wide so that any project on the machine can link against it without extra -L flags: 
sudo make install
This runs three commands: 
cp libLWXGL.so /usr/local/lib
cp src/libLWXGL.h /usr/local/include
ldconfig
  • libLWXGL.so is copied to /usr/local/lib, which is on the standard dynamic linker search path.
  • libLWXGL.h is copied to /usr/local/include, which is on the default compiler header search path.
  • ldconfig refreshes the linker cache so the new library is discoverable immediately.
After installation, any project can compile with just -lLWXGL: 
gcc -o myapp main.c -lLWXGL

​
Manual Installation

If you want to keep libLWXGL.so local to a project directory (no root privileges required), skip make install and pass the location explicitly when compiling your application. 
# Build the library as normal
make build

# Copy it next to your project, or use it in place
cp /path/to/LWXGL/libLWXGL.so .
cp /path/to/LWXGL/src/libLWXGL.h .

# Compile your app, pointing the linker at the current directory
# -Wl,-rpath,. embeds the current directory in the binary's runtime search path
gcc -o myapp main.c -I. -L. -lLWXGL -Wl,-rpath,.
You can replace . with any absolute path, for example to keep a shared copy under $HOME/lib: 
gcc -o myapp main.c -I$HOME/include -L$HOME/lib -lLWXGL -Wl,-rpath,$HOME/lib

​
Verifying the Install

Run a minimal smoke test to confirm the library loads and can open a window. Create smoke.c: 
#include <libLWXGL.h>
#include <stdio.h>

int main(void) {
    int rc = GCreateWindow(320, 240, "Smoke Test", 0);
    if (rc != 0) {
        fprintf(stderr, "GCreateWindow failed with code %d\n", rc);
        return 1;
    }
    /* Window opened successfully — clean up immediately */
    GTerminateWindow();
    printf("libLWXGL OK\n");
    return 0;
}
Compile and run: 
gcc -o smoke smoke.c -lLWXGL
./smoke
Expected output: 
libLWXGL OK
If GCreateWindow returns a non-zero code, consult the table below:
Return codeMeaning
0Success
1XOpenDisplay failed — check DISPLAY
2Default font (9x15) not found on the X server
3A window is already open
127+nFailed to allocate palette color n

​
Uninstalling

Remove the installed files manually and refresh the linker cache: 
sudo rm /usr/local/lib/libLWXGL.so /usr/local/include/libLWXGL.h
sudo ldconfig
This fully removes LWXGL from the system. Any application previously linked with -lLWXGL will fail to start until the library is reinstalled or the binary is relinked.

Build docs developers (and LLMs) love

Get started for freeTalk to us