Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update readme #103

Merged
merged 2 commits into from
Jan 17, 2025
Merged

Update readme #103

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3dccf4b
Update readme
yogh333 Jan 17, 2025
8cf6d74
update and fix typo
yogh333 Jan 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 47 additions & 52 deletions README.md
View file
Open in desktop
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,88 @@ 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) 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

### Emulator

You can also run the app directly on the [Speculos emulator](https://github.com/LedgerHQ/speculos)
You can then send APDU using `ledgercomm` (`pip install 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/flex/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`
Loading