verify-16k-page-align 0.0.1 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +1 -1
- package/README.md +123 -56
- package/package.json +18 -9
- package/src/verify-16k-page-align.sh +18 -14
package/LICENSE.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
Copyright (c) since
|
|
1
|
+
Copyright (c) since 2025 @hotbrainstech
|
|
2
2
|
|
|
3
3
|
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
4
4
|
|
package/README.md
CHANGED
|
@@ -2,30 +2,51 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/verify-16k-page-align)
|
|
4
4
|
[](LICENSE.md)
|
|
5
|
-
[](#platform-support)
|
|
6
6
|
|
|
7
|
-
A shell script and npm package to verify if your Android APK/AAB native libraries are aligned to 16KB
|
|
7
|
+
A shell script and npm package to verify if your Android APK/AAB/APEX native libraries are aligned to 16KB or 64KB memory pages. This is required for compatibility with Android 15+ devices and Google Play submissions after **November 1, 2025** ([see official docs](https://developer.android.com/guide/practices/page-sizes?hl=pt-br)).
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Features](#features)
|
|
14
|
+
- [Why 16KB Page Alignment?](#why-16kb-page-alignment)
|
|
15
|
+
- [Installation](#installation)
|
|
16
|
+
- [Usage](#usage)
|
|
17
|
+
- [CI/CD Integration](#cicd-integration)
|
|
18
|
+
- [How It Works](#how-it-works)
|
|
19
|
+
- [Platform Support](#platform-support)
|
|
20
|
+
- [Requirements](#requirements)
|
|
21
|
+
- [Migration Guide](#migration-guide)
|
|
22
|
+
- [Troubleshooting](#troubleshooting)
|
|
23
|
+
- [FAQ](#faq)
|
|
24
|
+
- [Contributing](#contributing)
|
|
25
|
+
- [References](#references-further-reading)
|
|
26
|
+
- [Support](#show-your-support)
|
|
27
|
+
- [License](#license)
|
|
8
28
|
|
|
9
29
|
---
|
|
10
30
|
|
|
11
31
|
## Features
|
|
12
32
|
|
|
13
|
-
- Checks all native `.so` libraries in APK
|
|
14
|
-
-
|
|
15
|
-
- Uses `
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
33
|
+
- Checks all native `.so` libraries in **APK**, **AAB**, and **APEX** files for 16KB or 64KB page alignment.
|
|
34
|
+
- Supports scanning extracted directories containing native libraries.
|
|
35
|
+
- Uses `objdump` to analyze ELF program headers.
|
|
36
|
+
- **CI/CD Ready**: Returns exit code `1` on failure, `0` on success.
|
|
37
|
+
- Includes APK zip-alignment verification (requires Android build-tools 35.0.0-rc3+).
|
|
38
|
+
- Fast, zero dependencies (besides unzip/objdump).
|
|
39
|
+
- CLI and npm global install.
|
|
40
|
+
- Supports both `arm64-v8a` and `x86_64` architectures.
|
|
19
41
|
|
|
20
42
|
---
|
|
21
43
|
|
|
22
44
|
## Why 16KB Page Alignment?
|
|
23
45
|
|
|
24
|
-
Starting with Android 15, many devices will use 16KB memory pages for improved performance and reliability. All apps targeting Android 15+ and distributed via Google Play **must** ensure their native libraries (`.so` files) are 16KB aligned. See:
|
|
46
|
+
Starting with Android 15, many devices will use 16KB memory pages for improved performance and reliability. All apps targeting Android 15+ and distributed via Google Play **must** ensure their native libraries (`.so` files) are 16KB or 64KB aligned. See:
|
|
25
47
|
- [Android Developers: 16 KB Page Size](https://developer.android.com/guide/practices/page-sizes?hl=pt-br)
|
|
26
48
|
- [Google Play Blog: Prepare for 16 KB page size](https://android-developers.googleblog.com/2025/05/prepare-play-apps-for-devices-with-16kb-page-size.html)
|
|
27
49
|
- [Medium: Android 15 Mandatory 16KB Memory Page Size](https://devharshmittal.medium.com/android-15-is-raising-the-bar-mandatory-16kb-memory-page-size-what-developers-need-to-know-4dd81ec58f67)
|
|
28
|
-
- [Reddit discussion](https://www.reddit.com/r/brdev/comments/1nl3fx4/android_15_seus_apps_j%C3%A1_est%C3%A3o_prontos_para_16kb/)
|
|
29
50
|
|
|
30
51
|
**Benefits:**
|
|
31
52
|
- Faster app launches (3–30% improvement)
|
|
@@ -51,94 +72,141 @@ sudo npm i -g verify-16k-page-align
|
|
|
51
72
|
|
|
52
73
|
## Usage
|
|
53
74
|
|
|
54
|
-
|
|
55
|
-
### Check an APK or AAB file
|
|
75
|
+
### Check an APK, AAB, or APEX file
|
|
56
76
|
By default, only `arm64-v8a` libraries are checked. To also check `x86_64` libraries, add `x86` as a second argument.
|
|
57
77
|
|
|
78
|
+
#### Using NPM package
|
|
58
79
|
```sh
|
|
59
80
|
# Default: check arm64-v8a only
|
|
60
|
-
verify-16k-page-align
|
|
81
|
+
verify-16k-page-align path/to/app.apk
|
|
82
|
+
verify-16k-page-align path/to/app.aab
|
|
61
83
|
|
|
62
84
|
# Check arm64-v8a and x86_64
|
|
63
|
-
verify-16k-page-align
|
|
85
|
+
verify-16k-page-align path/to/app.apk x86
|
|
64
86
|
```
|
|
65
87
|
|
|
66
|
-
|
|
88
|
+
#### Using local script
|
|
89
|
+
Make sure the script is executable:
|
|
67
90
|
```sh
|
|
68
|
-
|
|
69
|
-
sh ./src/verify-16k-page-align.sh <path-to-apk-or-aab>
|
|
91
|
+
chmod +x ./src/verify-16k-page-align.sh
|
|
70
92
|
|
|
71
|
-
#
|
|
72
|
-
|
|
93
|
+
# Run
|
|
94
|
+
./src/verify-16k-page-align.sh path/to/app.apk
|
|
73
95
|
```
|
|
74
96
|
|
|
75
|
-
|
|
97
|
+
### Check a directory
|
|
98
|
+
You can also run the script against a directory containing extracted native libraries (must follow `lib/arm64-v8a/` structure).
|
|
99
|
+
|
|
76
100
|
```sh
|
|
77
|
-
|
|
78
|
-
# Default: check arm64-v8a only
|
|
79
|
-
./src/verify-16k-page-align.sh <path-to-apk-or-aab>
|
|
80
|
-
# Check arm64-v8a and x86_64
|
|
81
|
-
./src/verify-16k-page-align.sh <path-to-apk-or-aab> x86
|
|
101
|
+
verify-16k-page-align path/to/extracted/libs
|
|
82
102
|
```
|
|
83
103
|
|
|
84
|
-
|
|
104
|
+
### Example Output
|
|
105
|
+
|
|
85
106
|
```
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
107
|
+
=== APK zip-alignment ===
|
|
108
|
+
lib/arm64-v8a/libfoo.so: 16384 (OK - 16KB aligned)
|
|
109
|
+
lib/arm64-v8a/libbar.so: 4096 (BAD - 4KB aligned)
|
|
110
|
+
Verification FAILED
|
|
111
|
+
=========================
|
|
112
|
+
|
|
113
|
+
=== ELF alignment ===
|
|
114
|
+
lib/arm64-v8a/libfoo.so: ALIGNED (2**14)
|
|
115
|
+
lib/arm64-v8a/libbar.so: UNALIGNED (2**12)
|
|
116
|
+
Found 1 unaligned libs (only arm64-v8a/x86_64 libs need to be aligned).
|
|
117
|
+
=====================
|
|
94
118
|
```
|
|
95
119
|
|
|
96
|
-
|
|
97
|
-
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## CI/CD Integration
|
|
123
|
+
|
|
124
|
+
This tool is designed for CI/CD pipelines. It returns a non-zero exit code if verification fails.
|
|
125
|
+
|
|
126
|
+
### GitHub Actions Example
|
|
127
|
+
|
|
128
|
+
```yaml
|
|
129
|
+
name: Verify 16KB Alignment
|
|
130
|
+
|
|
131
|
+
on: [push, pull_request]
|
|
132
|
+
|
|
133
|
+
jobs:
|
|
134
|
+
verify-alignment:
|
|
135
|
+
runs-on: ubuntu-latest
|
|
136
|
+
steps:
|
|
137
|
+
- uses: actions/checkout@v3
|
|
138
|
+
|
|
139
|
+
# Install dependencies (objdump is usually present, but just in case)
|
|
140
|
+
- name: Install dependencies
|
|
141
|
+
run: sudo apt-get update && sudo apt-get install -y binutils unzip
|
|
142
|
+
|
|
143
|
+
- name: Install verify-16k-page-align
|
|
144
|
+
run: sudo npm i -g verify-16k-page-align
|
|
145
|
+
|
|
146
|
+
- name: Verify APK
|
|
147
|
+
run: verify-16k-page-align path/to/your-app-release.apk
|
|
148
|
+
```
|
|
98
149
|
|
|
99
150
|
---
|
|
100
151
|
|
|
101
152
|
## How It Works
|
|
102
153
|
|
|
103
|
-
1.
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
154
|
+
1. **Extraction**:
|
|
155
|
+
- For **APK/AAB**: Unzips `lib/` directory to a temporary location.
|
|
156
|
+
- For **APEX**: Uses `deapexer` to extract contents.
|
|
157
|
+
2. **APK Zip Alignment**: If checking an APK and `zipalign` is available (build-tools 35.0.0-rc3+), verifies 16KB zip alignment.
|
|
158
|
+
3. **ELF Analysis**: Scans all `.so` files using `objdump` to inspect ELF program headers.
|
|
159
|
+
4. **Validation**: Checks if `LOAD` segments are aligned to 16KB (`2**14`) or 64KB (`2**16`).
|
|
160
|
+
5. **Result**:
|
|
161
|
+
- Prints status for each library.
|
|
162
|
+
- Exits with `1` if any unaligned libraries are found.
|
|
107
163
|
|
|
108
164
|
---
|
|
109
165
|
|
|
110
166
|
## Platform Support
|
|
111
167
|
|
|
112
|
-
- Linux
|
|
113
|
-
-
|
|
168
|
+
- **Linux** (Ubuntu, Debian, Fedora, etc.)
|
|
169
|
+
- **macOS** (requires GNU binutils)
|
|
170
|
+
- **Windows** (Not supported directly; use WSL2)
|
|
114
171
|
|
|
115
172
|
---
|
|
116
173
|
|
|
117
174
|
## Requirements
|
|
118
175
|
|
|
119
|
-
- unzip
|
|
120
|
-
-
|
|
176
|
+
- `unzip` (for extracting APK/AAB contents)
|
|
177
|
+
- `objdump` (from binutils, for ELF analysis)
|
|
178
|
+
- `zipalign` (Optional: from Android build-tools 35.0.0-rc3+, for zip alignment check)
|
|
179
|
+
- `deapexer` (Optional: for APEX file support)
|
|
180
|
+
|
|
181
|
+
### macOS additional requirement
|
|
182
|
+
macOS `objdump` may not support all flags. Install GNU binutils:
|
|
183
|
+
|
|
184
|
+
```sh
|
|
185
|
+
brew install binutils
|
|
186
|
+
# Ensure gobjdump is in your PATH or linked as objdump
|
|
187
|
+
```
|
|
121
188
|
|
|
122
189
|
---
|
|
123
190
|
|
|
124
191
|
## Migration Guide
|
|
125
192
|
|
|
126
193
|
If your app or any dependency uses native code:
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
194
|
+
1. **Update your build tools:** Use Android Gradle Plugin (AGP) >= 8.5.1 and NDK r27+ (prefer r28+).
|
|
195
|
+
2. **Recompile all native libraries** with 16KB alignment.
|
|
196
|
+
3. **Remove hardcoded page size assumptions** (replace `4096`/`0x1000`/`PAGE_SIZE` with `sysconf(_SC_PAGESIZE)`).
|
|
197
|
+
4. **Check all third-party .so files** for compliance.
|
|
198
|
+
5. **Test on Android 15+ emulators or real devices**.
|
|
132
199
|
|
|
133
|
-
See [official migration steps](https://developer.android.com/guide/practices/page-sizes?hl=pt-br#compile-16-kb-alignment)
|
|
200
|
+
See [official migration steps](https://developer.android.com/guide/practices/page-sizes?hl=pt-br#compile-16-kb-alignment).
|
|
134
201
|
|
|
135
202
|
---
|
|
136
203
|
|
|
137
204
|
## Troubleshooting
|
|
138
205
|
|
|
139
|
-
-
|
|
140
|
-
-
|
|
141
|
-
-
|
|
206
|
+
- **`UNALIGNED (2**12)`**: The library is 4KB aligned. You must rebuild it with NDK r27+ or add linker flags.
|
|
207
|
+
- **`command not found: verify-16k-page-align`**: Ensure npm global bin is in your PATH, or use the shell script directly.
|
|
208
|
+
- **`objdump: command not found`**: Install `binutils`.
|
|
209
|
+
- **`Permission denied`**: Run `chmod +x verify-16k-page-align.sh` before executing.
|
|
142
210
|
|
|
143
211
|
---
|
|
144
212
|
|
|
@@ -150,8 +218,8 @@ A: No need—Java/Kotlin-only apps do not use native libraries and are already c
|
|
|
150
218
|
**Q: What if my library is not 16KB aligned?**
|
|
151
219
|
A: Update your build tools and recompile. Contact third-party vendors for updated .so files.
|
|
152
220
|
|
|
153
|
-
**Q: Can I use this on macOS
|
|
154
|
-
A:
|
|
221
|
+
**Q: Can I use this on macOS?**
|
|
222
|
+
A: Yes, install `binutils` via Homebrew.
|
|
155
223
|
|
|
156
224
|
**Q: Is this required for Play Store submission?**
|
|
157
225
|
A: Yes, for Android 15+ apps after Nov 1, 2025.
|
|
@@ -168,7 +236,6 @@ Pull requests and issues are welcome! See [GitHub Issues](https://github.com/hot
|
|
|
168
236
|
- [Android 16KB Page Size Docs](https://developer.android.com/guide/practices/page-sizes?hl=pt-br)
|
|
169
237
|
- [Google Play Blog](https://android-developers.googleblog.com/2025/05/prepare-play-apps-for-devices-with-16kb-page-size.html)
|
|
170
238
|
- [Medium: Migration Guide](https://devharshmittal.medium.com/android-15-is-raising-the-bar-mandatory-16kb-memory-page-size-what-developers-need-to-know-4dd81ec58f67)
|
|
171
|
-
- [Reddit: brdev discussion](https://www.reddit.com/r/brdev/comments/1nl3fx4/android_15_seus_apps_j%C3%A1_est%C3%A3o_prontos_para_16kb/)
|
|
172
239
|
|
|
173
240
|
## Show your support
|
|
174
241
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "verify-16k-page-align",
|
|
3
|
-
"version": "0.0
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Shell script and npm package to verify Android APK/AAB/APEX native libraries are 16KB or 64KB page aligned for Android 15+ compatibility",
|
|
5
5
|
"main": "lib/index.js",
|
|
6
6
|
"types": "lib/index.d.ts",
|
|
7
7
|
"private": false,
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
"license": "MIT",
|
|
13
13
|
"scripts": {
|
|
14
14
|
"lint": "shellcheck src/verify-16k-page-align.sh",
|
|
15
|
-
"
|
|
15
|
+
"test": "./src/verify-16k-page-align.sh --help",
|
|
16
16
|
"version": "git add -A src",
|
|
17
17
|
"postversion": "git push && git push --tags"
|
|
18
18
|
},
|
|
@@ -23,11 +23,11 @@
|
|
|
23
23
|
"node": ">=20.0.0"
|
|
24
24
|
},
|
|
25
25
|
"files": [
|
|
26
|
-
"
|
|
26
|
+
"src/**/*"
|
|
27
27
|
],
|
|
28
28
|
"os": [
|
|
29
29
|
"linux",
|
|
30
|
-
"
|
|
30
|
+
"darwin",
|
|
31
31
|
"!win32"
|
|
32
32
|
],
|
|
33
33
|
"bundleDependencies": [
|
|
@@ -39,16 +39,25 @@
|
|
|
39
39
|
},
|
|
40
40
|
"keywords": [
|
|
41
41
|
"android",
|
|
42
|
+
"android-15",
|
|
43
|
+
"16kb-pages",
|
|
44
|
+
"page-alignment",
|
|
45
|
+
"apk",
|
|
46
|
+
"aab",
|
|
47
|
+
"apex",
|
|
48
|
+
"native-libraries",
|
|
49
|
+
"elf",
|
|
50
|
+
"objdump",
|
|
42
51
|
"react-native",
|
|
43
52
|
"npm",
|
|
44
|
-
"
|
|
53
|
+
"shell-script",
|
|
54
|
+
"ci-cd"
|
|
45
55
|
],
|
|
46
56
|
"bugs": {
|
|
47
57
|
"url": "https://github.com/hotbrainstech/verify-16k-page-align/issues"
|
|
48
58
|
},
|
|
49
59
|
"homepage": "https://github.com/hotbrainstech/verify-16k-page-align#readme",
|
|
50
60
|
"devDependencies": {
|
|
51
|
-
"@types/node": "^24.5.2"
|
|
52
|
-
"concurrently": "^9.2.1"
|
|
61
|
+
"@types/node": "^24.5.2"
|
|
53
62
|
}
|
|
54
|
-
}
|
|
63
|
+
}
|
|
@@ -16,7 +16,7 @@ usage() {
|
|
|
16
16
|
echo "Shared libraries are reported ALIGNED when their ELF regions are"
|
|
17
17
|
echo "16 KB or 64 KB aligned. Otherwise they are reported as UNALIGNED."
|
|
18
18
|
echo
|
|
19
|
-
echo "Usage: ${progname} [input-path|input-APK|input-APEX]"
|
|
19
|
+
echo "Usage: ${progname} [input-path|input-APK|input-AAB|input-APEX]"
|
|
20
20
|
}
|
|
21
21
|
|
|
22
22
|
|
|
@@ -47,28 +47,30 @@ if [ ${#} -eq 2 ] && [ "${2}" = "x86" ]; then
|
|
|
47
47
|
arch_filter="arm64-v8a|x86_64"
|
|
48
48
|
fi
|
|
49
49
|
|
|
50
|
-
if [[ "${dir}" == *.apk ]]; then
|
|
50
|
+
if [[ "${dir}" == *.apk ]] || [[ "${dir}" == *.aab ]]; then
|
|
51
51
|
trap 'cleanup_trap' EXIT
|
|
52
52
|
|
|
53
53
|
echo
|
|
54
54
|
echo "Recursively analyzing $dir"
|
|
55
55
|
echo
|
|
56
56
|
|
|
57
|
-
if {
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
57
|
+
if [[ "${dir}" == *.apk ]]; then
|
|
58
|
+
if { zipalign --help 2>&1 | grep -q "\-P <pagesize_kb>"; }; then
|
|
59
|
+
echo "=== APK zip-alignment ==="
|
|
60
|
+
zipalign -v -c -P 16 4 "${dir}" | egrep "lib/(${arch_filter})|Verification"
|
|
61
|
+
echo "========================="
|
|
62
|
+
else
|
|
63
|
+
echo "NOTICE: Zip alignment check requires build-tools version 35.0.0-rc3 or higher."
|
|
64
|
+
echo " You can install the latest build-tools by running the below command"
|
|
65
|
+
echo " and updating your \$PATH:"
|
|
66
|
+
echo
|
|
67
|
+
echo " sdkmanager \"build-tools;35.0.0-rc3\""
|
|
68
|
+
fi
|
|
67
69
|
fi
|
|
68
70
|
|
|
69
71
|
dir_filename=$(basename "${dir}")
|
|
70
|
-
tmp=$(mktemp -d -t "${dir_filename
|
|
71
|
-
unzip "${dir}" lib/* -d "${tmp}"
|
|
72
|
+
tmp=$(mktemp -d -t "${dir_filename%.*}_out_XXXXX")
|
|
73
|
+
unzip -q "${dir}" "lib/*" -d "${tmp}"
|
|
72
74
|
dir="${tmp}"
|
|
73
75
|
fi
|
|
74
76
|
|
|
@@ -115,6 +117,8 @@ done
|
|
|
115
117
|
|
|
116
118
|
if [ ${#unaligned_libs[@]} -gt 0 ]; then
|
|
117
119
|
echo -e "${RED}Found ${#unaligned_libs[@]} unaligned libs (only arm64-v8a/x86_64 libs need to be aligned).${ENDCOLOR}"
|
|
120
|
+
echo "====================="
|
|
121
|
+
exit 1
|
|
118
122
|
elif [ -n "${dir_filename}" ]; then
|
|
119
123
|
echo -e "ELF Verification Successful"
|
|
120
124
|
fi
|