README.md

   1 # About
   2
   3 This is a demo of using [Haskell](https://haskell.org),
   4 [Nix](https://nixos.org/) and [Miso](https://haskell-miso.org)
   5 to produce a [LynxJS](https://lynxjs.org) application for Android.
   6
   7 The main interest about this demo is that everything is reproducibly built with Nix,
   8 including the building of the `.apk` with `gradle`.
   9
  10 # Requirements
  11
  12 - `nix` [installed](https://nixos.org/download/).
  13 - A host supporting the [Kernel Virtual Machine (KVM) hypervisor](https://developer.android.com/studio/run/emulator-acceleration)
  14 (and having it enabled in its BIOS), or an Android device in debug mode to install the `.apk`.
  15
  16 # Usage
  17
  18 ## For an Android emulator
  19
  20 Running:
  21 ```console
  22 nix -L run git+https://radicle-mermet.sourcephile.fr/z2BeGZUdNCY3FzYarKMV7XXXuc5os.git#android-emulator-x86_64
  23 ```
  24 or alternatively (for hacking):
  25 ```console
  26 git clone https://radicle-mermet.sourcephile.fr/z2BeGZUdNCY3FzYarKMV7XXXuc5os.git haskell-miso-nix-demo &&
  27 cd haskell-miso-nix-demo &&
  28 nix -L run .#android-emulator-x86_64
  29 ```
  30 or alternatively (for [radicle](https://radicle.xyz) users):
  31 ```console
  32 rad clone z2BeGZUdNCY3FzYarKMV7XXXuc5os &&
  33 cd haskell-miso-nix-demo &&
  34 nix -L run .#android-emulator-x86_64
  35 ```
  36 should saturate your download link, fill you `/nix/store/`, produce a lot of heat
  37 and eventually spawn an Android emulator running a demo app
  38 where you can increase (resp. decrease) a counter
  39 by tapping on a cat 🐈 (resp. a ramen dish 🍜).
  40
  41 __ResourceWarning:__
  42 because the Haskell compiler (GHC) has to be patched
  43 (otherwise the buttons of the app do not work)
  44 and is not using the same `nixpkgs` as the ones on the public cache
  45 `haskell-miso-cachix.cachix.org`,
  46 this demo requires a lot of CPU cycles and memory space in `/tmp`
  47 to build that patched GHC.
  48
  49 __ResourceWarning:__
  50 besides part of it being in the `/nix/store/`
  51 the actual Android system remains in `/tmp/nix-android-user-home-*` after closing the emulator,
  52 since it weights several gibibits you may want to remove it before your next reboot.
  53
  54 ## For an Android device
  55
  56 ```console
  57 git clone https://radicle-mermet.sourcephile.fr/z2BeGZUdNCY3FzYarKMV7XXXuc5os.git haskell-miso-nix-demo &&
  58 cd haskell-miso-nix-demo &&
  59 nix -L build .#default &&
  60 adb install result/app-debug.apk
  61 ```
  62
  63 __PortabilityNote:__
  64 this demo targets the Android platform 34 which requires Android >= 14,
  65 and all main computer architectures should be supported:
  66 ```console
  67 $ aapt dump badging result/app-debug.apk | grep native-code
  68 native-code: 'arm64-v8a' 'armeabi-v7a' 'x86' 'x86_64'
  69 ```
  70
  71 # Acknowledgements
  72
  73 - https://github.com/haskell-miso/miso-lynx provided the `counter` example.
  74 - https://github.com/lynx-family/integrating-lynx-demo-projects provided the `JavaEmptyProject`.
  75
  76 # Hack
  77
  78 Java dependencies in `android/deps.json` can be updated with:
  79 ```console
  80 nix -L run .#default.update-deps
  81 ```
  82
  83 Using `nix -L develop` registers the custom GHC to the host Nix's garbage-collector
  84 in `haskell/cache/gc-roots/ghcjs-ghc`,
  85 manually remove this symbolic link to let `nix-collect-garbage` reclaim it.
  86
  87 ## ToDo
  88
  89 - SecurityToDo: sign the APK.