Add Prefab Support for Easier Integration into Android Projects

[andersonkxiass]

First, I’d like to express my appreciation for the work you’ve done on this project. The library is incredibly useful, and I’m grateful for the effort that has gone into developing and maintaining it.

I’m currently trying to integrate the library into an Android project but have encountered challenges during the compilation and setup process. I believe that adding Prefab support could make the library much easier to integrate, similar to how Oboe offers support for Prefab.

Prefab is a feature in the Android Gradle Plugin that allows developers to package and consume prebuilt native libraries more easily. By providing prefab support, the library could be included directly in Android projects without requiring extensive manual setup.

To help clarify my request, here are some resources that might be helpful:

Prefab Documentation: https://google.github.io/prefab/
Oboe Prefab Example: https://github.com/google/oboe/tree/main/prefab
Prefab Publishing Example: https://github.com/android/ndk-samples/blob/main/prefab/prefab-publishing/mylibrary/build.gradle

While I understand that open-source contributions often depend on volunteers and contributors, I am unfortunately not a C/C++ specialist and cannot create a pull request for this myself. However, I’m happy to assist in testing or documenting the setup once implemented.

Thank you for considering this suggestion! I believe this addition would greatly improve the usability of the library for Android developers. Please let me know if there’s any way I can assist further or if more information is needed.

[derselbst]

Apologize, I'm probably as far away from Android as you are from C++. I've read through the docs, looked at the examples, yet failed to build the oboe prefab example myself, so it's still not clear to me which problem exactly prefab is supposed to solve.

From my understanding, prefab can generate cmake scripts and ndk-build scripts that are intended to ease consuming binaries. Generating cmake scripts seems redundant to me, because fluidsynth's buildsystem is already cmake-based and ships the proper scripts for integrating it into other cmake buildsystems, i.e. even without prefab you can find_package(fluidsynth) in your app, if it's cmake based.

ndk-build on the other hand seems to be exclusively used by the ndk.

[andersonkxiass]

Hi @derselbst,

Thank you so much for taking the time to respond! I truly appreciate your effort in maintaining this fantastic library, as well as your thoughtful insights regarding my suggestion about Prefab support.

I wanted to expand on why I think adopting Prefab could be beneficial, clarify how it can be implemented, and offer my assistance to contribute as a user, even though I’m not a C/C++ expert.

From my perspective as an Android developer who isn’t deeply experienced with C/C++, Prefab is a game-changer because it abstracts away much of the complexity involved in integrating native libraries. For example, when I used Oboe, the steps to include the library in my project were as simple as:

1. Adding the dependency to build.gradle.
2. Enabling Prefab with a straightforward Gradle configuration.
3. Linking it in CMakeLists.txt using find_package.

Detailed oboe setup:

1. Gradle-Based Integration:

   • All I needed to do was add a single line to my build.gradle file:

     dependencies {
         implementation 'com.google.oboe:oboe:X.X.X'
     }

   • This simplicity means I didn’t have to worry about downloading or building the source code for Oboe manually.

2. Prefab Integration:

   • Enabling Prefab in the Gradle file was straightforward:

     android {
         buildFeatures {
             prefab true
         }
     }

3. Minimal CMake Configuration:

   • In my CMakeLists.txt file, I could simply include and link Oboe:

     find_package (oboe REQUIRED CONFIG)
     target_link_libraries(native-lib oboe::oboe)

4. Immediate Usability:

   • Once configured, I was able to use Oboe in my native code without worrying about low-level build details:

     oboe::AudioStreamBuilder builder;
     builder.setFormat(oboe::AudioFormat::Float)
             ->setChannelCount(oboe::ChannelCount::Mono)
             ->setSampleRate(48000)
             ->setCallback(this);
     builder.openStream(&stream);
     stream->requestStart();

   • This meant no need to manage source code, environment settings, or manually resolve dependencies.

This is especially helpful for non-experts who want to use a native library but lack the knowledge or time to dive into low-level setup processes.

I understand your point about FluidSynth already being CMake-based, which makes generating CMake scripts with Prefab seem redundant. However, the real strength of Prefab is not just in generating scripts—it’s in packaging and distributing the library in a way that makes integration seamless for Android projects.

Prefab automates:

• Prebuilding the .so binaries for multiple ABIs (e.g., armeabi-v7a, arm64-v8a, etc.).
• Organizing headers and libraries into a structured format for distribution.
• Providing a standard interface for Gradle to consume these native dependencies directly.

To adopt Prefab, the library would need to:

1. Build FluidSynth for Android using the NDK for all supported ABIs.
2. Organize the binaries, headers, and a prefab.json configuration into the required format.
3. Package the library as a .zip (or include it in an .aar) and distribute it through a Maven repository.

I've tried to compile general information on how to adopt prefabrication (again, my aim here is to try to provide as much information as possible to clarify and see if it makes sense).

Steps to Create Prefab for FluidSynth

1. Cross-Compile for Android:
   Use the Android NDK to build the shared library (libfluidsynth.so) for different ABI targets (e.g., armeabi-v7a, arm64-v8a, x86, x86_64).
   Example command:

   cmake -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
         -DANDROID_ABI=arm64-v8a \
         -DANDROID_PLATFORM=android-21 \
         -DCMAKE_BUILD_TYPE=Release \
         -B build-arm64-v8a \
         -S .
   cmake --build build-arm64-v8a --target install

Repeat for Other ABIs
Adjust the -DANDROID_ABI parameter for each target ABI (e.g., armeabi-v7a, x86, etc.).

Create a folder structure for the Prefab package:

prefab/
├── modules/
│   └── fluidsynth/
│       ├── headers/         # Public headers (e.g., fluidsynth.h)
│       ├── libs/
│       │   ├── arm64-v8a/
│       │   │   └── libfluidsynth.so
│       │   ├── armeabi-v7a/
│       │   │   └── libfluidsynth.so
│       │   ├── x86/
│       │   │   └── libfluidsynth.so
│       │   └── x86_64/
│       │       └── libfluidsynth.so
│       └── prefab.json      # Prefab module descriptor
└── prefab.json              # Root Prefab descriptor

• headers/: Contains all the headers required to use FluidSynth.
• libs/: Contains the prebuilt shared libraries for each ABI.
• prefab.json (root): Describes the Prefab package.
• prefab.json (module): Describes the specific module within the package.

---

Write the Prefab Configuration

1. Root prefab.json:

   {
       "name": "fluidsynth",
       "schema_version": 1
   }

2. Module prefab.json:
   Located in prefab/modules/fluidsynth/:

   {
       "library_name": "fluidsynth",
       "headers": "headers",
       "dependencies": []
   }

Package the Prefab
Compress the prefab/ directory into a .zip file:

zip -r fluidsynth-prefab.zip prefab/

Alternatively, if you are creating an Android .aar library, include the prefab/ directory in the aar package.

Publish the Prefab
Publish the .zip or .aar to a Maven repository (e.g., JCenter, Maven Central, or a private repository). Developers can then add the library to their Gradle project.

Usage in Android Projects

Once published, Android developers can integrate FluidSynth by:

1. Adding the dependency to their build.gradle:

   dependencies {
       implementation 'org.fluidsynth:fluidsynth:X.X.X'
   }

2. Enabling Prefab in their build.gradle:

   android {
       buildFeatures {
           prefab true
       }
   }

3. Updating CMakeLists.txt:

   find_package(fluidsynth REQUIRED CONFIG)
   target_link_libraries(native-lib fluidsynth::fluidsynth)

I fully understand and respect that open-source projects require a significant time investment from maintainers like you, and I appreciate the dedication you’ve already shown to this project. I don’t mean to add unnecessary burden or imply that this is a trivial task—it’s simply a suggestion that I believe could make FluidSynth even more accessible to Android developers.

[derselbst]

Many thanks for the write-up! We are already distributing precompiled Android binaries with our Github releases. So to me it looks like it boils down to a simple folder-restructuring of that plus adding the two mentioned json files. Sounds pretty straight forward, I'll give it a try when I find some time.
You mentioned a Maven repository. I have no experience with that - is that required, what's the benefit, or would it be fine to just publish a ZIP archive with the Github releases as we already do?

[andersonkxiass]

Thanks for keeping this on your radar! It's great to hear that only a folder restructuring is needed.

Publishing to a Maven repository is the standard for JVM-based library distribution. Once FluidSynth is available there, developers can easily add it to their projects with a simple dependency like this:

dependencies {
    implementation 'org.fluidsynth:fluidsynth:X.X.X'
}

I'd be happy to assist with the Maven setup!

[derselbst]

I have a first test ready, you can download the ZIP from this build:
https://dev.azure.com/tommbrt/d3638885-de4a-4ce7-afe7-f237ae461c07/_apis/build/builds/11401/artifacts?artifactName=fluidsynth-android24&api-version=7.1&%24format=zip

Essentially, I've renamed that inner prefab.json to module.json, as the docs suggest so. And I have renamed the headers directory to include, which seems to be recognized by default.

Before investing more time, like Maven setup, aar, adding package metadata, etc., it would be good to know if that approach works at all. My biggest concern is that fluidsynth's dependency libraries won't be correctly discovered, since all the information I found so far only talk about the libs directory containing a single library.

[andersonkxiass]

Thank you for your patience and for completing this work. I’ll test it and get back to you shortly