Run embedded avm on Linux and macOS

Most platforms run embedded avm in the flash. Implement a similar mechanism
on generic_unix platform, to enable an escriptize-like experience.

Signed-off-by: Paul Guyot <[email protected]>

Author: pguyot

doc/src/atomvm-tooling.md

@@ -71,6 +71,34 @@ Return value: ok
 
 For instructions about how to install AtomVM on the `generic_unix` platform, see the [Getting Started Guide](./getting-started-guide.md#getting-started-on-the-generic-unix-platform)
 
+#### Building standalone binaries (macOS and Linux)
+
+Using [`atomvm_rebar3_plugin`](https://atomvm.github.io/atomvm_rebar3_plugin), it is possible to generate a standalone binary where your application is bundled with AtomVM virtual machine. The binary can be copied to another host and would work without any specific installation. Please note that AtomVM on generic unix currently depends on zlib and mbedtls as shared libraries.
+
+To proceed, you need to define the main module that should export a `main/1` function. This function is called with parameters like regular Erlang `escript` applications. This is done by adding these two lines to your `rebar.config` file:
+
+```
+{plugins, [atomvm_rebar3_plugin]}.
+{atomvm_rebar3_plugin, [{packbeam, [{start, main_module}]}]}.
+```
+
+where `main_module` is the name of the module that exports `main/1`. Alternatively, `main_module` can be defined with `escript_name` or `escript_main_app` options.
+
+Then you can run:
+```shell
+$ rebar3 atomvm escriptize
+...
+===> Created packed AVM: ... main_module_packed.avm with start module main_module
+===> Created standalone executable: ... main_module/_build/default/bin/main_module
+```
+
+It is possible to build this standalone binary with a specific build of AtomVM, for example including a particular `nif`.
+
+```{seealso}
+See the [`atomvm_rebar3_plugin`](https://atomvm.github.io/atomvm_rebar3_plugin) page for more detailed instructions
+about how to use the `escriptize` target.
+```
+
 ### Flashing your application with `rebar3`
 
 The [`atomvm_rebar3_plugin`](https://atomvm.github.io/atomvm_rebar3_plugin) supports flash targets for various device types.  These targets are described in more detail below.

libs/estdlib/src/init.erl

@@ -39,7 +39,36 @@
 %% @doc Entry point.
 %% @end
 %%-----------------------------------------------------------------------------
--spec boot([binary() | atom()]) -> any().
+-spec boot([binary() | atom() | string()]) -> any().
+boot([<<"-s">>, escript, <<"--">>, _Filename | Args]) ->
+    % Escript mode: check for start beam and main/1 function before starting kernel
+    case atomvm:get_start_beam(escript) of
+        {ok, ModuleNameBinary} ->
+            % Remove .beam suffix if present (check last 5 bytes)
+            Size = byte_size(ModuleNameBinary),
+            ModuleName =
+                if
+                    Size > 5 ->
+                        case binary:part(ModuleNameBinary, Size - 5, 5) of
+                            <<".beam">> -> binary:part(ModuleNameBinary, 0, Size - 5);
+                            _ -> ModuleNameBinary
+                        end;
+                    true ->
+                        ModuleNameBinary
+                end,
+            Module = binary_to_atom(ModuleName, utf8),
+            case erlang:function_exported(Module, main, 1) of
+                true ->
+                    {ok, _KernelPid} = kernel:start(boot, []),
+                    Module:main(Args);
+                false ->
+                    io:format("Function ~s:main/1 is not exported~n", [Module]),
+                    error
+            end;
+        _ ->
+            io:format("start_beam not found~n"),
+            error
+    end;
 boot([<<"-s">>, StartupModule]) when is_atom(StartupModule) ->
     % Until we have boot scripts, we just start kernel application.
     {ok, _KernelPid} = kernel:start(boot, []),

src/libAtomVM/globalcontext.c

@@ -29,6 +29,7 @@
 #include "context.h"
 #include "defaultatoms.h"
 #include "erl_nif_priv.h"
+#include "interop.h"
 #include "list.h"
 #include "mailbox.h"
 #include "posix_nifs.h"
@@ -720,21 +721,62 @@ Module *globalcontext_get_module_by_index(GlobalContext *global, int index)
     return result;
 }
 
-run_result_t globalcontext_run(GlobalContext *glb, Module *startup_module, FILE *out_f)
+run_result_t globalcontext_run(GlobalContext *glb, Module *startup_module, FILE *out_f, int argc, char **argv)
 {
     Context *ctx = context_new(glb);
     ctx->leader = 1;
     Module *init_module = globalcontext_get_module(glb, INIT_ATOM_INDEX);
     if (IS_NULL_PTR(init_module)) {
+        if (IS_NULL_PTR(startup_module)) {
+            fprintf(stderr, "Unable to locate entrypoint.\n");
+            return RUN_NO_ENTRY_POINT;
+        }
         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;
+        // Build boot arguments based on whether we're in embedded mode
+        if (argc > 0 && argv != NULL) {
+            // Embedded mode: ["-s", escript, "--" | argv_strings]
+            // Calculate heap size needed
+            size_t heap_needed = term_binary_heap_size(2) + // "-s"
+                term_binary_heap_size(2) + // "--"
+                LIST_SIZE(3, 0); // list for ["-s", escript, "--"]
+
+            // Calculate space for argv strings
+            for (int i = 0; i < argc; i++) {
+                size_t arg_len = strlen(argv[i]);
+                heap_needed += CONS_SIZE * arg_len + LIST_SIZE(1, 0);
+            }
+
+            if (UNLIKELY(memory_ensure_free(ctx, heap_needed) != MEMORY_GC_OK)) {
+                fprintf(stderr, "Unable to allocate arguments.\n");
+                return RUN_MEMORY_FAILURE;
+            }
+
+            // Build the argv list in reverse: [argvn, ..., argv0, "--", escript, "-s"]
+            term args_list = term_nil();
+            for (int i = argc - 1; i >= 0; i--) {
+                term arg = interop_chars_to_list(argv[i], strlen(argv[i]), &ctx->heap);
+                args_list = term_list_prepend(arg, args_list, &ctx->heap);
+            }
+
+            term separator = term_from_literal_binary("--", strlen("--"), &ctx->heap, glb);
+            args_list = term_list_prepend(separator, args_list, &ctx->heap);
+
+            term escript_atom = globalcontext_make_atom(glb, ATOM_STR("\x7", "escript"));
+            args_list = term_list_prepend(escript_atom, args_list, &ctx->heap);
+
+            term s_opt = term_from_literal_binary("-s", strlen("-s"), &ctx->heap, glb);
+            ctx->x[0] = term_list_prepend(s_opt, args_list, &ctx->heap);
+        } else {
+            // Non-embedded mode: ["-s", startup_module]
+            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);
         }
-        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);
     }

src/libAtomVM/globalcontext.h

@@ -95,6 +95,7 @@ typedef enum run_result_t
     RUN_SUCCESS = 0,
     RUN_MEMORY_FAILURE = 1,
     RUN_RESULT_NOT_OK = 2,
+    RUN_NO_ENTRY_POINT = 3,
 } run_result_t;
 
 struct GlobalContext
@@ -530,9 +531,11 @@ Module *globalcontext_load_module_from_avm(GlobalContext *global, const char *mo
  * @param global the global context
  * @param start_module the start module
  * @param out_f file to print the result to, or NULL
+ * @param argc number of command-line arguments (0 for non-embedded mode)
+ * @param argv command-line arguments (NULL for non-embedded mode)
  * @returns RUN_SUCCESS or an error code
  */
-run_result_t globalcontext_run(GlobalContext *global, Module *start_module, FILE *out_f);
+run_result_t globalcontext_run(GlobalContext *global, Module *start_module, FILE *out_f, int argc, char **argv);
 
 #ifndef __cplusplus
 static inline uint64_t globalcontext_get_ref_ticks(GlobalContext *global)

src/platforms/emscripten/src/main.c

@@ -96,7 +96,7 @@ static int start(void)
         return EXIT_FAILURE;
     }
 
-    run_result_t ret_value = globalcontext_run(global, main_module, stdout);
+    run_result_t ret_value = globalcontext_run(global, main_module, stdout, 0, NULL);
 
     int status;
     if (ret_value == RUN_SUCCESS) {

src/platforms/esp32/main/main.c

@@ -123,7 +123,7 @@ void app_main()
     ESP_LOGI(TAG, "Starting %s...", startup_module_name);
     fprintf(stdout, "---\n");
 
-    run_result_t result = globalcontext_run(glb, mod, stdout);
+    run_result_t result = globalcontext_run(glb, mod, stdout, 0, NULL);
 
     bool reboot_on_not_ok =
 #if defined(CONFIG_REBOOT_ON_NOT_OK)