[rcore][android] App crashes when trying to link raylib dynamically

[OussamaTeyib]

Issue Description:

Generally, to use raylib in an Android project, you have two options, both "demonstrated" in raylib-game-template:

1. Compile raylib as a static library and link your code against it. You can either load your generated shared library using NativeActivity or a custom Java class. This works fine, and the app launches properly.

2. Compile raylib as a shared library and link your code against it. In this case, you need a custom Java class to load the two shared libraries since NativeActivity by default accepts only one library. A custom loader might look like this:

package com.company.app;

public class NativeLoader extends android.app.NativeActivity {
    static {
        System.loadLibrary("raylib");
        System.loadLibrary("main");
    }
}

However, this approach does not work, and the app crashes immediately after launch.

---

Possible Cause:

After trying multiple Java native loader implementations from the web, I believe the issue is not caused by Java, but rather by raylib itself.

Android requires native apps to use android_main(). Raylib, to improve portability and allow Android users to write a regular main(), handles android_main() internally and calls the user-defined main() function.

This creates a circular dependency:

• libmain depends on symbols from libraylib.
• libraylib “depends” on main from libmain.

In the case of static linking, this isn’t a problem because the libraries are merged. However, with dynamic linking, each library is loaded separately at runtime, and libraries that depend on each other must be loaded in a specific order. In this case, libraylib.so and libmain.so depend on each other, making it impossible to satisfy the load order. As a result, the app crashes immediately after launch.

---

Additional Info:

To prove that this is not a Java issue, I tested with an external standalone library (Box2D), and everything worked fine. Here’s the loader for that case:

package com.company.app;

public class NativeLoader extends android.app.NativeActivity {
    static {
        System.loadLibrary("box2d");
        System.loadLibrary("main"); // my code + raylib static library
    }
}

[raysan5]

@OussamaTeyib Thanks for reporting. Is there any possibility to address this issue without big changes on how raylib addresses the multiplatform approach (mapping main() to android_main())?

[orcmid]

@OussamaTeyib @raysan5

THE CONSIDERATION IN FAVOR OF SHARED LIBRARIES TO BIND TO NON-C/C++ ENGINES

The raylib library is written in C Language and is readily used in the case of (4) below in C/C++ apps. When language bindings are in different languages that do not operate in the ways discussed above, the usual requirement is to provide a shared library not exactly to the app, but to the app engine (e.g., the Java engine, and also .NET). The problem here, it seems to me, is that raylib is being asked to solve a problem that raylib is not designed-/built-for.

For example, to use the Java Native Interface (JNI), it is necessary to supply a shared library. I've done that. I think I knew what I was doing, in that case, but my shared library was a bridge to another shared library not written in Java and it did not become the provider-of-that-library's problem. (The JNI interface to the shared library is essentially COM based so a different beast than for raylib.)

My suspicion is this is the box we're in here is with the use of Java-like engines as the only way to incorporate "native" libraries. This should not be raylib's problem to solve. It should be the bridge-builder, binding-provider problem to solve.

I am sympathetic that this is the only way a preferred platform can have the use of raylib functionality DIRECTLY. This should not be raylib's problem because then raylib has to maintain it. Someone else should build the bridge.

CONSIDERATIONS AGAINST RAYLIB PROVIDING A SHARED LIBRARY

I would very much like to understand the fascination with having a shared library for raylib, apart from external requirements that are not matters of choice.

What is the expected benefit? In particular, I don't think it will do much for the binding problem in support of different run-time engines. Now I want to address this generally.

I see four considerations against it.

1. First, a shared library includes all of the run-time sharable data and functions, not just those used in a particular app. Linking to the ones that are used is via an indirect mechanism, but it is all parked in RAM someplace.

2. The benefit of a shared library is that it be used by more than one process/application at the same time. The operating-system shared libraries (on Windows, kernel.dll, etc.) have that quality. The pay-off is very clear in those cases. It is also very relevant in those cases, that on different versions of the OS, there is typical backwards compatibility so that apps will still run. Note that those libraries are not distributable with apps, they are tied to the OS and its version.

3. Shared libraries can support shared-library data that is static by process, even when multiple apps are using the library. This tends to be handled by the per-process initialization that is available when a shared library is bound-to at runtime. That takes special techniques in construction of the shared library, generally. Raylib uses a global data structure that is used across many functions and not dynamically/automatic, etc. I don't know what provisions are made to ensure that along with the API functions being in a shared library. If there are collisions with that arrangement, they probably don't arise because the running of two raylib apps concurrently is probably rather unlikely.

4. When a library API or function implementations have breaking changes, the only way to avoid this breaking access to a shared library is if each application ships the shared library it is built to and relies on the operating system to avoid duplication of the same specific shared-library code. Although it's a cool idea that updates with non-breaking changes can be installed without having the app be rebuilt, and folks will tell you how cool that is, there is now an increased security threat surface. A poisoned or simply defective update with an exploitable vulnerability can now expose previously safely-coded apps to a vulnerability out of the app-builder's control.

With static-library bindings including multiple object files and various static-binding libraries (without entry name clashes), and appropriate compilation options, only library code that is required for the functions depended upon will be incorporated in the app. Furthermore, there can be optimization of those functions, even including in-lining, with today's powerful compilation systems for C/C++. THIS IS A SWEET SPOT FOR RAYLIB.

[orcmid]

@OussamaTeyib @raysan5

PS: If the job can be done using a static raylib library, go for it. I can't see a downside.

[OussamaTeyib]

Thanks @orcmid for the detailed discussion and explanations. I fully agree with your assessment, and personally, I also prefer linking raylib statically.
I even tried patching a workaround using weak symbols, but that didn’t help, so it seems the issue might be deeper in the way raylib handles the app lifecycle or integrates with the Java activity.
I’ll leave it to @raysan5 to close this issue as not planned, if they agree, and I suggest updating the documentation to clearly state that the current Android implementation supports only static linking.

[raysan5]

@orcmid thanks for the detailed explanation. I'm closing this issue as not planned.
@OussamaTeyib Feel free to update the Android documentation, is open for editing to everyone: https://github.com/raysan5/raylib/wiki/Working-for-Android

[OussamaTeyib]

Hi @raysan5,

I've investigated the issue further and confirmed that there is indeed a circular dependency problem, as shown in the following log:

2025-08-21 17:43:35.562 11716-11716 nativeloader com.company.app D Load /data/app/.../libraylib.so using class loader ns clns-9 (caller=/data/data/com.company.app/code_cache/.../classes3.dex): dlopen failed: cannot locate symbol "main" referenced by "/data/app/.../libraylib.so"...
2025-08-21 17:43:35.564 11716-11716 AndroidRuntime com.company.app D Shutting down VM
2025-08-21 17:43:35.572 11716-11716 AndroidRuntime com.company.app E FATAL EXCEPTION: main
                                                                 Process: com.company.app, PID: 11716
                                                                 java.lang.UnsatisfiedLinkError: dlopen failed: cannot locate symbol "main" referenced by "/data/app/.../libraylib.so"...

The problem can be avoided by loading only the main library. The Android runtime will implicitly load libraylib.so because it is a dependency of libmain.so. The native loader can be simplified as follows:

package com.company.app;

public class NativeLoader extends android.app.NativeActivity {
    static {
        System.loadLibrary("main"); // That's all
    }
}

This approach resolves the crash while maintaining proper library loading order.

[OussamaTeyib]

Fun fact:

The entire native loader we wrote above (which is also what raylib-game-template uses) is actually not necessary—whether using static or dynamic linking. This is because we are subclassing android.app.NativeActivity, which by default loads the library specified in the manifest file (the default library name is main if none is specified).

So, as long as we rely on NativeActivity and do not implement a full custom Android activity, the instruction:

System.loadLibrary("main");

is redundant.