Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@yogh333
yogh333 committed Jan 17, 2025
1 parent c1e8a9b commit 3dccf4b
Showing 1 changed file with 46 additions and 54 deletions.
100 changes: 46 additions & 54 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -42,93 +42,85 @@ 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)
* Compilation of the application for all supported devices in the [ledger-app-builder](https://github.com/LedgerHQ/ledger-app-builder) docker image
* 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`

0 comments on commit 3dccf4b

Please sign in to comment.