raylib-d

(static) D bindings for raylib, a simple and easy-to-use library to learn videogames programming.

Installation

Adding the dependency

raylib-d is used via the dub build system.

Use dub add to add raylib-d to the dependency list of an existing project:

> dub add raylib-d
Adding dependency raylib-d ~>5.5.0
>

Or you can add the dependency through the interactive prompts when creating your project with dub init

Get a copy of Raylib

You will need a copy of the raylib binary C library to link against, in order to run a raylib-d program. There are 3 ways to get this. Please read ALL the instructions before picking which mechanism you want to use.

(preferred) Use the raylib-d:install utility to copy the appropriate pre-built library.
Download the precompiled binary from the official github account for raylib.
Compile the library from source

Method 1: install appropriate raylib library with helper tool

Since raylib-d version 4.2.1 onwards, a new raylib-d:install subproject is included, along with pre-built binary raylib libraries. This greatly simplifies the process of obtaining pre-built libraries. Note that not all binary distributions are included.

Run this command from your project directory, and it will copy all the appropriate library files to your project directory:

> dub upgrade
> dub run raylib-d:install

The following OS/arch combinations are included:

Windows - x86_64
Linux -x86_64 Note: 4.2.4 and above!
MacOS - x86_64
MacOS - arm64

If other platforms are desired, please let me know in the issues. As of now, I am only supporting libraries that I built myself or that are included in the official distribution.

Note that D does not natively support WASM, and until it does, I will not be supporting it here.

This command can be executed as part of your build (generally in a preBuildCommands directive), with the option -u=no to suppress any interactive prompts, and also -q will suppress any output in general.

Method 2: Download official binaries

Download the official precompiled binaries from raylib's github page. Find the appropriate download archive for your version of raylib and your OS/arch. Copy or move the files out of the lib subdirectory into your project directory.

Notes for Windows users:

The raylib dll linker file will be named raylibdll.lib. It is recommended to copy this file, but rename it to raylib.lib. The raylib.lib file included in the zipfile is for static linking, which is not recommended.
Version 4.2.0 of raylib had a build issue where it did not export a needed symbol for raylib-d 4.2.x, and therefore the downloaded version will not link with raylib-d. If you are using raylib 4.2.0, use Method 1.

Method 3: Compile raylib from source

You can get the library from the source, and build it according to those instructions. Make sure to checkout the version tagged, and not the master branch. raylib is under continuous development, and the binding does not take into account any possible changes to API that may have occurred. You may get linker errors (or worse, memory corruption) if you use the master version, or wrong tagged version of raylib! Due to the way C functions are linked, there is no protection against this.

The Windows notes from Method 2 apply here as well.

Optional: relocate libraries (Linux/MacOS)

On Posix systems (non-windows), you have the option of moving the library files to the appropriate directory instead of your project directory. On most systems, this would be /usr/local/lib.

To do this, use the sudo command:

> sudo mv libraylib* /usr/local/lib

On Linux, you should also reload the library cache:

> sudo ldconfig

This aids in running your executable, as the library can be found easily by the dynamic loader.

See the linking instructions for ways to avoid this step. This step is never necessary for Windows, and there is no "global" location to use.

Linking instructions in dub.json

You must include the linker flags to link against the raylib library in your dub.json file. This is done using the "libs" directive.

The following directives should work for all systems, for the case where the library is in the project directory.

"dependencies": { "raylib-d": "~>5.5.0" },
"libs": [ "raylib" ],
"lflags-posix" : ["-L."],
"lflags-osx" : ["-rpath", "@executable_path/"],
"lflags-linux" : ["-rpath=$$ORIGIN"],

The OS-specific lflags lines are unnecessary if your library is copied to /usr/local/lib

The -rpath flag allows the system to load the library from the local directory without using environment variables.

If you are using dub.json, and you use the raylib-d:install script, this will give the option to update your dub.json file to include all the correct linker directives.

Using the correct library

WARNING: Make sure you get the correct copy of the raylib library based on the version of raylib-d! Getting the incorrect version will cause SILENT compatibility errors, including memory corruption. It is extremely important to match these together.

If you depend on raylib-d vX.Y.Z, then your raylib binary should be vX.Y.0. Note that so far, raylib has never had point releases, but raylib-d may have them. Note that raylib-d version 3.1.0 is matched against raylib version 3.7.0, but should probably never have been tagged that way. There is an equivalent 3.7.0 tag now.

For example, if you depend on raylib-d version v3.0.x, then you should download raylib version 3.0.0. If you depend on raylib-d version 3.7.x, then you should download raylib version 3.7.0.

Starting with version 4.2.0, raylib-d includes a new module raylib.binding, which at the moment contains one function: validateRaylibBinding. @raysan5 was kind enough to include a runtime-accessible version string for version 4.2.0 of the library, so now we can validate the raylib binding mechanically without relying on proper environmental setup. So if you compile against one version, but link against another, you can call this function and it will exit the program with an error code if the binding is incorrect. This is better than creating memory corruption errors!

As noted earlier, this did not properly get exported for the pre-built Windows dll for 4.2.0. Therefore, you must use installation method 1 above to link with raylib-d 4.2.x.

Running your program

In order to run your program, you will need to ensure the raylib dynamic library is available for loading. This is different based on the OS:

On Windows, you simply need the raylib.dll file to be located in the same directory as your executable, or in the PATH.
On MacOS, if you used the -rpath option as specified above, you can run the executable as long as the appropriate dylib is located in the same directory as your executable. Alternatively, it can be located in /usr/local/lib. If you do not use the -rpath option, you can export the environment variable DYLD_LIBRARY_PATH to point at the path where your library resides and it will be loaded.
On Linux, the same instructions as MacOS apply, except that if you want to use the environment variable it is LD_LIBRARY_PATH.

Example Program

import raylib;

void main()
{
    // call this before using raylib
    validateRaylibBinding();
    InitWindow(800, 600, "Hello, Raylib-D!");
    SetTargetFPS(60);
    while (!WindowShouldClose())
    {
        BeginDrawing();
        ClearBackground(Colors.RAYWHITE);
        DrawText("Hello, World!", 400, 300, 28, Colors.BLACK);
        EndDrawing();
    }
    CloseWindow();
}

Port of raylib examples

@D-a-n-i-l-o has been kind enough to port a large amount of the raylib examples from the C library to D (maybe all of them at this point!). He has passed on the repository to me, so please see the repository for more information.

BetterC support (Experimental)

BetterC was added for the raylib-d binding, but has since broken since switching away from a source library.

If you wish to help fix, please file an issue and even better, submit a PR.

Docs/Cheatsheet

At the moment, we do not properly ddoc the binding. This may change in the near future. However, all documentation is valid from the raylib online cheatsheet, or you can view the binding source files directly.

Raygui

As of v 5.5.0, raygui is no longer included in raylib-d. This is intentional, as the raygui binding was not properly maintained, and the version of raygui is not tied to any one version of raylib. Instead, it is in the raygui-d package.

License

raylib-d is licensed under an unmodified zlib/libpng license. View LICENSE.

schveiguy / raylib-d

readme