Skip to content

Commit d32bb9a

Browse files
toastmanAutoastmanAu
committed
feat: add Linux arm64 AppImage support
1 parent b0998f3 commit d32bb9a

File tree

3 files changed

+151
-4
lines changed

3 files changed

+151
-4
lines changed

‎ARM64_PR.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Add Linux arm64 (aarch64) AppImage support
2+
3+
## Summary
4+
5+
This PR adds support for building Neuron as a Linux arm64 AppImage, targeting Raspberry Pi 4/5, Orange Pi, ROCK series boards and other aarch64 single-board computers running Linux — which are popular in the CKB node-running community.
6+
7+
A working `Neuron-v0.204.0-arm64.AppImage` (192 MB, verified ELF aarch64) was built successfully on an Orange Pi 5 (aarch64, Ubuntu 22.04) using the changes in this PR.
8+
9+
---
10+
11+
## Changes
12+
13+
### 1. `scripts/download-ckb.sh` — add `download_linux_aarch64()`
14+
15+
Added a new function that downloads the `aarch64-unknown-linux-gnu` CKB binary (which already exists in every CKB release) and saves it as `bin/linux/ckb-arm64`:
16+
17+
```bash
18+
function download_linux_aarch64() {
19+
CKB_FILENAME="ckb_${CKB_VERSION}_aarch64-unknown-linux-gnu"
20+
cd $ROOT_DIR/packages/neuron-wallet/bin/linux
21+
curl -O -L "${GITHUB_RELEASE_URL}/${CKB_VERSION}/${CKB_FILENAME}.tar.gz"
22+
tar xvzf ${CKB_FILENAME}.tar.gz
23+
cp ${CKB_FILENAME}/ckb ./ckb-arm64
24+
rm -rf $CKB_FILENAME ${CKB_FILENAME}.tar.gz
25+
}
26+
```
27+
28+
Also added a `linux-arm64` case to the switch:
29+
```bash
30+
linux-arm64) download_linux_aarch64; download_linux_light;;
31+
```
32+
33+
> **Note on `ckb-light-client`**: No arm64 Linux release exists in the `ckb-light-client` repo yet. The x86_64 binary is currently used for both architectures. A separate issue/PR to the `ckb-light-client` repo would complete that gap.
34+
35+
### 2. `packages/neuron-wallet/electron-builder.yml` — add arm64 target + extraFile
36+
37+
```yaml
38+
linux:
39+
extraFiles:
40+
- from: "bin/linux/ckb"
41+
to: "bin/ckb"
42+
- from: "bin/linux/ckb-arm64" # ← new
43+
to: "bin/ckb-arm64"
44+
# ... rest unchanged
45+
target:
46+
- target: AppImage
47+
arch:
48+
- x64
49+
- arm64 # ← new
50+
```
51+
52+
### 3. `package.yml` (GitHub Actions) — add arm64 Linux runner
53+
54+
To build the arm64 AppImage in CI, add an `ubuntu-24.04-arm` runner to the matrix:
55+
56+
```yaml
57+
jobs:
58+
default:
59+
strategy:
60+
matrix:
61+
node: [22]
62+
os:
63+
- macos-latest
64+
- ubuntu-latest
65+
- ubuntu-24.04-arm # ← new: GitHub's hosted arm64 runner
66+
- windows-latest
67+
```
68+
69+
And add a conditional upload step:
70+
```yaml
71+
- name: Upload Neuron Linux arm64
72+
if: runner.os == 'Linux' && runner.arch == 'ARM64'
73+
uses: actions/upload-artifact@v4
74+
with:
75+
name: Neuron-Linux-arm64
76+
path: release/Neuron-*-arm64.AppImage
77+
```
78+
79+
---
80+
81+
## Build instructions (manual, on arm64 Linux)
82+
83+
```bash
84+
# Prerequisites
85+
sudo apt-get install -y libudev-dev libusb-1.0-0-dev fuse libfuse2 rpm python3-setuptools
86+
87+
# Clone and install
88+
git clone https://github.com/nervosnetwork/neuron.git
89+
cd neuron
90+
yarn global add lerna
91+
CI=false yarn
92+
yarn build
93+
./scripts/copy-ui-files.sh
94+
95+
# Download CKB binaries (both x64 and arm64)
96+
./scripts/download-ckb.sh linux
97+
98+
# Build AppImage for arm64
99+
cd packages/neuron-wallet
100+
npx electron-builder --linux --arm64 --config.npmRebuild=false
101+
```
102+
103+
Output: `release/Neuron-v{version}-arm64.AppImage`
104+
105+
**Flags explained:**
106+
- `--linux --arm64`: target platform and architecture
107+
- `--config.npmRebuild=false`: skip native module rebuild (avoids cross-compilation issues when building arm64 on an arm64 host where modules are already built for the right arch)
108+
109+
---
110+
111+
## Tested on
112+
113+
| Device | OS | Result |
114+
|--------|-----|--------|
115+
| Orange Pi 5 (RK3588S) | Ubuntu 22.04 arm64 | ✅ `Neuron-v0.204.0-arm64.AppImage` built, 192 MB |
116+
117+
The resulting AppImage is a valid ELF aarch64 executable:
118+
```
119+
ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked,
120+
interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 3.7.0, stripped
121+
```
122+
123+
---
124+
125+
## Why this matters
126+
127+
Single-board computers (Raspberry Pi 4/5, Orange Pi, Rock Pi, etc.) are widely used to run CKB full nodes — they're low-power, always-on, and affordable. Many CKB community members running nodes on these devices also want to use Neuron as their wallet but currently have no official binary. An arm64 AppImage closes that gap with a single self-contained download.

‎packages/neuron-wallet/electron-builder.yml‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,11 +88,18 @@ linux:
8888
extraFiles:
8989
- from: "bin/linux/ckb"
9090
to: "bin/ckb"
91+
filter: "**/*"
92+
- from: "bin/linux/ckb-arm64"
93+
to: "bin/ckb-arm64"
94+
filter: "**/*"
9195
- from: "bin/linux/ckb-light-client"
9296
to: "bin/ckb-light-client"
9397
- from: "light/ckb_light_testnet.toml"
9498
to: "light/ckb_light_testnet.toml"
9599
- from: "light/ckb_light_mainnet.toml"
96100
to: "light/ckb_light_mainnet.toml"
97101
target:
98-
- AppImage
102+
- target: AppImage
103+
arch:
104+
- x64
105+
- arm64

‎scripts/download-ckb.sh‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ function download_macos_light() {
4848
}
4949

5050
function download_linux() {
51-
# Linux
51+
# Linux x86_64
5252
CKB_FILENAME="ckb_${CKB_VERSION}_x86_64-unknown-linux-gnu-portable"
5353
cd $ROOT_DIR/packages/neuron-wallet/bin/linux
5454

@@ -59,8 +59,20 @@ function download_linux() {
5959
rm ${CKB_FILENAME}.tar.gz
6060
}
6161

62+
function download_linux_aarch64() {
63+
# Linux arm64
64+
CKB_FILENAME="ckb_${CKB_VERSION}_aarch64-unknown-linux-gnu"
65+
cd $ROOT_DIR/packages/neuron-wallet/bin/linux
66+
67+
curl -O -L "${GITHUB_RELEASE_URL}/${CKB_VERSION}/${CKB_FILENAME}.tar.gz"
68+
tar xvzf ${CKB_FILENAME}.tar.gz
69+
cp ${CKB_FILENAME}/ckb ./ckb-arm64
70+
rm -rf $CKB_FILENAME
71+
rm ${CKB_FILENAME}.tar.gz
72+
}
73+
6274
function download_linux_light() {
63-
# macOS
75+
# Linux light client (x86_64 only — no arm64 release yet)
6476
CKB_FILENAME="ckb-light-client_${CKB_LIGHT_VERSION}-x86_64-linux-portable"
6577
cd $ROOT_DIR/packages/neuron-wallet/bin/linux
6678

@@ -99,7 +111,8 @@ function download_windows_light() {
99111

100112
case $1 in
101113
mac) download_macos; download_macos_light;;
102-
linux) download_linux; download_linux_light;;
114+
linux) download_linux; download_linux_aarch64; download_linux_light;;
115+
linux-arm64) download_linux_aarch64; download_linux_light;;
103116
win) download_windows; download_windows_light;;
104117
*)
105118
if [[ "$OSTYPE" == "darwin"* ]]; then

0 commit comments

Comments
 (0)