[test-android] disable tests by the converter. And it is fully documented now.

test-android/README.md

@@ -2,16 +2,40 @@
 
 It is meant to be an Android app that runs those fluidsynth tests under `../test` directory.
 
-It is not immediately doable at this moment because everything is based on ctest where each source has `main()` function that cannot be more than one within a shared library. Either every single test source file has to be compiled separately, or renaming `main()` to something else and have separate runnable (latter is much simpler).
+It is not immediately doable because everything is based on ctest where each source has `main()` function that cannot be more than one within a shared library. Therefore, we generate the modified test sources into this standalone Android tester app.
 
-But so far this app makes sure that it loads `libfluidsynth.so` without problem.
+Also, since those tests have to access to libfluidsynth non-public implementation, we have to build the entire native test libraries (for each ABI), not with `libfluidsynth.so`.
+
+The application was based on Android Studio 4.2 (when it was created).
 
 ## Building
 
-It can be built and run from Android Studio (or gradle if you prefer).
+Here is a brief task list to generate, build, and run Android tests:
 
-You have to build fluidsynth for Android first, and then copy
+- run `./convert-tests.sh` to generate runnable tests.
-`libfluidsynth.so` and all the dependencies into `app/src/main/jniLibs/{ABI}` (`armeabi-v7a` / `arm64-v8a` / `x86` / `x86_64`).
+- run `./download.sh` to download fluidsynth dependency archives to build from sources as Android dependencies.
+- run `./build-scripts/build-all-archs.sh` to build fluidsynth native libraries for Android.
+- copy `build-scripts/build-artifacts/lib` contents into `app/src/main/jniLibs`.
+- run `./gradlew connectedCheck` to build and run Android tests.
 
-If you want to build them locally the scripts under `build-scripts` directory would be useful. Run `download.sh` first, and then `build-all-archs.sh`. The scripts are mostly taken from the build scripts from `.azure`.
+Detailed explanation follows.
 
+(1) First of all, you have to generate the modified test sources as well as the native test runner from `../test` directory. `./convert-tests.sh` does this work for you.
+
+It is a simple sed script that expects various preconditions that those existing ctests meet at the moment when this script was created (e.g. test source filename can be used to construct a valid C function name, it must have `int main()` literally, it must be compilable among with other sources, etc.). This also overwrites `app/src/main/cpp/run_all_tests.c`
+
+You are supposed to run this every time the set of test files get updated. On CI builds it has to be run every time. This also applies when you want to try re-enabling those failing tests, adding exceptional tests that this converter cannot cover, or adding more failing tests.
+
+(2) Once you are done with generating tests, then the next step is to download all fluidsynth runtime dependencies. This can be done by `./download.sh`. It is based on (but not a complete copy of) [Azure DevOps CI build setup](https://github.com/FluidSynth/fluidsynth/blob/master/.azure/azure-pipelines-android.yml). You have to do once until the list of dependencies changes. On Azure DevOps this step is therefore already handled (when this notes were written).
+
+(3) Once you are done with downloading all those dependencies, the next step is to build fluidsynth for Android. Locally it can be achieved by `build-scripts/build-all-archs.sh`. It is (again) based on the Azure DevOps setup and therefore it is already handled there (when this notes were written).
+
+It will end up with `build-scripts/build-artifacts/` that contains a `include` directory and `lib/*` directories for each ABI, on local builds. (Azure DevOps builds it is `$(Build.ArtifactStagingDirectory)/lib/*`.)
+
+Once you have finished building fluidsynth for Android. there will be `$(topdir)/build_(ABI)` directories. While you want to build the Android tester app, you cannot remove them because those intermediate files (OBJ files) are referenced by this app's `CMakeLists.txt`.
+
+(4) The `lib` part from the above has to be copied into `app/src/main/jniLibs`. There should be `armeabi-v7a`, `arm64-v8a`, `x86`, and `x86_64` subdirectories. (Note that the locations are different between local builds and Azure DevOps.)
+
+(5) After all the steps above are done, the Android tester app is ready to build and run. You can either open this directory as a project on Android Studio, or run `./gradlew build` to build the app, or run `./gradlew connectedCheck` to build and run the tests on a connected Android target (emulator or device). You can also run the tests by simply launching the MainActivity as it run there before showing the UI.
+
+Note that those tests have to run on an Android target otherwise it does not make sense. `./gradlew build` or `./gradlew check` runs "test" in the project, but it does not mean they run on an Android target.

test-android/app/src/main/cpp/run_all_tests.c

@@ -1,54 +0,0 @@
-#include <assert.h>
-
-int preset_pinning_main();
-int seq_event_queue_remove_main();
-int seq_scale_main();
-int jack_obtaining_synth_main();
-int settings_unregister_callback_main();
-int pointer_alignment_main();
-int sfont_zone_main();
-int utf8_open_main();
-int seqbind_unregister_main();
-int sf3_sfont_loading_main();
-int sample_cache_main();
-int synth_process_main();
-int ct2hz_main();
-int seq_evt_order_main();
-int snprintf_main();
-int seq_event_queue_sort_main();
-int sfont_loading_main();
-int preset_sample_loading_main();
-int sfont_unloading_main();
-int sample_rate_change_main();
-int sample_validate_main();
-int synth_chorus_reverb_main();
-int bug_635_main();
-
-int run_all_fluidsynth_tests() {
-    int ret = 0; 
-    //ret += preset_pinning_main();
-    ret += seq_event_queue_remove_main();
-    ret += seq_scale_main();
-    ret += jack_obtaining_synth_main();
-    ret += settings_unregister_callback_main();
-    ret += pointer_alignment_main();
-    ret += sfont_zone_main();
-    //ret += utf8_open_main();
-    ret += seqbind_unregister_main();
-    //ret += sf3_sfont_loading_main();
-    //ret += sample_cache_main();
-    ret += synth_process_main();
-    ret += ct2hz_main();
-    ret += seq_evt_order_main();
-    ret += snprintf_main();
-    ret += seq_event_queue_sort_main();
-    //ret += sfont_loading_main();
-    //ret += preset_sample_loading_main();
-    //ret += sfont_unloading_main();
-    //ret += sample_rate_change_main();
-    ret += sample_validate_main();
-    ret += synth_chorus_reverb_main();
-    //ret += bug_635_main();
-    assert(ret == 0);
-    return ret;
-}

test-android/convert-tests.sh

@@ -1,8 +1,20 @@
 #!/bin/sh
 
+DISABLED_TESTS=(\
+    preset_pinning \
+    utf8_open \
+    sf3_sfont_loading \
+    sample_cache \
+    sfont_loading \
+    preset_sample_loading \
+    sfont_unloading \
+    sample_rate_change \
+    bug_635 \
+    )
+
 rm -f test-names.txt
 
-for f in `grep -lR "int main(void)" ../test/` ; do
+for f in `grep -lR "int main(void)" ../test/ | sort` ; do
     export TESTMAINNAME=`echo $f | sed -e "s/\.\.\/test\/test_\(.*\).c$/\1/"`
     echo $TESTMAINNAME >> test-names.txt
     export OUTPUTFILE=app/src/main/cpp/tests/test_${TESTMAINNAME}.c
@@ -17,14 +29,16 @@ while IFS= read -r line; do
     echo "int "$line"_main();" >> $RUN_ALL_TESTS ;
 done < test-names.txt
 
-echo "extern \"C\" {" >> $RUN_ALL_TESTS
 echo "int run_all_fluidsynth_tests() {" >> $RUN_ALL_TESTS
 echo "    int ret = 0; " >> $RUN_ALL_TESTS
 
 while IFS= read -r line; do
-    echo "    ret += "$line"_main();" >> $RUN_ALL_TESTS ;
+    if [[ " ${DISABLED_TESTS[@]} " =~ " ${line} " ]]; then
+        echo "    //ret += "$line"_main();" >> $RUN_ALL_TESTS ;
+    else
+        echo "    ret += "$line"_main();" >> $RUN_ALL_TESTS ;
+    fi
 done < test-names.txt
 
 echo "    return ret;" >> $RUN_ALL_TESTS
 echo "}" >> $RUN_ALL_TESTS
-echo "}" >> $RUN_ALL_TESTS