Skip to content

1.2. Install

Jump to bottom
Kai Burjack edited this page Jan 11, 2020 · 8 revisions

LWJGL is organized in modules. Each module is packaged as a collection of artifacts, where each artifact has the same name but a different classifier.

  • The artifact name for the LWJGL core module is just lwjgl.
  • The artifact name for a binding module is lwjgl-<binding>, for example lwjgl-opengl for the OpenGL module.

The artifacts based on classifier are:

  • No classifier: the compiled Java classes
  • sources: the Java sources
  • javadoc: the API documentation
  • natives-<platform>: the native shared libraries for the corresponding platform

Not all artifacts have natives and not all artifacts with natives are available on all platforms.

This design means that you only need to download the modules that are needed for your project.

Additional modules can be downloaded and added later on, if your needs change.

Downloading LWJGL - Using the build configurator

The LWJGL website provides a handy configurator for choosing which parts of the library you want to download. This section will contain a brief explanation of what the separate parts of this configurator do.

There are three separate release channels to choose from: Release, Stable and Nightly. Unless you know what you are doing, you should use Release, as it will be more stable.

The Mode selector allows you to choose how you want to download the library. If you plan on using an IDE or need the actual .jar files, choose ZIP Bundle. If you are going to use maven or gradle, choose the respective option to generate a build script.

Maven/Gradle is recommended during development. The zip bundle is recommended when creating a production build or installer for your application.

Natives are not required for compiling your project, but are needed for running it. Thus, you need to get natives for all the platforms you want to run your application on. Remember that you don't need to download natives for all platforms at once. You can download additional natives when you are ready to distribute your project.

If it is your first time using LWJGL, the Getting Started or Minimal OpenGL presets should be sufficient to get started with most tutorials. Alternatively, you can create a custom configuration and choose exactly which modules you want. Keep in mind that you can view the description of the different modules by ticking Show descriptions under Settings.

Extracting the natives (optional)

The LWJGL native shared libraries do NOT need to be extracted from their .jar files. The SharedLibraryLoader that is included with LWJGL does it automatically at runtime.

The SharedLibraryLoader extracts the natives once and reuses them from run to run. The natives are overridden only if a different LWJGL version is detected.

The extract directory can be customized with Configuration.SHARED_LIBRARY_EXTRACT_DIRECTORY and Configuration.SHARED_LIBRARY_EXTRACT_PATH.

Using the SharedLibraryLoader is optional. For example a custom installer for an application may extract the natives to a specific location. In such cases, the familiar options -Djava.library.path and -Dorg.lwjgl.librarypath (or Configuration.LIBRARY_PATH) are still fully supported.

Setting up your build tool or IDE

Gradle or Maven

When using either Gradle or Maven, choose the mode "Gradle" or "Maven" (under "Mode") instead of "ZIP Bundle" in the generator. This will result in a portion of a build.gradle script containing dependency declarations for all selected modules and platforms which you can copy/paste into your own build.gradle file and use it to build your project.

Note that when using gradle you probably want to prepend apply plugin: 'java' and apply plugin: 'application' to build.gradle.

IntelliJ IDEA

IDEA supports Gradle/Maven projects and makes it trivial to use them. For a custom configuration, follow these instructions:

  1. Go to our download page, select channel, select zip bundle, review the options and choose the bindings you're interested in, then click on Generate Bundle.
  2. When the download is complete, extract its contents in your project.
  3. In IntelliJ, go to Project Structure > Libraries > New Project Library. Add all LWJGL .jar files (classes+natives) to the library and add the library as a dependency to your project module(s). You do not need to extract the native libraries.
  4. If you also downloaded the sources, add the corresponding .jar files as sources to the LWJGL library. You do not need to download and attach the javadoc .jar files, IntelliJ generates javadoc directly from sources.

If you want to match the Maven/Gradle behavior exactly, you could create 2 separate libraries:

  • One with the class+source .jar files, make it a compile dependency of your module(s).
  • One with the natives .jar files, make it a runtime dependency of your module(s).

You can do this in the Project Structure > Modules > select a module > Dependencies tab, by changing the Scope of each dependency.

NetBeans

  1. Download LWJGL as a ZIP Bundle using the build configurator and extract the archive to somewhere you will be able to find it later.
  2. Inside Netbeans, under Tools > Libraries press New Library... in the bottom left corner.
  3. Name the library something sensible, such as "LWJGL 3.1.0" and press OK
  4. The center of the Library window should now contain options to configure the library.
  5. In the Classpath tab add all .jar files from the previously downloaded .zip file, excluding those containing sources or javadoc in their name
  6. (Optional) In the Sources tab add all .jar files with sources in their name. This will give you access to both documentation and the source code directly from NetBeans. Source can be viewed in the editor with Ctrl-Left click while hovering over a function or class that belongs to LWJGL.
  7. Create a new project by choosing File > New Project.... Choose Java | Java Application as the project type.
  8. Find your project in the project window (Can be opened with Ctrl-1). Right click on Libraries, choose Import, find the previously created library and select Import Library and then Add Library.
  9. Check if everything worked as intended by adding the following line to your main class and running the project: System.out.println(org.lwjgl.Version.getVersion());. This should print the version of LWJGL which you are using.

Eclipse

(you need at least Eclipse Luna (4.4) or Eclipse Kepler (4.3) with the "Eclipse Java 8 Support (for Kepler SR2)" patch installed to work with LWJGL 3 in Eclipse)

Eclipse supports Gradle/Maven projects and it is highly recommended to use them instead of a manual Eclipse project configuration. However, if you prefer setting up a native Eclipse project, follow these instructions (works with Eclipse Neon):

  1. Download the ZIP bundle from https://www.lwjgl.org/customize
  2. When the download is complete, extract its contents to some file system directory, henceforth referred to as <lwjgl3>.
  3. In Eclipse go to menu "Window" > "Preferences" and in the tree view to the left search for 'Java' > 'Build Path' > 'User Libraries'
  4. Click "New..." in the 'User Libraries' dialog. In the opened modal dialog "New User Library" write "LWJGL3" in the 'User library name:' text field and click 'OK'. The newly created library "LWJGL3" should show up in the list 'Defined user libraries:'.
  5. Now, select this item in the list and click 'Add External JARs...'. This opens a standard OS file selection dialog allowing you to select *.jar files which get added to the classpath/buildpath of all projects using the LWJGL3 User Library. Go to <lwjgl3> and select all *.jar files which do not have -javadoc or -sources in their names. Make sure you don't forget the lwjgl-natives-<os>.jar file, and click 'Open'.
  6. This will populate the LWJGL3 user library in the list with respective entries for all selected jar files. You could leave it at that now in order to use LWJGL 3.
  7. However, if you want to have Sources and JavaDocs, you will have to select each of the entries, click on 'Source attachment: (None)' and on 'Edit...'. This will open the "Source Attachment Configuration" dialog. Here you could select 'External location' and 'External File...' to select the appropriate *-sources.jar file.
  8. In order to actually use the LWJGL3 User Library in one of your projects, go to the Build Path settings of your project and select the 'Libraries' tab. Here, click 'Add Library...', select 'User Library' and mark the "LWJGL3" User Library.
  9. Now you are set up to use LWJGL 3 in your project.

Other tools

If you are familiar with other tools or IDEs, feel free to add information about setting up LWJGL in them to this section. If you want to contribute, please make a post on the forum.

Getting Started

back

Clone this wiki locally