Allow users to opt-out of early failure on unsupported platforms.

timfel · timfel · commit 28f6160420b9 · 2025-08-20T19:00:13.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,9 @@
 This changelog summarizes major changes between GraalVM versions of the Python
 language runtime. The main focus is on user-observable behavior of the engine.
 
+## Version 25.0.1
+* Allow users to keep going on unsupported JDK/OS/ARCH combinations at their own risk by opting out of early failure using `-Dtruffle.UseFallbackRuntime=true`, `-Dpolyglot.engine.userResourceCache=/set/to/a/writeable/dir`, `-Dpolyglot.engine.allowUnsupportedPlatform=true`, and `-Dpolyglot.python.UnsupportedPlatformEmulates=[linux|macos|windows]` and `-Dorg.graalvm.python.resources.exclude=native.files`.
+
 ## Version 25.0.0
 * `sys.implementation.version` now returns the GraalPy version instead of the Python version it implements. Also available as `sys.graalpy_version_info` for better discoverability by people already familiar with PyPy and its `sys.pypy_version_info`.
 * `GRAALPY_VERSION_NUM` C macro now inlcudes the release level and serial number at the end to conform to the `hexversion` format. This shouldn't break any existing comparisons.
diff --git a/graalpython/com.oracle.graal.python.resources/src/com/oracle/graal/python/resources/PythonResource.java b/graalpython/com.oracle.graal.python.resources/src/com/oracle/graal/python/resources/PythonResource.java
@@ -105,7 +105,8 @@ public final class PythonResource implements InternalResource {
     @Override
     public void unpackFiles(Env env, Path targetDirectory) throws IOException {
         OS os = env.getOS();
-        Path osArch = Path.of(os.toString()).resolve(env.getCPUArchitecture().toString());
+        CPUArchitecture cpuArchitecture = env.getCPUArchitecture();
+        Path osArch = Path.of(os.toString()).resolve(cpuArchitecture.toString());
         ResourcesFilter filter = new ResourcesFilter();
         if (os.equals(OS.WINDOWS)) {
             env.unpackResourceFiles(BASE_PATH.resolve(LIBPYTHON_FILES), targetDirectory.resolve("Lib"), BASE_PATH.resolve(LIBPYTHON), filter);
@@ -121,7 +122,23 @@ public void unpackFiles(Env env, Path targetDirectory) throws IOException {
         // ni files are in the same place on all platforms
         env.unpackResourceFiles(BASE_PATH.resolve(NI_FILES), targetDirectory, BASE_PATH, filter);
         // native files already have the correct structure
-        env.unpackResourceFiles(BASE_PATH.resolve(osArch).resolve(NATIVE_FILES), targetDirectory, BASE_PATH.resolve(osArch), filter);
+        if (!os.equals(OS.UNSUPPORTED) && !cpuArchitecture.equals(CPUArchitecture.UNSUPPORTED)) {
+            env.unpackResourceFiles(BASE_PATH.resolve(osArch).resolve(NATIVE_FILES), targetDirectory, BASE_PATH.resolve(osArch), filter);
+        } else {
+            // Native resources are not available for unsupported operating systems.
+            if (!filter.test(Path.of(NATIVE_FILES))) {
+                throw new IOException("Extracting native resources failed for " +
+                                osArch.toString() +
+                                ". This means that GraalPy cannot use native extensions and some built-in features that rely on native code will be unavailable. " +
+                                "Currently supported platforms are linux/amd64, linux/aarch64, macos/amd64, macos/aarch64, and windows/amd64. " +
+                                "If you are running on one of these platforms and are receiving this error, that indicates a bug in this build of GraalPy. " +
+                                "If you are running on a different platform and want to keep going with this unsupported configuration, you can specify the system property \"" +
+                                ResourcesFilter.EXCLUDE_PROP +
+                                "\" with a pattern to exclude \"" +
+                                NATIVE_FILES +
+                                "\" to continue past this point. ");
+            }
+        }
 
         if (filter.log) {
             System.out.println("unpacked python resources:");
@@ -153,8 +170,7 @@ private static class ResourcesFilter implements Predicate<Path> {
         private final List<String> included;
         private static final String INCLUDE_PROP = "org.graalvm.python.resources.include";
         private static final String EXCLUDE_PROP = "org.graalvm.python.resources.exclude";
-
-        private static final String LOG_PROP = "org.graalvm.python.resources.exclude";
+        private static final String LOG_PROP = "org.graalvm.python.resources.log";
 
         private ResourcesFilter() {
             include = getProperty(INCLUDE_PROP);
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/PythonOS.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/PythonOS.java
@@ -42,18 +42,23 @@
 
 import static com.oracle.graal.python.util.PythonUtils.toTruffleStringUncached;
 
+import java.util.Locale;
+
+import org.graalvm.nativeimage.ImageInfo;
+
+import com.oracle.graal.python.PythonLanguage;
+import com.oracle.graal.python.runtime.PythonOptions;
+import com.oracle.truffle.api.exception.AbstractTruffleException;
 import com.oracle.truffle.api.strings.TruffleString;
 
 public enum PythonOS {
-    PLATFORM_JAVA("java", "Java"),
-    PLATFORM_CYGWIN("cygwin", "CYGWIN"),
     PLATFORM_LINUX("linux", "Linux"),
     PLATFORM_DARWIN("darwin", "Darwin"),
     PLATFORM_WIN32("win32", "Windows"),
-    PLATFORM_SUNOS("sunos", "SunOS"),
-    PLATFORM_FREEBSD("freebsd", "FreeBSD"),
     PLATFORM_ANY(null, null);
 
+    public static final String SUPPORTED_PLATFORMS = "linux/amd64, linux/aarch64, macos/amd64, macos/aarch64, and windows/amd64";
+
     private final TruffleString name;
     private final TruffleString uname;
 
@@ -73,28 +78,62 @@ public TruffleString getUname() {
     private static final PythonOS current;
 
     static {
-        String property = System.getProperty("os.name");
-        PythonOS os = PLATFORM_JAVA;
-        if (property != null) {
-            property = property.toLowerCase();
-            if (property.contains("cygwin")) {
-                os = PLATFORM_CYGWIN;
-            } else if (property.contains("linux")) {
-                os = PLATFORM_LINUX;
-            } else if (property.contains("mac")) {
-                os = PLATFORM_DARWIN;
-            } else if (property.contains("windows")) {
-                os = PLATFORM_WIN32;
-            } else if (property.contains("sunos")) {
-                os = PLATFORM_SUNOS;
-            } else if (property.contains("freebsd")) {
-                os = PLATFORM_FREEBSD;
-            }
+        String property = System.getProperty("os.name", "").toLowerCase(Locale.ENGLISH);
+        if (property.contains("linux")) {
+            current = PLATFORM_LINUX;
+        } else if (property.contains("mac") || property.contains("darwin")) {
+            current = PLATFORM_DARWIN;
+        } else if (property.contains("windows")) {
+            current = PLATFORM_WIN32;
+        } else {
+            current = PLATFORM_ANY;
         }
-        current = os;
     }
 
     public static PythonOS getPythonOS() {
+        if (current == PLATFORM_ANY) {
+            if (ImageInfo.inImageBuildtimeCode()) {
+                throw new RuntimeException("Native images with GraalPy are only supported on " + SUPPORTED_PLATFORMS + ".");
+            }
+            String emulated = PythonLanguage.get(null).getEngineOption(PythonOptions.UnsupportedPlatformEmulates);
+            if (!emulated.isEmpty()) {
+                switch (emulated) {
+                    case "linux":
+                        return PLATFORM_LINUX;
+                    case "macos":
+                        return PLATFORM_DARWIN;
+                    case "windows":
+                        return PLATFORM_WIN32;
+                    default:
+                        throw new UnsupportedPlatform("UnsupportedPlatformEmulates must be exactly one of \"linux\", \"macos\", or \"windows\"");
+                }
+            } else {
+                throw new UnsupportedPlatform("This platform is not currently supported. " +
+                                "Currently supported platforms are " + SUPPORTED_PLATFORMS + ". " +
+                                "If you are running on one of these platforms and are receiving this error, that indicates a bug in this build of GraalPy. " +
+                                "If you are running on a different platform and accept that any functionality that interacts with the system may be " +
+                                "incorrect and Python native extensions will not work, you can specify the system property \"UnsupportedPlatformEmulates\" " +
+                                "with a value of either \"linux\", \"macos\", or \"windows\" to continue further and have GraalPy behave as if it were running on " +
+                                "the OS specified. Loading native libraries will not work and should be disabled using the context options. " +
+                                "See https://www.graalvm.org/python/docs/ for details on GraalPy modules with both native and Java backends, " +
+                                "and https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/Context.Builder.html to learn about disallowing native access.");
+            }
+        }
         return current;
     }
+
+    public static void throwIfUnsupported(String msg) {
+        if (current == PLATFORM_ANY) {
+            throw new UnsupportedPlatform(msg +
+                            "\nThis point was reached as earlier platform checks were overridden using the system property UnsupportedPlatformEmulates");
+        }
+    }
+
+    public static final class UnsupportedPlatform extends AbstractTruffleException {
+        public UnsupportedPlatform(String msg) {
+            super(msg);
+        }
+
+        private static final long serialVersionUID = 1L;
+    }
 }
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/modules/SysModuleBuiltins.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/modules/SysModuleBuiltins.java
@@ -481,7 +481,7 @@ private static PSimpleNamespace makeImplementation(PythonLanguage language, PTup
     public void initialize(Python3Core core) {
         PythonLanguage language = core.getLanguage();
         StructSequence.initType(core, VERSION_INFO_DESC);
-        if (PythonOS.getPythonOS() == PLATFORM_WIN32) {
+        if (getPythonOS() == PLATFORM_WIN32) {
             StructSequence.initType(core, WINDOWS_VER_DESC);
         }
         StructSequence.initType(core, FLAGS_DESC);
@@ -569,7 +569,7 @@ public void initialize(Python3Core core) {
         // tarballs, not git
         addBuiltinConstant("_git", PFactory.createTuple(language, new Object[]{T_GRAALPYTHON_ID, T_EMPTY_STRING, T_EMPTY_STRING}));
 
-        if (PythonOS.getPythonOS() == PLATFORM_WIN32) {
+        if (os == PLATFORM_WIN32) {
             addBuiltinConstant("_vpath", "");
         }
 
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PosixConstants.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PosixConstants.java
@@ -43,6 +43,7 @@
 import java.util.HashMap;
 import java.util.Map;
 
+import com.oracle.graal.python.builtins.PythonOS;
 import com.oracle.truffle.api.CompilerDirectives;
 
 public final class PosixConstants {
@@ -56,21 +57,19 @@ public final class PosixConstants {
     public static final boolean IS_WIN32;
 
     static {
-        String os = System.getProperty("os.name");
-        if (os.contains("Linux")) {
+        if (PythonOS.getPythonOS() == PythonOS.PLATFORM_LINUX) {
             IS_LINUX = true;
             IS_DARWIN = false;
             IS_WIN32 = false;
-        } else if (os.contains("Mac")) {
+        } else if (PythonOS.getPythonOS() == PythonOS.PLATFORM_DARWIN) {
             IS_LINUX = false;
             IS_DARWIN = true;
             IS_WIN32 = false;
-        } else if (os.contains("Windows")) {
+        } else {
+            assert PythonOS.getPythonOS() == PythonOS.PLATFORM_WIN32;
             IS_LINUX = false;
             IS_DARWIN = false;
             IS_WIN32 = true;
-        } else {
-            throw new RuntimeException("Unsupported platform " + os);
         }
     }
 
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PosixResources.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PosixResources.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -54,11 +54,11 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
-import java.util.Locale;
 import java.util.Map;
 import java.util.SortedMap;
 import java.util.TreeMap;
 
+import com.oracle.graal.python.builtins.PythonOS;
 import com.oracle.graal.python.util.SuppressFBWarnings;
 import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary;
 import com.oracle.truffle.api.TruffleFile;
@@ -223,12 +223,11 @@ protected PosixResources(PythonContext context) {
         files = Collections.synchronizedSortedMap(new TreeMap<>());
         filePaths = Collections.synchronizedMap(new HashMap<>());
         children = Collections.synchronizedList(new ArrayList<>());
-        String osProperty = System.getProperty("os.name");
 
         files.put(FD_STDIN, ChannelWrapper.createForStandardStream());
         files.put(FD_STDOUT, ChannelWrapper.createForStandardStream());
         files.put(FD_STDERR, ChannelWrapper.createForStandardStream());
-        if (osProperty != null && osProperty.toLowerCase(Locale.ENGLISH).contains("win")) {
+        if (PythonOS.getPythonOS() == PythonOS.PLATFORM_WIN32) {
             filePaths.put(FD_STDIN, "STDIN");
             filePaths.put(FD_STDOUT, "STDOUT");
             filePaths.put(FD_STDERR, "STDERR");
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonContext.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonContext.java
@@ -28,6 +28,7 @@
 import static com.oracle.graal.python.builtins.PythonOS.PLATFORM_DARWIN;
 import static com.oracle.graal.python.builtins.PythonOS.PLATFORM_WIN32;
 import static com.oracle.graal.python.builtins.PythonOS.getPythonOS;
+import static com.oracle.graal.python.builtins.PythonOS.throwIfUnsupported;
 import static com.oracle.graal.python.builtins.modules.SysModuleBuiltins.T_CACHE_TAG;
 import static com.oracle.graal.python.builtins.modules.SysModuleBuiltins.T__MULTIARCH;
 import static com.oracle.graal.python.builtins.modules.io.IONodes.T_CLOSED;
@@ -222,7 +223,7 @@ public final class PythonContext extends Python3Core {
     public static String getSupportLibName(PythonOS os, String libName) {
         // note: this should be aligned with MX's "lib" substitution
         return switch (os) {
-            case PLATFORM_LINUX, PLATFORM_FREEBSD, PLATFORM_SUNOS -> J_LIB_PREFIX + libName + J_EXT_SO;
+            case PLATFORM_LINUX -> J_LIB_PREFIX + libName + J_EXT_SO;
             case PLATFORM_DARWIN -> J_LIB_PREFIX + libName + J_EXT_DYLIB;
             case PLATFORM_WIN32 -> libName + J_EXT_DLL;
             default -> libName;
@@ -231,6 +232,10 @@ public static String getSupportLibName(PythonOS os, String libName) {
 
     @TruffleBoundary
     public static String getSupportLibName(String libName) {
+        throwIfUnsupported("Trying to load a native library on an unsupported platform. " +
+                        "This is not possible and will fail. " +
+                        "Ensure that native access is disallowed for this context and configure GraalPy to use Java backends where possible. " +
+                        "Refer to https://www.graalvm.org/python/docs/ for more information on native and Java module backends.");
         return getSupportLibName(getPythonOS(), libName);
     }
 
diff --git a/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonOptions.java b/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/runtime/PythonOptions.java
@@ -103,6 +103,12 @@ public static void checkBytecodeDSLEnv() {
                     "Determines default values for the CoreHome, StdLibHome, SysBasePrefix, SysPrefix.", usageSyntax = "<path>", stability = OptionStability.STABLE) //
     public static final OptionKey<String> PythonHome = new OptionKey<>("");
 
+    @EngineOption @Option(category = OptionCategory.EXPERT, help = "Allow running on unsupported platforms, making GraalPy behave as if running on macOS, Windows, or Linux. " +
+                    "This option is useful to run GraalPy on platforms with a compliant Java implementation, but without native support for GraalPy. " +
+                    "When this option is set, native libraries cannot be loaded and the Java backends must be used for common operating system libraries provided by Python.", //
+                    usageSyntax = "windows|macos|linux", stability = OptionStability.STABLE) //
+    public static final OptionKey<String> UnsupportedPlatformEmulates = new OptionKey<>("");
+
     @Option(category = OptionCategory.USER, help = "Set the location of sys.prefix. Overrides any environment variables or Java options.", usageSyntax = "<path>", stability = OptionStability.STABLE) //
     public static final OptionKey<TruffleString> SysPrefix = new OptionKey<>(T_EMPTY_STRING, TS_OPTION_TYPE);
 
