From 0bc1b7156ef75066d2938e9bf804440acc9978af Mon Sep 17 00:00:00 2001
From: Josh B <421772+HT154@users.noreply.github.com>
Date: Tue, 7 Jan 2025 07:55:27 -0800
Subject: [PATCH] Fix page size for Linux AArch64 native executables (#875)

Graal Native Image is assuming 4k page size here, which is a naughty assumption to make in the modern Linux-on-ARM landscape.
Two very common hardware configurations require 16k minumum page size: the Raspberry Pi 5 and Asahi Linux (running on Apple Silicon hardware).

This change forces 64k pages for Linux/AArch64 native executables to guarantee compatibility with these platforms.
DEVELOPMENT.adoc is also updated to cover the additional dependencies required for building native executables on Linux.
---
 DEVELOPMENT.adoc           | 9 +++++++--
 pkl-cli/pkl-cli.gradle.kts | 9 +++++++--
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/DEVELOPMENT.adoc b/DEVELOPMENT.adoc
index 8bd89b96..40936b22 100644
--- a/DEVELOPMENT.adoc
+++ b/DEVELOPMENT.adoc
@@ -3,7 +3,8 @@
 :uri-jenv: https://www.jenv.be
 :uri-intellij: https://www.jetbrains.com/idea/download/
 :uri-jdk: https://adoptopenjdk.net/releases.html?variant=openjdk17
-:uri-native-prerequisites: https://www.graalvm.org/latest/getting-started/windows/#prerequisites-for-native-image-on-windows
+:uri-native-prerequisites-linux: https://www.graalvm.org/latest/getting-started/linux/#prerequisites-for-native-image-on-linux
+:uri-native-prerequisites-windows: https://www.graalvm.org/latest/getting-started/windows/#prerequisites-for-native-image-on-windows
 
 == Setup
 
@@ -26,11 +27,15 @@ jenv enable-plugin gradle
 jenv enable-plugin export
 ----
 
+=== Additional Linux Setup
+. (optional) To build the native executable (`./gradlew buildNative`),
+install {uri-native-prerequisites-linux}[Prerequisites For Native Image on Linux].
+
 === Additional Windows Setup
 . (optional) Go to `System->For developers` and enable `Developer Mode`.
 Otherwise, some tests may fail due to insufficient file system privileges.
 . (optional) To build the native executable (`./gradlew buildNative`), 
-install {uri-native-prerequisites}[Prerequisites For Native Image on Windows].
+install {uri-native-prerequisites-windows}[Prerequisites For Native Image on Windows].
 
 == Common Build Commands
 
diff --git a/pkl-cli/pkl-cli.gradle.kts b/pkl-cli/pkl-cli.gradle.kts
index d82e9d33..27967f1a 100644
--- a/pkl-cli/pkl-cli.gradle.kts
+++ b/pkl-cli/pkl-cli.gradle.kts
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -276,7 +276,12 @@ val linuxExecutableAarch64: TaskProvider<Exec> by
     dependsOn(":installGraalVmAarch64")
     configureExecutable(
       buildInfo.graalVmAarch64,
-      layout.buildDirectory.file("executable/pkl-linux-aarch64")
+      layout.buildDirectory.file("executable/pkl-linux-aarch64"),
+      listOf(
+        // Ensure compatibility for kernels with page size set to 4k, 16k and 64k
+        // (e.g. Raspberry Pi 5, Asahi Linux)
+        "-H:PageSize=65536"
+      )
     )
   }