comment -*- mode: text; tab-width:2; indent-tabs-mode:nil -*-

Android support

* Tested environment
  Android 4.0 (x86)

* Build
  o Build with apache ant
    $ cd mlterm-x.x.x/android
    $ ./prepare-ant.sh /foo/bar
    $ export ANDROID_HOME=...
    $ export ANDROID_NDK_HOME=...
    $ export JAVA_HOME=...
    $ cd /foo/bar
      (edit build-ant.sh)
      (prepare some libraries in jni/ (see below))
    $ ./build-ant.sh
      => Install bin/mlterm-release-unsigned.apk to Android.

  o Build with gradle
    $ cd mlterm-x.x.x/android
    $ ./prepare-gradle.sh /foo/bar
    $ export ANDROID_HOME=...
    $ export ANDROID_NDK_HOME=...
    $ export JAVA_HOME=...
    $ cd /foo/bar
      (edit build-gradle.sh)
      (prepare some libraries in app/src/main/jni/ (see below))
    $ ./build-gradle.sh
      => Install app/build/outputs/apk/release/app-release-unsigned.apk to Android.

    (See .github/workflows/ci.yml)

  o Prepare some libraries (Optional)
    - fribidi
      Copy following files of fribidi (0.19.6) to jni/fribidi/.

      arabic-misc.tab.i     fribidi-bidi-types.c          fribidi-mem.c
      arabic-shaping.tab.i  fribidi-bidi-types.h          fribidi-mirroring.c
      bidi-type.tab.i       fribidi-bidi-types-list.h     fribidi-mirroring.h
      bidi-types.h          fribidi-common.h              fribidi-run.c
      common.h              fribidi-config.h              fribidi-shape.c
      config.h              fribidi-deprecated.c          fribidi-shape.h
      debug.h               fribidi-deprecated.h          fribidi-types.h
      fribidi.c             fribidi-enddecls.h            fribidi-unicode.h
      fribidi.h             fribidi-flags.h               fribidi-unicode-version.h
      fribidi-arabic.c      fribidi-joining.c             joining-type.tab.i
      fribidi-arabic.h      fribidi-joining.h             joining-types.h
      fribidi-begindecls.h  fribidi-joining-types.c       mem.h
      fribidi-bidi.c        fribidi-joining-types.h       mirroring.tab.i
      fribidi-bidi.h        fribidi-joining-types-list.h  run.h

    - libotf
      Copy following files of libotf (0.9.13) to jni/libotf/.

      config.h  internal.h  otf.h  otfdrive.c  otferror.c  otfopen.c

    - freetype2
      Build static library (libfreetype.a) for Android (*), and place files as follows.

      (*) Read "Autoconf" section in
          https://developer.android.com/ndk/guides/other_build_systems

      C Header files: jni/freetype/{armeabi,armeabi-v7,x86,mips}/include/
      Static library: jni/freetype/{armeabi,armeabi-v7,x86,mips}/lib/

      Specify following options to ./configure script in building freetype2.
      --with-png=no --with-harfbuzz=no --with-bzip2=no --with-brotli=no

e.g.) freetype2
export ANDROID_HOME=/usr/lib/android-sdk
export ANDROID_NDK_HOME=/usr/lib/android-sdk/ndk/XX.X.XXXXXXX
export JAVA_HOME=/usr/lib/jvm/java-X.X.X-openjdk-amd64/
CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabiXX-clang -fPIC" ./configure --host=armv7a-linux-androideabi --prefix=/tmp --disable-shared --with-png=no --with-harfbuzz=no --with-bzip2=no --with-brotli=no
make
make install

    - libssh2
      Build static libraries (libssh2.a(libssh2), libcrypto.a(openssl or libressl))
      for Android, and place files as follows.

      C Header files: jni/libssh2/{armeabi,armeabi-v7,x86,mips}/include/
      Static library: jni/libssh2/{armeabi,armeabi-v7,x86,mips}/lib/

e.g.) libssh2, libressl
export ANDROID_HOME=/usr/lib/android-sdk
export ANDROID_NDK_HOME=/usr/lib/android-sdk/ndk/XX.X.XXXXXXX
export JAVA_HOME=/usr/lib/jvm/java-X.X.X-openjdk-amd64/
CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabiXX-clang -fPIC" ./configure --host=armv7a-linux-androideabi --prefix=/tmp --disable-shared
make
make install

  o If build-gradle.sh exits with a following error message,
    add "distributionUrl=https\://services.gradle.org/distributions/gradle-4.6-all.zip"
    to /foo/bar/gradle/wrapper/gradle-wrapper.properties.

    A problem occurred evaluating project ':app'.
    > Failed to apply plugin [id 'com.android.application']
      > Minimum supported Gradle version is 4.6. Current version is 3.2.1.
        If using the gradle wrapper, try editing the distributionUrl in
        /foo/bar/gradle/wrapper/gradle-wrapper.properties to gradle-4.6-all.zip

  o Note that "LOCAL_ALLOW_UNDEFINED_SYMBOLS := true" is defined in Android.mk.
    So mlterm can crash by UnsatisfiedLinkedError.
    Check crash logs with logcat command.

  o Following steps enable mosh.
    - Build static library of protobuf for Android and place it as follows.

      C Header files: jni/protobuf/{armeabi,armeabi-v7,x86,mips}/include/
      Static library: jni/protobuf/{armeabi,armeabi-v7,x86,mips}/lib/

    - Execute ./configure in mosh.

    - Build and install mlterm. (See "Build with gradle")
      Specify mosh and openssl (or libressl) src directories to 2nd and 3rd
      arguments of ./prepare-gradle.sh.

    - Specify "mosh://" before a mosh server address or name in the connect
      dialog.

* Configuration
  Place configuration files (see README.fb in detail) in /sdcard/.mlterm/.

* Note
  o Available font formats are pcf and ttf.
  o mlterm uses /system/fonts/DroidSansMono.ttf by default.
    If you want to customize it, add "DEFAULT=/foo/bar/font.ttf" to
    /sdcard/.mlterm/font-fb.
    If you want to change the size of it, add "fontsize=<pixel size>" to
    /sdcard/.mlterm/main or append ":<percent>" (":100" means the normal size) to
    a font path in /sdcard/.mlterm/font-fb.
  o If you want to show emoji, copy images/emoji/unicode/*.png in
    https://github.com/github/gemoji/archive/master.zip to /sdcard/.mlterm/emoji/
    in advance.
  o mlterm-android-YYYYMMDD.apk contains the feature of rendering bidi and
    hindi (ISCII).
    Following steps are necessary to enable it.
    - Install DVYG0ntt.ttf.
    - Add "ISCII_HINDI=.../DVYG0ntt.ttf" to /sdcard/.mlterm/font-fb
    If you want to show other scripts of ISCII, edit 'tables' in
    vtemu/libctl/vt_iscii.c, install ISCII fonts and add it to
    /sdcard/.mlterm/font-fb.
  o You can show a software keyboard if you double-click the left mouse
    button (Button1) at the lower right corner of the screen.
  o Context menu (copy&paste and configuration) pops up by long click at the
    lower right corner.
  o You can rotate display by "rotate_display = right" or "rotate_display = left"
    in /sdcard/.mlterm/main.
  o The default values of following options are as below on Android.
    "font_size_range"       => 1-200
    "only_use_unicode_font" => "true"
    "box_drawing_font"      => "unicode"
  o "use_local_echo" option is unavailable.
  o "start_with_local_pty" option disables ssh connection dialog on startup if
    "default_server" option is not specified.
  o Input method plugin is not supported.
  o Scroll upward or downward by flick gesture. If you want to select characters
    instead of scrolling, touch screen for more than 0.5 sec.
  o Daemon mode is unavailable.
