+
+
+
+
+ + + + Page not found +
+ +Sorry, but the page you were trying to get to, does not exist. You +may want to try searching this site using the sidebar + + or using our API Reference page + +to find what you were looking for.
+ +Sorry, but the page you were trying to get to, does not exist. You +may want to try searching this site using the sidebar + + or using our API Reference page + +to find what you were looking for.
+ +All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, +and this project adheres to Semantic Versioning.
packbeam_api to make it more maintainable.rebar3_ex_docversion sub-command to print version to the console-r, --remove option and removed the -i, --include option, which was ineffective due to a bug. See the Updating notes on the impact of these changes.relx stanzas to create a standalone release of the packbeam utilityextract sub-command<<"Line">> chunks in BEAM files in generated AVM filespackbeam_api:create function to take a single map for optional
+parameters, instead of coding paramters into function arguments. Previous
+versions of the packbeam_api:create function that take optional parameters
+have been deprecated.format option to the list subcommand, supporting csv, bare,
+and default options.packbeam API functionality into packbeam_api module.
+Previous packbeam API functions now call corresponding packbeam_api
+functions and are deprecated.?BEAM_START_FLAG be set, for compatibility with ExAtomVM.erlfmt plugin and formatted code.We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community.
Examples of behavior that contributes to a positive environment for our +community include:
Examples of unacceptable behavior include:
Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful.
Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate.
This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event.
Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +davide AT uninstall.it. +All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the +reporter of any incident.
Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct:
Community Impact: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community.
Consequence: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested.
Community Impact: A violation through a single incident or series +of actions.
Consequence: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban.
Community Impact: A serious violation of community standards, including +sustained inappropriate behavior.
Consequence: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban.
Community Impact: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals.
Consequence: A permanent ban from any sort of public interaction within +the community.
This Code of Conduct is adapted from the Contributor Covenant, +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
Community Impact Guidelines were inspired by Mozilla's code of conduct +enforcement ladder.
For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations.
+Before contributing, please read carefully our Code of Conduct and +the following contribution guidelines.
Please, also make sure to understand the Apache 2.0 license and the +Developer Certificate of Origin.
Last but not least, do not use GitHub issues for vulnerability reports, read instead the +security policy for instructions.
git pull --rebasegit rebase -iGood:
void f(int reverse)
+{
+ if (reverse) {
+ puts("!dlroW olleH");
+ } else {
+ puts("Hello world");
+ }
+}Bad:
void f(int reverse) {
+ if (reverse)
+ puts ("!dlroW olleH");
+ else
+ puts ("Hello world");
+}, notchar* name`)Just use Elixir formatter enforced style.
+ + +'+((e=o.lambda(l,l))!=null?e:"")+`
+`},9:function(o,l,a,f,r){var e,n=o.lookupProperty||function(u,s){if(Object.prototype.hasOwnProperty.call(u,s))return u[s]};return((e=(n(a,"isArray")||l&&n(l,"isArray")||o.hooks.helperMissing).call(l??(o.nullContext||{}),l!=null?n(l,"results"):l,{name:"isArray",hash:{},fn:o.program(10,r,0),inverse:o.program(12,r,0),data:r,loc:{start:{line:28,column:2},end:{line:34,column:14}}}))!=null?e:"")+` +The search functionality is full-text based. Here are some tips:
+ +foo bar) are searched as OR* anywhere (such as fo*) as wildcard+ before a word (such as +foo) to make its presence required- before a word (such as -foo) to make its absence required: to search on a particular field (such as field:word). The available fields are title, doc and typeWORD^NUMBER (such as foo^2) to boost the given wordWORD~NUMBER (such as foo~2) to do a search with edit distance on wordTo quickly go to a module, type, or function, use the autocompletion feature in the sidebar search.
+`},10:function(o,l,a,f,r){var e,n=o.lookupProperty||function(u,s){if(Object.prototype.hasOwnProperty.call(u,s))return u[s]};return"Sorry, we couldn't find anything for "+o.escapeExpression((e=(e=n(a,"value")||(l!=null?n(l,"value"):l))!=null?e:o.hooks.helperMissing,typeof e=="function"?e.call(l??(o.nullContext||{}),{name:"value",hash:{},data:r,loc:{start:{line:29,column:48},end:{line:29,column:57}}}):e))+`.
+`},12:function(o,l,a,f,r){var e,n=o.lookupProperty||function(u,s){if(Object.prototype.hasOwnProperty.call(u,s))return u[s]};return(e=n(a,"if").call(l??(o.nullContext||{}),l!=null?n(l,"value"):l,{name:"if",hash:{},fn:o.program(13,r,0),inverse:o.program(15,r,0),data:r,loc:{start:{line:30,column:2},end:{line:34,column:2}}}))!=null?e:""},13:function(o,l,a,f,r){var e,n=o.lookupProperty||function(u,s){if(Object.prototype.hasOwnProperty.call(u,s))return u[s]};return"Invalid search: "+o.escapeExpression((e=(e=n(a,"errorMessage")||(l!=null?n(l,"errorMessage"):l))!=null?e:o.hooks.helperMissing,typeof e=="function"?e.call(l??(o.nullContext||{}),{name:"errorMessage",hash:{},data:r,loc:{start:{line:31,column:23},end:{line:31,column:39}}}):e))+`.
+`},15:function(o,l,a,f,r){return`Please type something into the search bar to perform a search.
+ `},compiler:[8,">= 4.3.0"],main:function(o,l,a,f,r){var e,n=l??(o.nullContext||{}),u=o.lookupProperty||function(s,i){if(Object.prototype.hasOwnProperty.call(s,i))return s[i]};return`+ Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2020, Fred Dushin <fred@dushin.net>. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. ++
Create an AVM file.
Create an AVM file.
Delete selected elements of an AVM file.
Extract all or selected elements from an AVM file.
List the contents of an AVM file.
-opaque avm_element()
+
+ -type avm_element_name() :: string().
+
+ -type options() ::
+ #{prune => boolean(),
+ start_module => module() | undefined,
+ application_module => module() | undefined,
+ include_lines => boolean()}.
+
+ -type path() :: string().
+
+ -spec create(OutputPath :: path(), InputPaths :: [path()]) -> ok | {error, Reason :: term()}.+ +
Create an AVM file.
Equivalent to create(OutputPath, InputPaths, DefaultOptions)
DefaultOptions is #{ prune => false, start_module => undefined, application_module => undefined, include_lines => false }
+ -spec create(OutputPath :: path(), InputPaths :: [path()], Options :: options()) -> + ok | {error, Reason :: term()}.+ +
Create an AVM file.
This function will create an AVM file at the location specified in OutputPath, using the input files specified in InputPaths. +-spec delete(OutputPath :: path(), InputPath :: path(), AVMElementNames :: [avm_element_name()]) -> + ok | {error, Reason :: term()}.+ +
Delete selected elements of an AVM file.
This function will delete elements of an AVM file at the location specified in InputPath, specified by the supplied list of names. The output AVM file is written to OutputPath, which may be the same as InputPath. +-spec extract(InputPath :: path(), AVMElementNames :: [avm_element_name()], OutputDir :: path()) -> + ok | {error, Reason :: term()}.+ +
Extract all or selected elements from an AVM file.
This function will extract elements of an AVM file at the location specified in InputPath, specified by the supplied list of names. The elements from the input AVM file will be written into the specified output directory, creating any subdirectories if the AVM file elements contain path information. +-spec get_element_data(AVMElement :: avm_element()) -> binary().+ +
-spec get_element_module(AVMElement :: avm_element()) -> module() | undefined.+ +
-spec get_element_name(AVMElement :: avm_element()) -> avm_element_name().+ +
-spec is_beam(AVMElement :: avm_element()) -> boolean().+ +
-spec is_entrypoint(AVMElement :: avm_element()) -> boolean().+ +
-spec list(InputPath :: path()) -> [avm_element()].+ +
List the contents of an AVM file.
This function will list the contents of an AVM file at the location specified in InputPath. +atomvvm_packbeam
+An Erlang Escript and library used to generate an AtomVM AVM file from a set of files (beam files, previously built AVM files, or even arbitrary data files).
This tool roughly approximates the functionality of the AtomVM PackBEAM utility, except:
The packbeam tool may be used on its own as a stand-alone command-line utility. More typically, it is used internally as part of the atomvm_rebar3_plugin rebar3 plugin.
Building packbeam requires a version of Erlang/OTP compatible with AtomVM, as well as a local installation of rebar3. Optionally, any recent version of make may be used to simplify builds. Consult the AtomVM Documentation for information about supported OTP versions.
To build a release, run the following commands:
shell$ rebar3 release
+shell$ rebar3 tarThese commands will create an Erlang tar archive containing a versioned release of the atomvm_packbeam tool, e.g.,
...
+===> Tarball successfully created: _build/prod/rel/atomvm_packbeam/atomvm_packbeam-0.6.2.tar.gzin your local working directory.
IMPORTANT! The files in this tar archive do not contain the
atomvm_packbeamprefix, so extracting these files without care will create abinandlibdirectory in the location into which files from the archive is extracted. See the example below before proceeding!
You can use the install.sh script to install the atomvm_packbeam utility into a location on your local machine. You will need to specify the prefix location into which you want to install the utility, together with it's current version.
shell$ ./install.sh /opt/atomvm_packbeam 0.6.2
+atomvm_packbeam version 0.6.2 installed in /opt/atomvm_packbeam.Note. Some prefix locations may require
rootpermissions to write files to.
Set your PATH environment variable to include the bin directory of the installation prefix (if not already set), and you should then be able to run the packbeam command included therein.
For example:
shell$ export PATH=/opt/atomvm_packbeam/bin:$PATH
+shell$ packbeam help
+Syntax:
+ packbeam <sub-command> <options> <args>
+ ...packbeam command
+The packbeam command is used to create an AVM file from a list of beam and other file types, to list the contents of an AVM file, or to delete elements from an AVM file.
The general syntax of the packbeam command takes the form:
packbeam <sub-command> <args>On-line help is available via the help sub-command:
shell$ packbeam help
+
+packbeam version 0.7.2
+
+Syntax:
+ 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 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:
+ <avm-file> is an AVM file,
+ and <options> are among the following:
+ [--format|-f csv|bare|default] Format output
+
+ extract <options> <avm-file> [<element>]*
+ where:
+ <avm-file> is an AVM file,
+ [<element>]+ is a list of one or more elements to extract
+ (if empty, then extract all elements)
+ and <options> are among the following:
+ [--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 a list of one or more elements to delete,
+ and <options> are among the following:
+ [--out|-o <output-avm-file>] Output AVM file
+
+ version
+ Print version and exit
+
+ help
+ Print this helpThe 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.
The packbeam sub-commands are described in more detail below.
create sub-command
+To create an AVM file from a list of beam files, use the create sub-command to create an AVM file. The first argument is take to be the output AVM file, following by the files you would like to add, e.g.,
shell$ packbeam create mylib.avm mylib/ebin/mylib.beam mylib/ebin/foo.beam mylib/ebin/bar.beamThis command will create an AtomVM AVM file suitable for use with AtomVM.
The input files specified in the create subcommand may be among the following types:
.beam)Note that beam files specified are stripped of their path information, inside of the generated AVM file. Any files that have the same name will be added in the order they are listed on the command line. However, AtomVM will only resolve the first such file when loading modules at run-time.
If you are building an application that provides a start entrypoint (as opposed to a library, suitable for inclusion in another AVM file), then at least one beam module in an AVM file must contain a start/0 entry-point, i.e., a function called start with arity 0. AtomVM will use this entry-point as the first function to execute, when starting.
Note. It is conventional, but not required, that the first beam file in an AVM file contains the
start/0entry-point. AtomVM will use the first BEAM file that contains an exportedstart/0function as the entry-point for the application.
If your application has multiple modules with exported start/0 functions, you may use the --start <module> (alternatively, -s <module>) option to specify the module you would like placed first in your AVM file. The <module> parameter should be the module name (without the .beam suffix, e.g., main).
A previously created AVM file file may be supplied as input (including the same file specified as output, for example). The contents of any input AVM files will be included in the output AVM file. For example, if you are building a library of BEAM files (for example, none of which contain a start/0 entry-point), you may want to archive these into an AVM file, which can be used for downstream applications.
In addition, you may specify a "normal" (i.e., non-beam or non-AVM) file. Normal files are labeled with the path specified on the command line.
shell$ packbeam create mylib.avm mylib.avm mylib/priv/sample.txtNote. It is conventional in AtomVM for normal files to have the path
<module-name>/priv/<file-name>.
If you specify the --prune (alternatively, -p) flag, then packbeam will only include beam files that are transitively dependent on the entry-point beam. Transitive dependencies are determined by imports, as well as use of an atom in a module (e.g, as the result of a dynamic function call, based on a module name).
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.
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.
To list the elements of an AVM file, specify the location of the AVM file to input as the first argument:
shell$ packbeam list mylib.avm
+mylib.beam * [284]
+foo.beam [276]
+bar.beam [252]
+mylib/priv/sample.txt [29]The elements in the AVM file are printed to the standard output stream and are listed on each line. If a beam file contain an exported start/0 function, it will be marked with an asterisk (*). The size in bytes of each module is also printed in square brackets ([]).
You may use the --format (alternatively, -f) option to specify an output format. The supported formats are:
csv Output elements in comma-separated value format. Fields include the module name, whether the element is a BEAM file, whether the element provides a start/0 entrypoint, and the size (in bytes) of the element.bare Output just the module name, with no annotations.default Output the module name, size (in brackets), and whether the file provides a start/0 entrypoint, indicated by an asterisk (*). The default output is used if the --format option is not specified.extract sub-command
+The extract sub-command can be used to extract elements from an AVM file.
To extract one or more elements from an AVM file, specify the location of the AVM file from which to extract elements, followed by the list of elements (as displayed via the list sub-command) to extract. If no elements are listed, then all elements from the AVM file will be extracted.
Non-BEAM ("normal") files that contain paths in their names will be extracted into a directory tree that reflects the path used in the element name. For example, if the element name is mylib/priv/sample.txt, then the sample.txt file will be extracted into the mylib/priv directory (relative to the output directory, detailed below).
You may optionally specify an output directory using the --out option, which will contain the extracted contents of the input AVM file. This directory must exist beforehand, or a runtime error will occur. If no output directory is specified, elements will be extracted into the current working directory.
For example:
shell$ mkdir mydir
+shell$ packbeam extract -out mydir mylib.avm foo.beam mylib/priv/sample.txt
+Writing to mydir ...
+x foo.beam
+x mylib/priv/sample.txtdelete sub-command
+The delete sub-command can be used to remove elements from an AVM file.
To delete one or more elements from an AVM file, specify the location of the AVM file from which to remove elements, followed by the list of elements (as displayed via the list sub-command) to remove. You may optionally specify an output AVM file using the --out option, which will contain the contents of the input AVM file, minus the specified elements. If no output AVM is specified, the input AVM file will be overwritten.
For example:
shell$ packbeam delete -out mylib2.avm mylib.avm foo.beam bar.beam
+shell$ packbeam list mylib2.avm
+mylib.beam * [284]
+mylib/priv/sample.txt [29]packbeam_api API
+In addition to being an escript command-line utility, this project provides an Erlang API and library for manipulating AVM files. Simply include atomvm_packbeam as a dependency in your rebar.config, and you will have access to this API.
For more detailed information about this API, see the
packbeam_apiReference.
To create a PackBEAM file, use the packbeam_api:create/2 function. Specify the output path of the AVM you would like to create, followed by a list of paths to the files that will go into the AVM file. Typically, these paths are a list of BEAM files, though you can also include plain data files, in addition to previously created AVM files. Previously-created AVM files will be copied into the output AVM file.
Note. Specify the file system paths to all files. BEAM file path information will be stripped from the AVM element path data. Any plain data files (non-BEAM files) will retain their path information. See the AtomVM Documentation about how to create plain data files in AVM files that users can retrieved via the
atomvm:read_priv/2function.
%% erlang
+ok = packbeam_api:create(
+ "/path/to/output.avm", [
+ "/path/to/foo.beam",
+ "/path/to/bar.beam",
+ "/path/to/myapp/priv/sample.txt",
+ "/path/to/some_lib.avm"
+ ]
+).Alternatively, you may specify a set of options with the packbeam_api:create/3 function, which takes a map as the third parameter.
| Key | Type | Deafult | Description |
|---|---|---|---|
prune | boolean() | false | Specify whether to prune the output AVM file. Pruned AVM files can take considerably less space and hence may lead to faster development times. |
start | module() | n/a | Specify the start module, if it can't be determined automatically from the application. |
application | module() | n/a | Specify the application module. The <application>.app file will be encoded and included as an element in the AVM file with the path <module>/priv/application.bin |
include_lines | boolean() | true | Specify whether to include line number information in generated AVM files. |
You can list the contents of PackBEAM files using the packbeam_api:list/1 function. Specify the file system path to the PackBEAM file you would like to list:
%% erlang
+AVMElements = packbeam_api:list("/path/to/input.avm").The returned AVMElements is list of an opaque data structures and should not be interpreted by user applications. However, several functions are exposed to retrieve information about elements in this list.
To get the element name, use the packbeam_api:get_element_name/1 function, passing in an AVM element. The return type is a string() and represents the path in the AVM file for the AVM element.
%% erlang
+AVMElementName = packbeam_api:get_element_name(AVMElement).To get the element data (as a binary) use the packbeam_api:get_element_data/1 function, passing in an AVM element. The return type is a binary() containing the actual data in the AVM element.
%% erlang
+AVMElementData = packbeam_api:get_element_data(AVMElement).To get the element module (as an atom) use the packbeam_api:get_element_module/1 function, passing in an AVM element. The return type is a module() and the module name of the AVM element.
Note that if the AVM element is not a BEAM file, this function returns undefined.
%% erlang
+AVMElementModule = packbeam_api:get_element_module(AVMElement).To determine if the element is a BEAM file, use the packbeam_api:is_beam/1 function, passing in an AVM element. The return value is a boolean().
%% erlang
+IsBEAM = packbeam_api:is_beam(AVMElement).To determine if the element is an entrypoint BEAM (i.e., it exports a start/0 function), use the packbeam_api:is_entrypoint/1 function, passing in an AVM element. The return value is a boolean().
%% erlang
+IsEntrypoint = packbeam_api:is_entrypoint(AVMElement).You can delete entries from an AVM file using the packbeam_api:delete/3 function. Specify the file system path to the PackBEAM file you would like to delete from, the output path you would like to write the new AVM file to, and a list of AVM elements you would like to delete:
%% erlang
+ok = packbeam_api:delete(
+ "/path/to/input.avm",
+ "/path/to/ouput.avm",
+ ["foo.beam", "myapp/priv/sample.txt"]
+).Note. You may specify the same values for the input and output paths. In this case, the input AVM file will be over-written by the new AVM file.
You can extract elements from an AVM file using the packbeam_api:extract/3 function. Specify the file system path to the PackBEAM file you would like to extract from, a list of AVM elements you would like to extract, and the output directory into which would like to extract the files:
%% erlang
+ok = packbeam_api:extract(
+ "/path/to/input.avm",
+ ["foo.beam", "myapp/priv/sample.txt"],
+ "/tmp"
+).-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.