Merge pull request #1752 from pguyot/w28/start-with-init-boot

Start with init:boot/1

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

Author: bettio

CHANGELOG.md

@@ -60,6 +60,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Release images for ESP32 chips are built with ESP-IDF v5.4
 - ESP32: SPI peripheral defaults to `"spi2"` instead of deprecated `hspi`
 - Added `zlib:compress/1`
+- Entry point now is `init:boot/1` if it exists. It starts the kernel application and calls `start/0` from the
+  identified startup module. Users who started kernel application (typically for distribution) must no longer
+  do it. Startint `net_kernel` is still required.
 
 ### Fixed
 

doc/src/programmers-guide.md

@@ -176,10 +176,7 @@ For more information about deploying the AtomVM image and AtomVM applications to
 An AtomVM application is a collection of BEAM files, aggregated into an AtomVM "Packbeam" (`.avm`) file, and typically deployed (flashed) to some device.  These BEAM files be be compiled from Erlang, Elixir, or any other language that targets the Erlang VM.
 
 ```{attention}
-The return value from the `start/0` function is ignored on the the `generic_unix` platform, most MCU platforms have
-the option of rebooting the device if the `start/0` function returns a value other than `ok`. Consult the
-[Build Instructions](./build-instructions.md#platform-specific-build-instructions) for your device to see how this
-is configured.
+The return value from the `start/0` function is printed, ok means success (0 is also accepted for historical reasons), and any other value means failure. The processing of this results depend on platforms, on generic unix for example it determines the exit code. Most MCU platforms have the option of rebooting the device if the `start/0` function returns a value other than `ok`. Consult the [Build Instructions](./build-instructions.md#platform-specific-build-instructions) for your device to see how this is configured.
 ```
 
 Here, for example is one of the smallest AtomVM applications you can write:
@@ -205,6 +202,8 @@ wait_forever() ->
     receive X -> X end.
 ```
 
+The start function actually isn't the first function evaluated by the virtual machine. If the `init` module exists, `init:boot/1` is called and this function calls `start/0`. The `init` module is part of atomvmlib.
+
 ### Packbeam files
 
 AtomVM applications are packaged into Packbeam (`.avm`) files, which contain collections of files, typically BEAM (`.beam`) files that have been generated by the Erlang or Elixir compiler.

examples/erlang/CMakeLists.txt

@@ -25,7 +25,7 @@ include(BuildErlang)
 add_subdirectory(esp32)
 add_subdirectory(rp2)
 
-pack_runnable(hello_world hello_world)
+pack_runnable(hello_world hello_world estdlib)
 pack_runnable(udp_server udp_server estdlib eavmlib)
 pack_runnable(udp_client udp_client estdlib eavmlib)
 pack_runnable(tcp_client tcp_client estdlib eavmlib)

libs/estdlib/src/init.erl

@@ -28,11 +28,23 @@
 -module(init).
 
 -export([
+    boot/1,
     get_argument/1,
     get_plain_arguments/0,
     notify_when_started/1
 ]).
 
+%%-----------------------------------------------------------------------------
+%% @param Args command line arguments
+%% @doc Entry point.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec boot([binary() | atom()]) -> any().
+boot([<<"-s">>, StartupModule]) when is_atom(StartupModule) ->
+    % Until we have boot scripts, we just start kernel application.
+    {ok, _KernelPid} = kernel:start(boot, []),
+    StartupModule:start().
+
 %%-----------------------------------------------------------------------------
 %% @param Flag flag to get values for
 %% @return `error' if no value is associated with provided flag or values in

src/libAtomVM/defaultatoms.def

@@ -188,3 +188,5 @@ X(BREAK_IGNORED_ATOM, "\xD", "break_ignored")
 
 X(SCOPE_ATOM, "\x5", "scope")
 X(NOMATCH_ATOM, "\x7", "nomatch")
+
+X(INIT_ATOM, "\x4", "init")

src/libAtomVM/globalcontext.c

@@ -719,3 +719,42 @@ Module *globalcontext_get_module_by_index(GlobalContext *global, int index)
     SMP_RWLOCK_UNLOCK(global->modules_lock);
     return result;
 }
+
+run_result_t globalcontext_run(GlobalContext *glb, Module *startup_module, FILE *out_f)
+{
+    Context *ctx = context_new(glb);
+    ctx->leader = 1;
+    Module *init_module = globalcontext_get_module(glb, INIT_ATOM_INDEX);
+    if (IS_NULL_PTR(init_module)) {
+        context_execute_loop(ctx, startup_module, "start", 0);
+    } else {
+        if (UNLIKELY(memory_ensure_free(ctx, term_binary_heap_size(2) + LIST_SIZE(2, 0)) != MEMORY_GC_OK)) {
+            fprintf(stderr, "Unable to allocate arguments.\n");
+            return RUN_MEMORY_FAILURE;
+        }
+        term s_opt = term_from_literal_binary("-s", strlen("-s"), &ctx->heap, glb);
+        term list = term_list_prepend(module_get_name(startup_module), term_nil(), &ctx->heap);
+        ctx->x[0] = term_list_prepend(s_opt, list, &ctx->heap);
+
+        context_execute_loop(ctx, init_module, "boot", 1);
+    }
+
+    term ret_value = ctx->x[0];
+    if (out_f) {
+        fprintf(out_f, "Return value: ");
+        term_display(out_f, ret_value, ctx);
+        fprintf(out_f, "\n");
+    }
+
+    run_result_t result;
+    // ok or 0. 0 is required for running tests for emscripten
+    if (ret_value == OK_ATOM || ret_value == term_from_int(0)) {
+        result = RUN_SUCCESS;
+    } else {
+        result = RUN_RESULT_NOT_OK;
+    }
+
+    context_destroy(ctx);
+
+    return result;
+}

src/libAtomVM/globalcontext.h

@@ -90,6 +90,13 @@ struct RefcBinaryQueueItem
     struct RefcBinary *refc;
 };
 
+typedef enum run_result_t
+{
+    RUN_SUCCESS = 0,
+    RUN_MEMORY_FAILURE = 1,
+    RUN_RESULT_NOT_OK = 2,
+} run_result_t;
+
 struct GlobalContext
 {
     struct ListHead ready_processes;
@@ -512,6 +519,21 @@ Module *globalcontext_get_module(GlobalContext *global, atom_index_t module_name
  */
 Module *globalcontext_load_module_from_avm(GlobalContext *global, const char *module_name);
 
+/**
+ * @brief Run a given start module.
+ *
+ * @details This function will create a new context and call init:boot/1
+ * to execute the passed start module. If init module is not found, it will
+ * fallback to calling start module:start/0 directly. It will also
+ * print the result to out_f, typically stdout. It will return RUN_SUCCESS if
+ * result is ok or 0, an error code otherwise.
+ * @param global the global context
+ * @param start_module the start module
+ * @param out_f file to print the result to, or NULL
+ * @returns RUN_SUCCESS or an error code
+ */
+run_result_t globalcontext_run(GlobalContext *global, Module *start_module, FILE *out_f);
+
 #ifndef __cplusplus
 static inline uint64_t globalcontext_get_ref_ticks(GlobalContext *global)
 {

src/platforms/emscripten/src/main.c

@@ -95,23 +95,16 @@ static int start(void)
         fprintf(stderr, "main module not loaded\n");
         return EXIT_FAILURE;
     }
-    Context *ctx = context_new(global);
-    ctx->leader = 1;
-    context_execute_loop(ctx, main_module, "start", 0);
-    term ret_value = ctx->x[0];
-    fprintf(stdout, "Return value: ");
-    term_display(stdout, ret_value, ctx);
-    fprintf(stdout, "\n");
+
+    run_result_t ret_value = globalcontext_run(global, main_module, stdout);
 
     int status;
-    if (ret_value == OK_ATOM || ret_value == term_from_int(0)) {
+    if (ret_value == RUN_SUCCESS) {
         status = EXIT_SUCCESS;
     } else {
         status = EXIT_FAILURE;
     }
 
-    context_destroy(ctx);
-
     return status;
 }
 

src/platforms/esp32/components/avm_sys/include/platform_defaultatoms.def

@@ -49,7 +49,6 @@ X(BACKLOG_ATOM, "\x7", "backlog")
 X(ACCEPT_ATOM, "\x6", "accept")
 X(FD_ATOM, "\x2", "fd")
 
-X(INIT_ATOM, "\x4", "init")
 X(GET_PORT_ATOM, "\x8", "get_port")
 X(SOCKNAME_ATOM, "\x8", "sockname")
 X(PEERNAME_ATOM, "\x8", "peername")

src/platforms/esp32/main/main.c

@@ -119,26 +119,19 @@ void app_main()
         AVM_ABORT();
     }
     globalcontext_insert_module(glb, mod);
-    Context *ctx = context_new(glb);
-    ctx->leader = 1;
 
     ESP_LOGI(TAG, "Starting %s...", startup_module_name);
     fprintf(stdout, "---\n");
 
-    context_execute_loop(ctx, mod, "start", 0);
-    term ret_value = ctx->x[0];
-
-    fprintf(stdout, "AtomVM finished with return value: ");
-    term_display(stdout, ret_value, ctx);
-    fprintf(stdout, "\n");
+    run_result_t result = globalcontext_run(glb, mod, stdout);
 
     bool reboot_on_not_ok =
 #if defined(CONFIG_REBOOT_ON_NOT_OK)
         CONFIG_REBOOT_ON_NOT_OK ? true : false;
 #else
         false;
 #endif
-    if (reboot_on_not_ok && ret_value != OK_ATOM) {
+    if (reboot_on_not_ok && result != RUN_SUCCESS) {
         ESP_LOGE(TAG, "AtomVM application terminated with non-ok return value.  Rebooting ...");
         esp_restart();
     } else {