quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

README.md (4206B)

      1 # QuickJS Taler Runtime (qtart)
      2 
      3 This repository contains qtart, a JavaScript runtime for the GNU Taler wallet
      4 based on Fabrice Bellard's QuickJS. The runtime is statically linked.
      5 
      6 ## Building
      7 
      8 Prerequisite dependencies:
      9 - `wget`
     10 - `meson`
     11 - `ninja`
     12 - `gcc` or `clang`
     13 - `git`
     14 
     15 Building also requires the `taler-wallet-core-qjs.mjs` file to be
     16 present in the top-level of this repository. You can build this file
     17 from the `taler-typescript-core.git` repository by running `make
     18 embedded` once the project is configured; the resulting file may then
     19 be found in `packages/taler-wallet-embedded/dist/` and should be
     20 copied into this directory.
     21 
     22 The following commands build the project and place resulting files
     23 in the `build/` directory:
     24 
     25 ```sh
     26 meson setup build
     27 meson compile -C build
     28 ```
     29 
     30 ## Cross-compiling
     31 
     32 ### Android
     33 
     34 #### Publish to local Maven repository for testing
     35 
     36 In order to test locally, you can use the `./cross/package-android.sh`
     37 script and pass the desired architecture, as well as specify whether
     38 the Gradle package should be published locally or not.
     39 
     40 ```sh
     41 ./cross/package-android.sh all    # build for all architectures
     42 ./cross/package-android.sh x86    # build only for x86
     43 ./cross/package-android.sh x86_64 # build only for x86_64
     44 ./cross/package-android.sh arm64  # build only for arm64
     45 ./cross/package-android.sh gradle # only publish to local Gradle
     46 ```
     47 
     48 In order to test the Taler wallet against this local build, add the
     49 following line to the project-level `build.gradle` file:
     50 
     51 ```groovy
     52 // taler-android.git/build.gradle
     53 allprojects {
     54     repositories {
     55         mavenLocal()
     56         // ...
     57     }
     58 }
     59 ```
     60 
     61 _**NOTE:** a distinctive suffix should be added to the `VERSION_NAME`
     62 in `Quickjs-android/gradle.properties` **before** building, and
     63 referenced in `wallet/build.gradle` in order to prevent Gradle from
     64 fetching the dependency from Maven Central._
     65 
     66 ```properties
     67 # quickjs-tart.git/QuickJS-android/gradle.properties
     68 VERSION_NAME=1.0.28-local
     69 ```
     70 
     71 ```groovy
     72 // taler-android.git/wallet/build.gradle
     73 def qtart_version = "1.0.28-local"
     74 ```
     75 
     76 #### Publish to Maven central
     77 
     78 See `docker-android/README.md`
     79 
     80 ### iOS
     81 
     82 ```
     83 ./cross/package-ios.sh
     84 ```
     85 
     86 This script will generate a `.xcframework` file under the `build-ios/`
     87 directory , which should be copied to the Taler iOS Xcode project
     88 under the `Frameworks/` directory and added to all wallet targets
     89 (e.g. `GNU Taler`, `Taler Wallet`, `Taler Nightly`).
     90 
     91 In order to build only for certain platforms, you can edit the
     92 `cross/package-ios.sh` directory and comment out the platforms that
     93 you don't want, for instance:
     94 
     95 ```bash
     96 targets=(
     97     iphoneos-arm64
     98     iphonesimulator-arm64
     99     iphonesimulator-x86_64
    100     # macosx-arm64
    101     # macosx-x86_64
    102 )
    103 ```
    104 
    105 _**NOTE:** you cannot pick individual architectures for a given
    106 platform, you must comment out ALL architectures for the platform that
    107 you don't want to build for._
    108 
    109 ## Architecture
    110 
    111 Infra:
    112 
    113 - The `tart` native quickjs module provides Taler-specific runtime functionalty for the wallet.
    114 - The `std` and `os` modules are extended with functionality needed by the wallet,
    115   such as a curl-based HTTP client and file access.
    116 - `prelude.js` adapts the global environment to enable the wallet JS to run
    117 - `taler-wallet-core-qjs.mjs` is the bundled taler-wallet-core.
    118 
    119 Programs/interfaces:
    120 - `$builddir/qtart` provides a JS interpreter and REPL with a bundled taler-wallet-core.
    121   It is mainly used for testing and benchmarking.
    122 - `$builddir/libtalerwalletcore.so` 
    123 - `taler_wallet_core_lib.h` declares the symbols exported by `libtalerwalletcore.so`
    124 - `wallet-client-example.c` is an example client for `libtalerwalletcore.so`
    125 
    126 ## To Do
    127 
    128 - We might leak memory in some places
    129 
    130 ## Repository Structure
    131 
    132 - `quickjs/`: A slightly modified version of Fabrice Bellard's QuickJS interpreter.
    133 We try to keep modifications as small as possible in this part of the code.
    134 - `subprojects/`: Vendored dependencies.  Only the build systems of these dependencies
    135 should be modified, not any of the code, if at all possible.
    136 
    137 ## Usage / Examples
    138 
    139 Run test with `localhost` deployment:
    140 
    141 ```
    142 ./qtart -e 'testWithLocal()'
    143 ```
    144 
    145 Run test with `taler.net` deployment:
    146 
    147 ```
    148 ./qtart -e 'testWithGv()'
    149 ```