Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/LWJGL/lwjgl3/llms.txt

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

A binding is a module that exposes a native C library to Java. LWJGL generates the JNI glue code from Kotlin template files, so adding a binding means creating those templates and registering the new module in several configuration files. This page covers every file you need to touch.

​
Before you start

The best starting point is an existing binding that resembles the library you want to wrap. LWJGL includes bindings with different styles depending on the library’s nature (e.g., object-oriented API, flat C API, header-only). Browse modules/lwjgl/ and pick one that is structurally similar to your target library.
After adding your binding, open a pull request against the LWJGL repository and follow the Contributing guide.

​
Module structure

Each binding lives under modules/lwjgl/<binding>/ and follows this layout: 
modules/lwjgl/<binding>/
├── src/
│   ├── main/
│   │   ├── c/               # Hand-written C code (optional)
│   │   ├── java/            # Hand-written Java code (optional)
│   │   └── resources/       # module-info descriptor
│   ├── templates/
│   │   └── kotlin/
│   │       └── <binding>/
│   │           └── templates/   # Kotlin template files
│   ├── generated/
│   │   ├── c/               # Generator output — C JNI glue
│   │   └── java/            # Generator output — Java classes
│   └── test/
│       └── java/            # Tests (optional)
Copy this structure from an existing binding and rename accordingly.

​
Registration steps

Besides the files under modules/lwjgl/<binding>/, several other places must be updated. Complete all of the following steps.
1

Copy an existing binding module

Copy the directory structure of a similar binding under modules/lwjgl/ and rename it to match your new library. Update the module-info descriptor in src/main/resources/ and adjust any hand-written Java or C sources.
2

Update build.xml

Open the root build.xml and add entries in three places:
  • compile target — add a compileBinding tag for the new binding.
  • compile-tests target — add the demo package if the binding includes demos.
  • release target — add a release-module tag for the binding.
3

Update config/build-bindings.xml

Add a binding.<name> property so the binding can be conditionally enabled or disabled. Also update the forEachBinding macro definition to include the new binding name.
4

Update config/<platform>/build.xml

For each platform the binding supports, add a build definition to the corresponding config/<platform>/build.xml file (e.g., config/linux/build.xml, config/windows/build.xml, config/macos/build.xml).
5

Update config/tests.xml

If the binding includes tests, add the test package to config/tests.xml (and to any applicable config/tests_<platform>.xml files).
6

Register in Generator.kt

Open modules/generator/src/main/kotlin/org/lwjgl/generator/Generator.kt and add the new binding to the Binding enum. This is what causes the Generator to process your templates during ant generate.
7

Update README.md

Add the new library to the “List of Supported Bindings” table in the root README.MD.
8

Add release notes

Document the new binding in doc/notes/<version>.md under the next planned release.
9

Update build.gradle.kts

Add the new binding to the Artifacts enum in build.gradle.kts so it is included in Gradle / Maven artifact generation.
10

Update IDEA project files (optional)

If you use IntelliJ IDEA, add the new Java and Kotlin modules to the project:
  • .idea/modules.xml — add both module entries.
  • Java module file: .idea/modules/lwjgl/<binding>.iml
  • Kotlin module file: .idea/modules/templates/<binding>.iml
If the library will be listed on the LWJGL website build configurator, you also need to add a definition for it in client/routes/customize/BuildConfigurator/lwjgl/nightly.js in the lwjgl3-www repository. This is a separate repository from the main lwjgl3 repo.

​
Writing templates with the Generator DSL

Templates are Kotlin source files that use the LWJGL Generator DSL to describe a native library’s API. The Generator reads these files and produces Java binding classes and C JNI glue code. Template files live at: 
modules/lwjgl/<binding>/src/templates/kotlin/<binding>/templates/
A minimal template file looks like this: 
package org.lwjgl.<binding>.templates

import org.lwjgl.generator.*

val MyLib = "MyLib".nativeClass(Module.MY_BINDING, prefix = "ML") {
    documentation = "Bindings to the MyLib library."

    IntConstant(
        "A constant value.",
        "CONSTANT_NAME"..0x0001
    )

    void(
        "myFunction",
        "A simple function.",
        int("param", "an integer parameter")
    )
}
Key DSL concepts:
  • nativeClass — Defines a Java class that maps to a native header. The prefix is prepended to constant names.
  • Type mappings — int, float, void, charUTF8.p (UTF-8 string pointer), opaque_p (opaque pointer), etc.
  • IntConstant / LongConstant — Declare enumerated constants.
  • Function definitions — Written as returnType("functionName", "doc", params...).
  • AutoSize — Instructs the generator to derive a length parameter automatically from a buffer parameter.
  • nullable / NullTerminated — Annotate pointer parameters with nullability or termination semantics.
The Generator source at modules/generator/src/main/kotlin/org/lwjgl/generator/ contains the full DSL definition. Reading an existing binding’s templates alongside the generated Java output is the fastest way to learn the DSL.

Build docs developers (and LLMs) love

Get started for freeTalk to us