[K/N] Expose program name in runtime

kotlin-native/runtime/src/launcher/cpp/launcher.cpp

@@ -30,8 +30,14 @@ using namespace kotlin;
 //--- Setup args --------------------------------------------------------------//
 
 OBJ_GETTER(setupArgs, int argc, const char** argv) {
+  if (argc > 0 && argv[0][0] != '\0') {
+    // Don't set the programName to an empty string (by checking argv[0][0] != '\0') to make all platforms behave the same:
+    // Linux would set argv[0] to "" in case no programName is passed, whereas Windows & macOS would set argc to 0.
+    kotlin::programName = argv[0];
+  }
+
   // The count is one less, because we skip argv[0] which is the binary name.
-  ObjHeader* result = AllocArrayInstance(theArrayTypeInfo, argc - 1, OBJ_RESULT);
+  ObjHeader* result = AllocArrayInstance(theArrayTypeInfo, std::max(0, argc - 1), OBJ_RESULT);
   ArrayHeader* array = result->array();
   for (int index = 1; index < argc; index++) {
     ObjHolder result;
@@ -58,6 +64,8 @@ extern "C" RUNTIME_EXPORT int Init_and_run_start(int argc, const char** argv, in
       Kotlin_shutdownRuntime();
   }
 
+  kotlin::programName = nullptr; // argv[0] might not be valid after this point
+
   return exitStatus;
 }
 

kotlin-native/runtime/src/main/cpp/Runtime.cpp

@@ -172,6 +172,8 @@ bool kotlin::initializeGlobalRuntimeIfNeeded() noexcept {
     return true;
 }
 
+const char* kotlin::programName = nullptr;
+
 extern "C" {
 
 RUNTIME_NOTHROW void AppendToInitializersTail(InitNode *next) {
@@ -310,6 +312,15 @@ KBoolean Konan_Platform_isDebugBinary() {
   return kotlin::compiler::shouldContainDebugInfo();
 }
 
+OBJ_GETTER0(Konan_Platform_getProgramName) {
+    if (kotlin::programName == nullptr) {
+        // null in case Platform.getProgramName is called from within a library and the main function of the binary is not built with Kotlin
+        RETURN_OBJ(nullptr)
+    } else {
+        RETURN_RESULT_OF(CreateStringFromCString, kotlin::programName)
+    }
+}
+
 bool Kotlin_memoryLeakCheckerEnabled() {
   return g_checkLeaks;
 }

kotlin-native/runtime/src/main/cpp/Runtime.h

@@ -51,6 +51,8 @@ namespace kotlin {
 // Returns `true` if initialized.
 bool initializeGlobalRuntimeIfNeeded() noexcept;
 
+extern const char* programName;
+
 }
 
 #endif // RUNTIME_RUNTIME_H

kotlin-native/runtime/src/main/kotlin/kotlin/native/Platform.kt

@@ -102,6 +102,13 @@ public object Platform {
     public val isFreezingEnabled: Boolean
         get() = false
 
+    /**
+     * Representation of the name used to invoke the program executable.
+     * [null] if the Kotlin code was compiled to a native library and the executable is not a Kotlin program.
+     */
+    public val programName: String?
+        get() = Platform_getProgramName()
+
     /**
      * If the memory leak checker is activated, by default `true` in debug mode, `false` in release.
      * When memory leak checker is activated, and leak is detected during last Kotlin context
@@ -156,6 +163,10 @@ private external fun Platform_getCpuArchitecture(): Int
 @GCUnsafeCall("Konan_Platform_isDebugBinary")
 private external fun Platform_isDebugBinary(): Boolean
 
+@GCUnsafeCall("Konan_Platform_getProgramName")
+@Escapes.Nothing
+private external fun Platform_getProgramName(): String?
+
 @GCUnsafeCall("Konan_Platform_getMemoryLeakChecker")
 private external fun Platform_getMemoryLeakChecker(): Boolean
 

libraries/tools/binary-compatibility-validator/klib-public-api/kotlin-stdlib.api

@@ -11454,6 +11454,8 @@ final object kotlin.native/Platform { // kotlin.native/Platform|null[0]
         final fun <get-memoryModel>(): kotlin.native/MemoryModel // kotlin.native/Platform.memoryModel.<get-memoryModel>|<get-memoryModel>(){}[0]
     final val osFamily // kotlin.native/Platform.osFamily|{}osFamily[0]
         final fun <get-osFamily>(): kotlin.native/OsFamily // kotlin.native/Platform.osFamily.<get-osFamily>|<get-osFamily>(){}[0]
+    final val programName // kotlin.native/Platform.programName|{}programName[0]
+        final fun <get-programName>(): kotlin/String? // kotlin.native/Platform.programName.<get-programName>|<get-programName>(){}[0]
 
     final var isCleanersLeakCheckerActive // kotlin.native/Platform.isCleanersLeakCheckerActive|{}isCleanersLeakCheckerActive[0]
         final fun <get-isCleanersLeakCheckerActive>(): kotlin/Boolean // kotlin.native/Platform.isCleanersLeakCheckerActive.<get-isCleanersLeakCheckerActive>|<get-isCleanersLeakCheckerActive>(){}[0]

native/native.tests/testData/CExport/InterfaceV1/programName/main.c

@@ -0,0 +1,8 @@
+#include <stdio.h>
+#include "programName_api.h"
+
+int main() {
+    programName();
+    fflush(NULL);
+    return 0;
+}

native/native.tests/testData/CExport/InterfaceV1/programName/programNameLib-main.out

@@ -0,0 +1 @@
+Platform.programName is null within library

native/native.tests/testData/CExport/InterfaceV1/programName/programNameLib.kt

@@ -0,0 +1,6 @@
+@file:OptIn(kotlin.experimental.ExperimentalNativeApi::class)
+
+@CName("programName")
+fun programName() {
+    println("Platform.programName is " + Platform.programName + " within library")
+}

native/native.tests/testData/programName/kotlinPrintEntryPoint.kt

@@ -0,0 +1,11 @@
+@file:OptIn(kotlin.experimental.ExperimentalNativeApi::class)
+
+import kotlin.native.Platform
+
+fun main(args: Array<String>) {
+    // Remove path (using both unix/win path seperators) and extension (.kexe or .exe)
+    val programFileName = Platform.programName?.substringAfterLast("/")?.substringAfterLast("\\")?.substringBeforeLast(".")
+
+    println("programName: $programFileName")
+    println("args: ${args.joinToString()}")
+}

native/native.tests/testData/programName/main.c

@@ -0,0 +1,15 @@
+#include <errno.h>
+#include <stdio.h>
+#include <unistd.h>
+
+int main(int argc, char *argv[]) {
+    printf("calling exec...\n");
+    fflush(NULL);
+
+    // Kotlin executable name is in argv[1]
+    // Forward argv[2..n] to kotlin executable as arguments (the first one should be the programName according to posix)
+    execv(argv[1], &(argv[2]));
+
+    printf("exec failed with errno=%d\n", errno);
+    return 1;
+}

native/native.tests/testData/standalone/entryPoint/programName.kt

@@ -0,0 +1,11 @@
+@file:OptIn(kotlin.experimental.ExperimentalNativeApi::class)
+
+import kotlin.native.Platform
+import kotlin.test.*
+
+fun main(args: Array<String>) {
+    // Remove path and extension (.kexe or .exe)
+     val programFileName = Platform.programName!!.substringAfterLast("/").substringAfterLast("\\").substringBeforeLast(".")
+
+    assertEquals("standalone_entryPoint_programName", programFileName)
+}

native/native.tests/tests/org/jetbrains/kotlin/konan/test/blackbox/ProgramNameTest.kt

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package org.jetbrains.kotlin.konan.test.blackbox
+
+import org.jetbrains.kotlin.konan.target.Family
+import org.jetbrains.kotlin.konan.test.blackbox.support.TestCase
+import org.jetbrains.kotlin.konan.test.blackbox.support.TestKind
+import org.jetbrains.kotlin.konan.test.blackbox.support.compilation.TestCompilationResult.Companion.assertSuccess
+import org.jetbrains.kotlin.konan.test.blackbox.support.settings.testProcessExecutor
+import org.jetbrains.kotlin.konan.test.blackbox.support.util.ClangDistribution
+import org.jetbrains.kotlin.konan.test.blackbox.support.util.compileWithClang
+import org.jetbrains.kotlin.native.executors.runProcess
+import org.junit.jupiter.api.Tag
+import org.junit.jupiter.api.Test
+import java.io.File
+import kotlin.test.assertEquals
+import kotlin.time.Duration.Companion.seconds
+
+@Tag("program-name")
+class ProgramNameTest : AbstractNativeSimpleTest() {
+
+    @Test
+    fun programNameTest() {
+        // 1. Compile kotlinPrintEntryPoint.kt to kotlinPrintEntryPoint.kexe
+
+        val kotlinCompilation = compileToExecutableInOneStage(
+            generateTestCaseWithSingleFile(
+                sourceFile = sourceDir.resolve("kotlinPrintEntryPoint.kt"),
+                testKind = TestKind.STANDALONE_NO_TR,
+                extras = TestCase.NoTestRunnerExtras("main")
+            )
+        ).assertSuccess()
+
+        // 2. Compile main.c to main.cexe
+
+        val cExecutable = buildDir.resolve("main.cexe")
+        compileWithClang(
+            clangDistribution = ClangDistribution.Llvm,
+            sourceFiles = listOf(sourceDir.resolve("main.c")),
+            outputFile = cExecutable,
+            additionalClangFlags = listOf("-Wall", "-Werror"),
+        ).assertSuccess()
+
+        // 3. run main.cexe (with different parameters) to call kotlin executable
+
+        fun validate(expected: String, vararg args: String) {
+            val binaryName = kotlinCompilation.resultingArtifact.executableFile.path
+            val result = testRunSettings.testProcessExecutor.runProcess(cExecutable.absolutePath, binaryName, *args) {
+                timeout = 60.seconds
+            }
+            val sanitizedStdout = result.stdout.replace("\r\n", "\n") // Ignore if we have unix or windows line endings
+            assertEquals("calling exec...\n$expected", sanitizedStdout)
+            assertEquals("", result.stderr)
+        }
+
+        // kotlinPrintEntryPoint removes .kexe
+        validate("programName: app\nargs:", "app.kexe")
+
+        // Simulate a custom program name, see e.g. https://busybox.net/downloads/BusyBox.html#usage
+        validate("programName: customProgramName\nargs:", "customProgramName")
+        validate("programName: customProgramName\nargs: firstArg, secondArg", "customProgramName", "firstArg", "secondArg")
+
+        if (targets.testTarget.family == Family.MINGW) {
+            // With MinGW, `execv` in `main.c` fails with errno=22 (EINVAL) in the tests below.
+            // Let's just skip those corner cases.
+            return
+        }
+
+        // No program name - this would not be POSIX compliant, see https://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html:
+        // "[...] requires a Strictly Conforming POSIX Application to pass at least one argument to the exec function"
+        // However, we should not crash the Kotlin runtime because of this.
+        validate("programName: null\nargs:")
+
+        /*
+        An empty programName is treated as "no program name", because of the following reasoning:
+
+        When providing no program name (see above validation), both macOS and windows result in an empty argv (argv=[]).
+        However, linux behaves differently and sets argv=[""].
+
+        The C standard in section "5.1.2.2.1 Program startup" states:
+        "argv[0][0] shall be the null character if the program name is not available from the host environment".
+
+        It is discussable if en empty program name is considered as "not available from the host environment",
+        however in the sake of consistency across platforms we decided to treat it as such.
+
+        Therefore, the following test with an empty program name is expected to result in programName=null.
+        */
+
+        validate("programName: null\nargs:", "")
+    }
+
+    companion object {
+        private val sourceDir = File("native/native.tests/testData/programName")
+    }
+}