Added version sub-command and fixed line number flags.

This change set adds a `version` sub-command, so that users can determine the current version of the tool. It also fixes an issue with line number flags, whereby the old `--include_lines` option was being ignored. Since we are by default adding line number information to AVM files in the rebar3 plugin, we are changing the default behavior to include line number information by default. Users can remove line number information using the `-r` or `--remove_lines` flags. Miscellaneous other fixes include: * Update version to 0.7.0 * Workaround for an issue loading the atomvm_packbeam application in a release, which prevents us from getting the proper version * Added UPDATING.md to describe the "breaking" change in 0.7.0 (see UPDATING below) * Fix to Makefile to build the release target properly * Removed use of deprecated packbeam_api create call UPDATING: The default behavior of not generating line number information in BEAM files has changed. By default, line number information will be generated in BEAM files. You can remove line number information using from BEAM files by using the `-r` (or `--remove_lines`) flags to the `create` subcommand. Note that in versions 0.6 of this tool, the `--include_lines` flag was ignored due to a bug in the code. Signed-off-by: Fred Dushin <[email protected]>
atomvm · Oct 15, 2023 · 5b6835a · 5b6835a
1 parent a21d15f
commit 5b6835a
Show file tree

Hide file tree

Showing 8 changed files with 86 additions and 19 deletions.
diff --git a/ChangeLog b/ChangeLog
@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0]
+
+- Added `version` sub-command to print version to the console
+- Added `-r`, `--remove` option and removed the `-i`, `--include` option, which was ineffective due to a bug.  See the [Updating](UPDATING.md) notes on the impact of these changes.
+
 ## [0.6.2]
 
 - Added `relx` stanzas to create a standalone release of the `packbeam` utility

diff --git a/Makefile b/Makefile
@@ -3,7 +3,7 @@
 ## All rights reserved.
 ##
 
-all: compile escript edoc etest release
+all: compile escript edoc etest rel
 
 compile:
 	rebar3 compile
@@ -19,7 +19,7 @@ etest:
 	rebar3 proper --cover
 	rebar3 cover --verbose
 
-release:
+rel:
 	rebar3 release
 	rebar3 tar
 

diff --git a/README.md b/README.md
@@ -57,18 +57,22 @@ The general syntax of the `packbeam` command takes the form:
 On-line help is available via the `help` sub-command:
 
     shell$ packbeam help
+
+    packbeam version 0.7.0
+
     Syntax:
-    packbeam <sub-command> <options> <args>
+        packbeam <sub-command> <options> <args>
 
     The following sub-commands are supported:
 
         create <options> <output-avm-file> [<input-file>]+
             where:
             <output-avm-file> is the output AVM file,
-            [<input-file>]+ is is a list of one or more input files,
+            [<input-file>]+ is a list of one or more input files,
             and <options> are among the following:
                 [--prune|-p]           Prune dependencies
                 [--start|-s <module>]  Start module
+                [--remove_lines|-r]    Remove line number information from AVM files
 
         list <options> <avm-file>
             where:
@@ -82,17 +86,21 @@ On-line help is available via the `help` sub-command:
             [<element>]+ is a list of one or more elements to extract
                 (if empty, then extract all elements)
             and <options> are among the following:
-                [-out <output-directory>]   Output directory into which to write elements
+                [--out|-o <output-directory>]   Output directory into which to write elements
                 (if unspecified, use the current working directory)
 
         delete <options> <avm-file> [<element>]+
             where:
             <avm-file> is an AVM file,
-            [<element>]+ is is a list of one or more elements to delete,
+            [<element>]+ is a list of one or more elements to delete,
             and <options> are among the following:
-                [-out <output-avm-file>]    Output AVM file
+                [--out|-o <output-avm-file>]    Output AVM file
+
+        version
+            Print version and exit
 
-        help  print this help
+        help
+            Print this help
 
 The `packbeam` command will return an exit status of 0 on successful completion of a command.  An unspecified non-zero value is returned in the event of an error.
 
@@ -136,6 +144,12 @@ If you specify the `--prune` (alternatively, `-p`) flag, then `packbeam` will on
 
 If there is no beam file with a `start/0` entry-point defined in the list of input modules and the `--prune` flag is used, the command will fail.  You should _not_ use the `--prune` flag if you are trying to build libraries suitable for inclusion on other AtomVM applications.
 
+### Line number information
+
+By default, the `packbeam` tool will generate line number information for embedded BEAM files.  Line number information is included in Erlang stacktraces, giving developers more clues into bugs in their programs.  However, line number information does increase the size of AVM files, and in some cases can have an impact on memory in running applications.
+
+For production applications that have no need for line number information, we recommend using the `-r` (or `--remove_lines`) flags, which will strip line number information from embedded BEAM files.
+
 ## `list` sub-command
 
 The `list` sub-command will print the contents of an AVM file to the standard output stream.

diff --git a/UPDATING.md b/UPDATING.md
@@ -0,0 +1,11 @@
+<!---
+  Copyright 2023 Fred Dushin <[email protected]>
+
+  SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+-->
+
+# AtomVM Update Instructions
+
+## 0.6.* -> 0.7.*
+
+- The default behavior of not generating line number information in BEAM files has changed.  By default, line number information will be generated in BEAM files.  You can remove line number information using from BEAM files by using the `-r` (or `--remove_lines`) flags to the `create` subcommand.  Note that in versions 0.6 of this tool, the `--include_lines` flag was ignored due to a bug in the code.
diff --git a/rebar.config b/rebar.config
@@ -8,7 +8,7 @@
 {escript_incl_apps, [atomvm_packbeam]}.
 {escript_main_app, atomvm_packbeam}.
 {escript_name, packbeam}.
-{escript_emu_args, "%%! +sbtu +A1\n"}.
+{escript_emu_args, "%%! -escript main packbeam"}.
 
 {ex_doc, [
     {source_url, <<"https://github.com/atomvm/atomvm_packbeam">>},
@@ -30,7 +30,7 @@
 ]}.
 
 {relx, [
-    {release, {atomvm_packbeam, "0.6.2"}, [
+    {release, {atomvm_packbeam, "0.7.0"}, [
         kernel,
         stdlib,
         atomvm_packbeam

diff --git a/src/atomvm_packbeam.app.src b/src/atomvm_packbeam.app.src
@@ -20,7 +20,7 @@
     [
         {description,
             "An escript and library to manipulate (create, list, delete) AtomVM PackBeam files"},
-        {vsn, "0.6.2"},
+        {vsn, "0.7.0"},
         {registered, []},
         {applications, [kernel, stdlib]},
         {env, []},

diff --git a/src/packbeam.erl b/src/packbeam.erl
@@ -28,6 +28,13 @@
 %% escript
 -export([main/1]).
 
+%%
+%% MAINTENANCE NOTE.  Due to an issue loading our atomvm_packbeam
+%% application from an escript in a release, we need to fall back to
+%% a hard-wired version string.
+%%
+-define(CURRENT_VERSION, "0.7.0").
+
 %%
 %% Public API
 %%
@@ -87,6 +94,9 @@ main(Argv) ->
                         erlang:halt(do_extract(Opts, ArgsRest));
                     "delete" ->
                         erlang:halt(do_delete(Opts, ArgsRest));
+                    "version" ->
+                        io:format("~s~n", [get_version()]),
+                        erlang:halt(0);
                     "help" ->
                         print_help(),
                         erlang:halt(0);
@@ -111,6 +121,9 @@ main(Argv) ->
 %% @private
 print_help() ->
     io:format(
+        "~n"
+        "packbeam version ~s~n"
+        "~n"
         "Syntax:~n"
         "    packbeam <sub-command> <options> <args>~n"
         "~n"
@@ -123,7 +136,7 @@ print_help() ->
         "           and <options> are among the following:~n"
         "              [--prune|-p]           Prune dependencies~n"
         "              [--start|-s <module>]  Start module~n"
-        "              [--include_lines|-i]   Include lines in AVM files~n"
+        "              [--remove_lines|-r]    Remove line number information from AVM files~n"
         "~n"
         "    list <options> <avm-file>~n"
         "        where:~n"
@@ -147,16 +160,40 @@ print_help() ->
         "           and <options> are among the following:~n"
         "               [--out|-o <output-avm-file>]    Output AVM file~n"
         "~n"
-        "    help  print this help"
+        "    version~n"
+        "        Print version and exit~n"
         "~n"
+        "    help~n"
+        "        Print this help~n"
+        "~n",
+        [get_version()]
     ).
 
+%% @private
+get_version() ->
+    case application:load(atomvm_packbeam) of
+        ok ->
+            case lists:keyfind(atomvm_packbeam, 1, application:loaded_applications()) of
+                {_, _, Version} ->
+                    Version;
+                false ->
+                    ?CURRENT_VERSION
+            end;
+        {error, _Reason} ->
+            ?CURRENT_VERSION
+    end.
+
 %% @private
 do_create(Opts, Args) ->
     validate_args(create, Opts, Args),
     [OutputFile | InputFiles] = Args,
     ok = packbeam_api:create(
-        OutputFile, InputFiles, undefined, maps:get(prune, Opts, false), maps:get(start, Opts, undefined)
+        OutputFile, InputFiles,
+        #{
+            prune => maps:get(prune, Opts, false),
+            start => maps:get(start, Opts, undefined),
+            include_lines => not maps:get(remove_lines, Opts, false)
+        }
     ),
     0.
 
@@ -308,10 +345,10 @@ parse_args(["-s", Module | T], {Opts, Args}) ->
 parse_args(["--start", Module | T], {Opts, Args}) ->
     parse_args(T, {Opts#{start_module => list_to_atom(Module)}, Args});
 
-parse_args(["-i" | T], {Opts, Args}) ->
-    parse_args(["--include_lines" | T], {Opts, Args});
-parse_args(["--include_lines" | T], {Opts, Args}) ->
-    parse_args(T, {Opts#{include_lines => true}, Args});
+parse_args(["-r" | T], {Opts, Args}) ->
+    parse_args(["--remove_lines" | T], {Opts, Args});
+parse_args(["--remove_lines" | T], {Opts, Args}) ->
+    parse_args(T, {Opts#{remove_lines => true}, Args});
 
 parse_args(["-format", Format | T], {Opts, Args}) ->
     io:format("WARNING.  Deprecated option.  Use --format instead.~n"),

diff --git a/src/packbeam_api.erl b/src/packbeam_api.erl
@@ -56,7 +56,7 @@
     prune => false,
     start_module => undefined,
     application_module => undefined,
-    include_lines => false
+    include_lines => true
 }).
 
 %%