README (7767B)
1 # GNU Taler Wallet & Anastasis Web UI 2 3 This repository contains the implementation of a wallet for GNU Taler written 4 in TypeScript and Anastasis Web UI 5 6 ## Dependencies 7 8 The following dependencies are required to build the wallet: 9 10 - python>=3.8 11 - nodejs>=20 12 - jq 13 - npm 14 - pnpm>=11.1.2 15 - zip 16 17 Note that you can install pnpm as an unprivileged user by running 18 19 ```shell 20 npm config set prefix $HOME/.npm-global 21 export PATH=$HOME.npm-global/bin:$PATH 22 npm install -g pnpm 23 ``` 24 25 ## Preparing the repository 26 27 After running clone you should bootstrap the repository. 28 29 ```shell 30 ./bootstrap 31 ``` 32 33 ## Installation 34 35 The CLI version of the wallet supports the normal GNU installation process. 36 37 ```shell 38 ./bootstrap 39 ./configure [ --prefix=$PREFIX ] && make install 40 ``` 41 42 ### Compiling from Git 43 44 If you are compiling the code from git, you have to run `./bootstrap` before 45 running `./configure`. 46 47 ### Build versions and source archives 48 49 All package manifests use version `0.0.0` and are private. Build versions come 50 from the shared repository tags, with the leading `v` removed. Commits after a 51 tag include the distance and commit hash. Inspect the version with 52 `node build-system/version-cli.mjs` (or add `--json` for the tag and full hash). 53 54 Git builds require a reachable release tag. Fetch missing tags with 55 `git fetch --tags`; shallow clones may also need `git fetch --unshallow`. 56 57 `make dist` and `make dist-git` include generated `build-info.json` metadata in 58 the source archive. Builds from these archives retain the same version and 59 commit hash without requiring Git. Source copies missing both Git metadata and 60 `build-info.json` cannot provide a build version. The metadata is generated only 61 inside the archive and is not maintained or committed by hand. 62 63 ## Pushing a new prebuilt version 64 65 After compiling run 66 67 ```shell 68 make prebuilt 69 ``` 70 71 This will create a directory `prebuilt` with a git subtree, 72 build every prebuilt project, copy everything into this subtree 73 and create a commit with the default message mentioning from 74 which revision the prebuilt was created. 75 When the script completes the prebuilt version can should 76 be manually pushed. 77 78 ```shell 79 cd prebuilt 80 git push 81 ``` 82 83 ### Building the WebExtension 84 85 The WebExtension can be built via the 'webextension' make target: 86 87 ```shell 88 ./configure && make webextension 89 ``` 90 91 This creates the browser-specific WebExtension ZIP files in 92 93 ``` 94 packages/wallet-webui/dist/extension/ 95 ``` 96 97 The Chrome and Firefox archives are named 98 `taler-wallet-<browser>-<version>.zip`. The corresponding unpacked builds are 99 in the `chrome/` and `firefox/` subdirectories. 100 101 ### Installing local WebExtension 102 103 Firefox: 104 - Settings 105 - Add-ons 106 - Manage your extension -> Debug Add-ons 107 - Load temporary Add-on... 108 - Select the Firefox zip under `packages/wallet-webui/dist/extension/` 109 110 Chrome: 111 - Settings 112 - More tools 113 - Extensions 114 - Load unpacked 115 - Select `packages/wallet-webui/dist/extension/chrome/` 116 117 ### Reviewing WebExtension UI examples 118 119 The wallet UI includes a searchable story catalogue. To run the development 120 server use: 121 122 ```shell 123 make webextension-dev 124 ``` 125 126 Open the Storybook route from the running wallet to review the registered 127 fixtures in `packages/wallet-webui/src/stories/`. 128 129 ### WebExtension UI Components 130 131 Every group of component have a directory and a README. 132 Testing component is based in two main category: 133 134 - UI testing 135 - State transition testing 136 137 For UI testing, every story example will be taken as a unit test. 138 For State testing, every stateful component should have an `useStateComponent` function that will be tested in a \*.test.ts file. 139 140 ### Testing WebExtension 141 142 After building the WebExtension, use the browser-specific output under 143 `packages/wallet-webui/dist/extension/`. 144 145 Firefox users: 146 147 - Go to about:addons 148 - Then `debug addon` (or about:debugging#/runtime/this-firefox) 149 - Then `Load temporary addon...` 150 - Select the `taler-wallet-firefox-*.zip` 151 152 Chrome users: 153 154 - Settings -> More tools -> Extensions (or go to chrome://extensions/) 155 - `Load unpacked` button in the upper left 156 - Select `packages/wallet-webui/dist/extension/chrome/` 157 158 ## Unit and package tests 159 160 Run the repository check from a clean set of generated files with: 161 162 ```shell 163 make check 164 ``` 165 166 The command builds the workspace, runs every package test command, continues 167 after package failures, and prints one summary at the end. To rerun only one 168 package while working, use its workspace name, for example: 169 170 ```shell 171 pnpm --filter @gnu-taler/taler-wallet-core test 172 ``` 173 174 Package test commands are responsible for removing their own generated test 175 output, so direct package runs cannot pick up JavaScript left behind by an 176 older source tree. See the [test runner design](doc/testrunner.md) for the 177 output, isolation, and generated-file conventions. 178 179 ## Release checks 180 181 Before making a release, run the build, unit tests, linter, spelling checker and 182 internationalized catalogue checks with: 183 184 ```shell 185 make check-release-fast 186 ``` 187 188 This requires GNU gettext and a clean set of checked-in files under 189 `packages/*/src/i18n/`. The target regenerates the gettext templates, merges the 190 PO files and emits each `strings.ts`; it fails and leaves the regenerated files 191 in place when the checked-in output was stale. 192 193 The full release check additionally runs all non-experimental integration tests: 194 195 ```shell 196 make check-release 197 ``` 198 199 It needs the same installed Taler services and test dependencies described 200 below for running the integration tests directly. 201 202 # Integration Tests 203 204 This repository comes with integration tests for GNU Taler. To run them, 205 install the wallet first. Then use the test runner from the 206 taler-integrationtests package: 207 208 ```shell 209 # List available tests 210 taler-wallet-cli testing list-integrationtests 211 212 # Run all tests 213 taler-wallet-cli testing run-integrationtests 214 215 # Run all tests matching pattern 216 taler-wallet-cli testing run-integrationtests $GLOB 217 218 $ Run all tests from a suite 219 taler-wallet-cli testing run-integrationtests --suites=wallet 220 ``` 221 222 The test runner accepts a bash glob pattern as parameter. Individual tests can 223 be run by specifying their name. 224 225 To check coverage, use c8 from the root of the repository and make sure that the taler-wallet-cli 226 from the source tree is executed, and not the globally installed one: 227 228 ``` 229 c8 ./packages/taler-wallet-cli/bin/taler-wallet-cli '*' 230 ``` 231 232 ## Minimum required browser for WebEx 233 234 The extension manifests, including Firefox's minimum supported version, are 235 generated by `packages/wallet-webui/manifest.mjs`. 236 237 ## Anastasis Web UI 238 239 ## Building for deploy 240 241 To build the Anastasis SPA run: 242 243 ```shell 244 make anastasis-webui 245 ``` 246 247 It will run the test suite and put everything into the dist folder under the project root (packages/anastasis-webui). 248 You can copy the SPA directly to work local webserver. 249 250 ```shell 251 cp -Tr ./packages/anastasis-webui/dist/prod /var/www/html/anastasis 252 ``` 253 254 Additionally you can create a zip file with the content to upload into a web server: 255 256 ```shell 257 make anastasis-webui-dist 258 ``` 259 260 It creates the zip file named `anastasis-webui.zip` 261 262 ## Building explored release in a container 263 264 First create a container with a base image, copy the release tar file and get inside the virtual machine. 265 266 ```shell 267 podman pull ubuntu:24.04 268 podman container create --name builder ubuntu:24.04 sleep infinity 269 podman container start builder 270 podman container cp taler-wallet-v*.tar.gz builder:/root/ 271 podman exec -it -w /root builder /bin/bash 272 ``` 273 274 Then inside the vm make sure you have the required software and follow the instruction for building. 275 276 Installing requirements 277 278 ```shell 279 apt update && apt install -y nodejs curl vim less python3 make zip jq npm 280 npm install --global corepack 281 tar xzf taler-wallet-v*.tar.gz 282 cd taler-wallet-v*/ 283 corepack enable pnpm 284 pnpm --version 285 ```