[GR-68779] Move Builtin annotation to the annotations package

PullRequest: graalpython/3971

Author: eregon

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/Builtin.java renamed to graalpython/com.oracle.graal.python.annotations/src/com/oracle/graal/python/annotations/Builtin.java

@@ -23,14 +23,12 @@
  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  * OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-package com.oracle.graal.python.builtins;
+package com.oracle.graal.python.annotations;
 
 import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
-import com.oracle.graal.python.nodes.StringLiterals;
-
 @Retention(RetentionPolicy.RUNTIME)
 @Repeatable(value = Builtins.class)
 public @interface Builtin {
@@ -89,17 +87,17 @@
      */
     boolean declaresExplicitSelf() default false;
 
-    String raiseErrorName() default StringLiterals.J_EMPTY_STRING;
+    String raiseErrorName() default "";
 
     boolean forceSplitDirectCalls() default false;
 
     /**
      * If set to {@code true}, then this builtin will be initialized and registered in
-     * {@link PythonBuiltins#initialize(Python3Core)}. Otherwise, it will be ignored even when it
-     * has a generated node factory. This is useful when we want to initialize the builtin manually
-     * in different way (e.g., wrap it in method, descriptor, ...). By convention set this to
-     * {@code false} also for builtins declared outside of {@link PythonBuiltins} subclass to
-     * document the intent to not initialize them automatically.
+     * PythonBuiltins#initialize. Otherwise, it will be ignored even when it has a generated node
+     * factory. This is useful when we want to initialize the builtin manually in different way
+     * (e.g., wrap it in method, descriptor, ...). By convention set this to {@code false} also for
+     * builtins declared outside of PythonBuiltins subclass to document the intent to not initialize
+     * them automatically.
      */
     boolean autoRegister() default true;
 }

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/Builtins.java renamed to graalpython/com.oracle.graal.python.annotations/src/com/oracle/graal/python/annotations/Builtins.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 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
@@ -38,7 +38,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package com.oracle.graal.python.builtins;
+package com.oracle.graal.python.annotations;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;

graalpython/com.oracle.graal.python.annotations/src/com/oracle/graal/python/annotations/PythonOS.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2021, 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
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.oracle.graal.python.annotations;
+
+import java.util.Locale;
+
+public enum PythonOS {
+    PLATFORM_LINUX("linux", "Linux"),
+    PLATFORM_DARWIN("darwin", "Darwin"),
+    PLATFORM_WIN32("win32", "Windows"),
+    PLATFORM_ANY(null, null);
+
+    public static final String SUPPORTED_PLATFORMS = "linux/amd64, linux/aarch64, macos/amd64, macos/aarch64, and windows/amd64";
+
+    private final String name;
+    private final String uname;
+
+    PythonOS(String name, String uname) {
+        this.name = name;
+        this.uname = uname;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public String getUname() {
+        return uname;
+    }
+
+    public static final PythonOS internalCurrent;
+
+    static {
+        String property = System.getProperty("os.name", "").toLowerCase(Locale.ROOT);
+        if (property.contains("linux")) {
+            internalCurrent = PLATFORM_LINUX;
+        } else if (property.contains("mac") || property.contains("darwin")) {
+            internalCurrent = PLATFORM_DARWIN;
+        } else if (property.contains("windows")) {
+            internalCurrent = PLATFORM_WIN32;
+        } else {
+            internalCurrent = PLATFORM_ANY;
+        }
+    }
+
+    public static boolean isUnsupported() {
+        return internalCurrent == PLATFORM_ANY;
+    }
+
+}

graalpython/com.oracle.graal.python.frozen/freeze_modules.py

@@ -543,8 +543,10 @@ def lower_camel_case(str):
  */
 package com.oracle.graal.python.builtins.objects.module;
 
-import com.oracle.graal.python.builtins.PythonOS;
+import com.oracle.graal.python.PythonLanguage;
+import com.oracle.graal.python.annotations.PythonOS;
 
+/** GENERATED BY graalpython/com.oracle.graal.python.frozen/freeze_modules.py */
 public final class FrozenModules {"""
 
 
@@ -581,7 +583,7 @@ def write_frozen_lookup(out_file, modules):
             )
         elif module.name == "os.path": # Special case for os.path
             out_file.write(u'            case "os.path":\n')
-            out_file.write(u'                return PythonOS.getPythonOS() != PythonOS.PLATFORM_WIN32 ? Map.POSIXPATH : Map.NTPATH;\n')
+            out_file.write(u'                return PythonLanguage.getPythonOS() != PythonOS.PLATFORM_WIN32 ? Map.POSIXPATH : Map.NTPATH;\n')
         else:
             out_file.write(f'            case "{module.name}":\n')
             out_file.write(f"                return Map.{module.symbol};\n")

graalpython/com.oracle.graal.python.processor/src/com/oracle/graal/python/processor/ArgumentClinicProcessor.java

@@ -82,9 +82,9 @@
 
 public class ArgumentClinicProcessor extends AbstractProcessor {
     private static final boolean LOGGING = false;
-    private static final String BuiltinAnnotationClass = "com.oracle.graal.python.builtins.Builtin";
+    private static final String BuiltinAnnotationClass = "com.oracle.graal.python.annotations.Builtin";
     private static final String SlotSignatureAnnotationClass = "com.oracle.graal.python.annotations.Slot.SlotSignature";
-    private static final String BuiltinsAnnotationClass = "com.oracle.graal.python.builtins.Builtins";
+    private static final String BuiltinsAnnotationClass = "com.oracle.graal.python.annotations.Builtins";
     private static final String BUILTINS_BASE_CLASSES_PACKAGE = "com.oracle.graal.python.nodes.function.builtins";
 
     private Element[] clinicBuiltinBaseClasses;

graalpython/com.oracle.graal.python.test/src/com/oracle/graal/python/test/SocketTests.java

@@ -97,6 +97,7 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
+import com.oracle.graal.python.PythonLanguage;
 import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Rule;
@@ -108,7 +109,7 @@
 import org.junit.runners.Parameterized.Parameter;
 import org.junit.runners.Parameterized.Parameters;
 
-import com.oracle.graal.python.builtins.PythonOS;
+import com.oracle.graal.python.annotations.PythonOS;
 import com.oracle.graal.python.builtins.objects.exception.OSErrorEnum;
 import com.oracle.graal.python.runtime.PosixConstants.MandatoryIntConstant;
 import com.oracle.graal.python.runtime.PosixSupportLibrary;
@@ -661,7 +662,7 @@ public void dgramSelect() throws PosixException {
 
     @Test
     public void streamSelect() throws PosixException {
-        if (PythonOS.getPythonOS() == PythonOS.PLATFORM_DARWIN) {
+        if (PythonLanguage.getPythonOS() == PythonOS.PLATFORM_DARWIN) {
             // transiently fails on darwin, skip
             return;
         }

graalpython/com.oracle.graal.python.test/src/com/oracle/graal/python/test/builtin/modules/ClinicTests.java

@@ -57,7 +57,7 @@
 import com.oracle.graal.python.annotations.ClinicConverterFactory.BuiltinName;
 import com.oracle.graal.python.annotations.ClinicConverterFactory.DefaultValue;
 import com.oracle.graal.python.annotations.ClinicConverterFactory.UseDefaultForNone;
-import com.oracle.graal.python.builtins.Builtin;
+import com.oracle.graal.python.annotations.Builtin;
 import com.oracle.graal.python.builtins.PythonBuiltinClassType;
 import com.oracle.graal.python.builtins.objects.PNone;
 import com.oracle.graal.python.builtins.objects.function.PArguments;

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/PythonLanguage.java

@@ -25,8 +25,7 @@
  */
 package com.oracle.graal.python;
 
-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.annotations.PythonOS.PLATFORM_WIN32;
 import static com.oracle.graal.python.nodes.BuiltinNames.T__SIGNAL;
 import static com.oracle.graal.python.nodes.StringLiterals.J_PY_EXTENSION;
 import static com.oracle.graal.python.nodes.StringLiterals.T_PY_EXTENSION;
@@ -51,15 +50,17 @@
 import java.util.concurrent.Semaphore;
 import java.util.logging.Level;
 
+import com.oracle.truffle.api.exception.AbstractTruffleException;
 import org.graalvm.home.Version;
+import org.graalvm.nativeimage.ImageInfo;
 import org.graalvm.options.OptionDescriptors;
 import org.graalvm.options.OptionKey;
 import org.graalvm.options.OptionValues;
 import org.graalvm.polyglot.SandboxPolicy;
 
 import com.oracle.graal.python.builtins.Python3Core;
 import com.oracle.graal.python.builtins.PythonBuiltinClassType;
-import com.oracle.graal.python.builtins.PythonOS;
+import com.oracle.graal.python.annotations.PythonOS;
 import com.oracle.graal.python.builtins.modules.MarshalModuleBuiltins;
 import com.oracle.graal.python.builtins.modules.SignalModuleBuiltins;
 import com.oracle.graal.python.builtins.objects.PNone;
@@ -1225,4 +1226,51 @@ public Source getOrCreateSource(Function<Object, Source> rootNodeFunction, Objec
         CompilerAsserts.neverPartOfCompilation();
         return sourceCache.computeIfAbsent(key, rootNodeFunction);
     }
+
+    public static PythonOS getPythonOS() {
+        if (PythonOS.internalCurrent == PythonOS.PLATFORM_ANY) {
+            if (ImageInfo.inImageBuildtimeCode()) {
+                throw new RuntimeException("Native images with GraalPy are only supported on " + PythonOS.SUPPORTED_PLATFORMS + ".");
+            }
+            String emulated = get(null).getEngineOption(PythonOptions.UnsupportedPlatformEmulates);
+            if (!emulated.isEmpty()) {
+                switch (emulated) {
+                    case "linux":
+                        return PythonOS.PLATFORM_LINUX;
+                    case "macos":
+                        return PythonOS.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 " + PythonOS.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 must 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 PythonOS.internalCurrent;
+    }
+
+    public static void throwIfUnsupported(String msg) {
+        if (PythonOS.isUnsupported()) {
+            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;
+    }
 }

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/CoreFunctions.java

@@ -25,6 +25,8 @@
  */
 package com.oracle.graal.python.builtins;
 
+import com.oracle.graal.python.annotations.PythonOS;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/Python3Core.java

@@ -64,6 +64,7 @@
 import java.util.logging.Level;
 
 import com.oracle.graal.python.PythonLanguage;
+import com.oracle.graal.python.annotations.PythonOS;
 import com.oracle.graal.python.builtins.modules.AbcModuleBuiltins;
 import com.oracle.graal.python.builtins.modules.ArrayModuleBuiltins;
 import com.oracle.graal.python.builtins.modules.AsyncioModuleBuiltins;
@@ -441,7 +442,7 @@ private static TruffleString[] getCoreFiles() {
                         T__SYSCONFIG,
                         T_JAVA,
                         toTruffleStringUncached("pip_hook"));
-        if (PythonOS.getPythonOS() == PythonOS.PLATFORM_WIN32) {
+        if (PythonLanguage.getPythonOS() == PythonOS.PLATFORM_WIN32) {
             coreFiles = new ArrayList<>(coreFiles);
             coreFiles.add(toTruffleStringUncached("_nt"));
         }
@@ -463,7 +464,7 @@ private static TruffleString[] getCoreFiles() {
     }
 
     private static void filterBuiltins(List<PythonBuiltins> builtins) {
-        PythonOS currentOs = PythonOS.getPythonOS();
+        PythonOS currentOs = PythonLanguage.getPythonOS();
         List<PythonBuiltins> toRemove = new ArrayList<>();
         for (PythonBuiltins builtin : builtins) {
             if (builtin == null) {