diff --git a/README.md b/README.md index 07b6e13..441511d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ![Rule enforcer](https://github.com/LedgerHQ/app-boilerplate-rust/actions/workflows/guidelines_enforcer.yml/badge.svg) ![Build and tests](https://github.com/LedgerHQ/app-boilerplate-rust/actions/workflows/build_and_functional_tests.yml/badge.svg) -This is a boilerplate application written in Rust which can be forked to start a new project for the Ledger Nano X/SP, Stax and Flex devices. +This is a boilerplate application written in Rust which can be forked to start a new project for the Ledger Nano X, S+, Stax and Flex devices. :warning: Nano S is not supported @@ -42,88 +42,80 @@ By using Ledger's own developer tools [Docker image](https://github.com/LedgerHQ ### Prerequisites -If you do not wish to use the [VS Code extension](#with-vs-code), you can follow the following steps to setup a development environment on Linux or MacOS. - -The [ledger-app-dev-tools](https://github.com/LedgerHQ/ledger-app-builder/pkgs/container/ledger-app-builder%2Fledger-app-dev-tools) Docker image contains all the required tools and libraries to build, test and load an application on a device. - -You can download it from the ghcr.io docker repository: +If you do not wish to use the [VS Code extension](#with-vs-code), you can follow the following steps to setup a development environment on Linux, Windows or MacOS. +* The [ledger-app-dev-tools](https://github.com/LedgerHQ/ledger-app-builder/pkgs/container/ledger-app-builder%2Fledger-app-dev-tools) Docker image contains all the required tools and libraries to build, test and load an application on a device. You can download it from the ghcr.io docker repository: ```shell sudo docker pull ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest ``` - -You can then enter into this development environment by executing the following command from the directory of the application (`git` repository): - -**Linux (Ubuntu)** - -```shell -sudo docker run --rm -ti --privileged -v "/dev/bus/usb:/dev/bus/usb" -v "$(realpath .):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest -``` - -**macOS** - -```shell -sudo docker run --rm -ti --privileged -v "$(pwd -P):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest -``` - -**Windows (with PowerShell)** - -```shell -docker run --rm -ti --privileged -v "$(Get-Location):/app" ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest -``` +* Make sure you have an X11 server running : + * On Ubuntu Linux, it should be running by default. + * On macOS, install and launch [XQuartz](https://www.xquartz.org/) (make sure to go to XQuartz > Preferences > Security and check "Allow client connections"). + * On Windows, install and launch [VcXsrv](https://sourceforge.net/projects/vcxsrv/) (make sure to configure it to disable access control). +* You can then enter into this development environment by executing the following command from the directory of the application (`git` repository): + * Linux (Ubuntu): + ```shell + sudo docker run --rm -ti --privileged -v "/dev/bus/usb:/dev/bus/usb" -v "$(realpath .):/app" --publish 5001:5001 --publish 9999:9999 -e DISPLAY=$DISPLAY -v '/tmp/.X11-unix:/tmp/.X11-unix' ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest + ``` + * macOS: + ```shell + sudo docker run --rm -ti --privileged -v "$(pwd -P):/app" --publish 5001:5001 --publish 9999:9999 -e DISPLAY='host.docker.internal:0' -v '/tmp/.X11-unix:/tmp/.X11-unix' ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest + ``` + * Windows (with PowerShell): + ```shell + docker run --rm -ti --privileged -v "$(Get-Location):/app" -e DISPLAY='host.docker.internal:0' --publish 5001:5001 --publish 9999:9999 ghcr.io/ledgerhq/ledger-app-builder/ledger-app-dev-tools:latest + ``` The application's code will be available from inside the docker container, you can proceed to the following compilation steps to build your app. ### Building You can build the boilerplate with the following command executed in the root directory of the app. - ```bash cargo ledger build nanox ``` - This command will build the app for the Nano X, but you can use any supported device (`nanox`, `nanosplus`, `stax`, `flex`) -### Loading - -ℹ️ Your device must be connected, unlocked and the screen showing the dashboard (not inside an application). - -[cargo-ledger](https://github.com/LedgerHQ/cargo-ledger) also allows you to side load the binary with the following command line executed in the root directory of the boilerplate app. - -```bash -cargo ledger build nanox --load -``` - -As for the build command, you can replace `nanox` with `nanosplus`, `stax` or `flex`. - -## Test - -### Ragger functional tests - +### Testing +#### Ragger functional tests This boilerplate app comes with functional tests implemented with Ledger's [Ragger](https://github.com/LedgerHQ/ragger) test framework. * Install the tests requirements - ```bash pip install -r tests/requirements.txt ``` - * Run the functional tests : ```shell pytest tests/ --tb=short -v --device {nanosp | nanox | stax | flex} ``` - -### Emulator - -You can also run the app directly on the [Speculos emulator](https://github.com/LedgerHQ/speculos) - +#### Emulator +You can also run the app directly on the [Speculos emulator](https://github.com/LedgerHQ/speculos) from the Docker container +#### Nano S+ or X +```bash +speculos --apdu-port 9999 --api-port 5001 --display headless --model nanosp target/nanosplus/release/app-boilerplate-rust +``` +:warning: UI is displayed on `localhost::5001` +#### Stax or Flex +```bash +speculos --apdu-port 9999 --api-port 5001 --model stax target/stax/release/app-boilerplate-rust +``` +:warning: UI is displayed by your X server +You can then send APDU using `ledgercomm`: +``` +ledgercomm-send file test.apdu +``` +### Loading on device +:warning: Loading the built application on a device shall be performed out of the Docker container, by using [ledgerctl](https://github.com/LedgerHQ/ledgerctl): +```shell +pip3 install ledgerwallet +```` +ℹ️ Your device must be connected, unlocked and the screen showing the dashboard (not inside an application). For instance, for Flex: ```bash -speculos --model nanox target/nanox/release/app-boilerplate-rust +ledgerctl install -f target/stax/release/app_flex.json ``` ## Continuous Integration - The following workflows are executed in [GitHub Actions](https://github.com/features/actions) : * Ledger guidelines enforcer which verifies that an app is compliant with Ledger guidelines. The successful completion of this reusable workflow is a mandatory step for an app to be available on the Ledger application store. More information on the guidelines can be found in the repository [ledger-app-workflow](https://github.com/LedgerHQ/ledger-app-workflows) @@ -131,4 +123,4 @@ The following workflows are executed in [GitHub Actions](https://github.com/feat * End-to-end tests with the [Speculos](https://github.com/LedgerHQ/speculos) emulator and [ragger](https://github.com/LedgerHQ/ragger) (see [tests/](tests/)) * Various lint checks : * Source code lint checks with `cargo fmt` - * Python functional test code lint checks with `pylint` and `mypy` + * Python functional test code lint checks with `pylint` and `mypy` \ No newline at end of file