Forward port changes from v0.6 release branch

Merge v0.6.4 into main.

.github/workflows/build-and-test.yaml

@@ -379,6 +379,16 @@ jobs:
         ./src/AtomVM ./tests/libs/alisp/test_alisp.avm
         valgrind ./src/AtomVM ./tests/libs/alisp/test_alisp.avm
 
+    - name: "Test: Tests.avm (Elixir)"
+      timeout-minutes: 10
+      working-directory: build
+      run: |
+        if command -v elixirc &> /dev/null
+        then
+          ./src/AtomVM ./tests/libs/exavmlib/Tests.avm
+          valgrind ./src/AtomVM ./tests/libs/exavmlib/Tests.avm
+        fi
+
     - name: "Install and smoke test"
       working-directory: build
       run: |

.github/workflows/build-docs.yaml

@@ -77,6 +77,15 @@ jobs:
           python3 -m pip install breathe
           python3 -m pip install pygments
 
+      - name: Set docs target name
+        shell: bash
+        run: |
+            if [[ ${{ github.ref_name }} == *"/merge" ]]; then
+              echo "AVM_DOCS_NAME=${{github.event.pull_request.base.ref}}" >> "$GITHUB_ENV";
+            else
+              echo "AVM_DOCS_NAME=${{ github.ref_name }}" >> "$GITHUB_ENV";
+            fi
+
       - uses: actions/checkout@v4
         with:
           repository: ${{ vars.GITHUB_REPOSITORY }}

.github/workflows/publish-docs.yaml

@@ -38,6 +38,9 @@ jobs:
     # The type of runner that the job will run on
     runs-on: ubuntu-latest
 
+    env:
+      AVM_DOCS_NAME: ${{ github.ref_name }}
+
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it

CHANGELOG.md

@@ -10,14 +10,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added a limited implementation of the OTP `ets` interface
 - Added `code:all_loaded/0` and `code:all_available/0`
 
-## [0.6.4] - Unreleased
+## [0.6.4] - 2024-08-18
 
 ### Added
 
 - Implement `gpio:init/1` on esp32 to initialize pins for GPIO usage, which some pins
 require depending on default function and bootloader code
-
-## [0.6.3] - 20-07-2024
+- Implement missing opcode 161 (raw_raise), that looks more likely to be generated with Elixir code
+- Support for Elixir `Map.replace/3` and `Map.replace!/3`
+- Support for Elixir `Kernel.struct` and `Kernel.struct!`
+- Support for Elixir `IO.iodata_to_binary/1`
+- Support for Elixir exceptions: `Exception` module and the other error related modules such as
+`ArgumentError`, `UndefinedFunctionError`, etc...
+- Support for Elixir `Enumerable` and `Collectable` protocol
+- Support for Elixir `Enum` functions: `split_with`, `join`, `map_join`, `into`, `reverse`,
+`slice` and `to_list`
+- Support for Elixir `MapSet` module
+- Support for Elixir `Range` module
+- Support for Elixir `Kernel.min` and `Kernel.max`
+- Support (as stub) for `erlang:error/3` (that is required from Elixir code)
+
+## [0.6.3] - 2024-07-20
 
 ### Added
 

doc/CMakeLists.txt

@@ -35,9 +35,18 @@ file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/edoc/edown_dep DESTINATION ${CMAKE_CURRENT
 
 # Configure libAtomVM restucturedtext skeleton.
 file(GLOB SOURCE_FILES LIST_DIRECTORIES false RELATIVE ${CMAKE_SOURCE_DIR}/src/libAtomVM/ ${CMAKE_SOURCE_DIR}/src/libAtomVM/*.c ${CMAKE_SOURCE_DIR}/src/libAtomVM/*.h)
+set(OMIT_FILES
+    "defaultatoms.c"
+    "opcodesswitch.h"
+    "scheduler.c"
+    "tempstack.h"
+)
 foreach(SOURCE_FILE ${SOURCE_FILES})
     configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/apidocs/libatomvm/file.rst.in ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/src/${SOURCE_FILE}.rst @ONLY)
 endforeach(SOURCE_FILE)
+foreach(OMIT ${OMIT_FILES})
+    file(REMOVE ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/src/${OMIT}.rst)
+endforeach(OMIT)
 
 # Support for edoc -> markdown.
 add_custom_target(edown-escript
@@ -46,11 +55,21 @@ add_custom_target(edown-escript
     COMMENT "Preparing edown escript" VERBATIM
 )
 
-# Get the version tree name, tag if this is a tagged commit, otherwise main.
-execute_process(COMMAND "bash" "-c" "tag=$(git for-each-ref --points-at=HEAD --format='%(refname:lstrip=2)' refs/tags); ( [ $tag ] && echo $tag ) || echo 'main'"
-                OUTPUT_VARIABLE
-                DOC_TREE_VERSION
-                OUTPUT_STRIP_TRAILING_WHITESPACE )
+# Get the version tree name, tag if this is a tagged commit, otherwise get the current branch name.
+if ($ENV{CI})
+    set(DOC_TREE_VERSION $ENV{AVM_DOCS_NAME})
+    message("CI building documentation for target branch ${DOC_TREE_VERSION}")
+else()
+    execute_process(COMMAND "bash" "-c" "tag=$(git for-each-ref --points-at=HEAD --format='%(refname:lstrip=2)' refs/tags); ( [ $tag ] && echo $tag )|| git branch --show-current"
+                    OUTPUT_VARIABLE
+                    DOC_TREE_VERSION
+                    OUTPUT_STRIP_TRAILING_WHITESPACE )
+    message("Local documentation test build on ${DOC_TREE_VERSION}")
+endif($ENV{CI})
+
+
+## conf.py.in must be configured after DOC_TREE_VERSION is defined
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py @ONLY)
 
 ##
 ## Erlang API documentation
@@ -108,7 +127,6 @@ endif()
 find_package(Sphinx)
 if(SPHINX_FOUND)
     message("Sphinx found: ${SPHINX_BUILD_EXECUTABLE}")
-    configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py @ONLY)
     configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
     file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/pdf_stylesheet.rts DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)
     file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/pdf_template.rtt DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)

doc/Doxyfile.in

@@ -465,7 +465,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO,
@@ -520,7 +520,7 @@ HIDE_FRIEND_COMPOUNDS  = NO
 # blocks will be appended to the function's detailed documentation block.
 # The default value is: NO.
 
-HIDE_IN_BODY_DOCS      = NO
+HIDE_IN_BODY_DOCS      = YES
 
 # The INTERNAL_DOCS tag determines if documentation that is typed after a
 # \internal command is included. If the tag is set to NO then the documentation
@@ -692,7 +692,7 @@ SHOW_FILES             = YES
 # Folder Tree View (if specified).
 # The default value is: YES.
 
-SHOW_NAMESPACES        = YES
+SHOW_NAMESPACES        = NO
 
 # The FILE_VERSION_FILTER tag can be used to specify a program or script that
 # doxygen should invoke to get the current version for each file (typically from
@@ -769,7 +769,7 @@ WARN_IF_DOC_ERROR      = YES
 # EXTRACT_ALL is set to YES then this flag will automatically be disabled.
 # The default value is: NO.
 
-WARN_NO_PARAMDOC       = NO
+WARN_NO_PARAMDOC       = YES
 
 # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
 # a warning is encountered.
@@ -903,7 +903,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */libAtomVM/opcodesswitch.h
+EXCLUDE_PATTERNS = */defaultatoms.c */opcodesswitch.h */scheduler.c */tempstack.h
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -1015,7 +1015,7 @@ SOURCE_BROWSER         = YES
 # classes and enums directly into the documentation.
 # The default value is: NO.
 
-INLINE_SOURCES         = NO
+INLINE_SOURCES         = YES
 
 # Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any
 # special comment blocks from generated source code fragments. Normal C, C++ and
@@ -2030,7 +2030,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2070,7 +2070,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = DOXYGEN_SKIP_SECTION
+PREDEFINED = DOXYGEN_SKIP_SECTION AVM_TASK_DRIVER_ENABLED ENABLE_ADVANCED_TRACE OTP_SOCKET_LWIP
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -2316,7 +2316,7 @@ DOT_IMAGE_FORMAT       = png
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INTERACTIVE_SVG        = NO
+INTERACTIVE_SVG        = YES
 
 # The DOT_PATH tag can be used to specify the path where the dot tool can be
 # found. If left blank, it is assumed the dot tool can be found in the path.

doc/_templates/versions.html

@@ -11,14 +11,14 @@
 {# Add rst-badge after rst-versions for small badge style. #}
   <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
     <span class="rst-current-version" data-toggle="rst-current-version">
-      <span class="fa fa-book">AtomVM Docs</span>
-      v: {{ current_version }}
+      <span class="fa fa-download"></span><span class="fa fa-book"> AtomVM Docs version:</span>
+      {{ current_version }}
       <span class="fa fa-caret-down"></span>
     </span>
     <div class="rst-other-versions">
       {% if versions|length >= 1 %}
       <dl>
-        <dt>{{ _('Versions') }}</dt>
+        <dt><span class="fa fa-book">{{ _(' Versions') }}</span></dt>
         {% for slug, url in versions %}
           {% if slug == current_version %} <strong> {% endif %}
           <dd><a href="{{ url }}">{{ slug }}</a></dd>
@@ -28,7 +28,7 @@
       {% endif %}
       {% if downloads|length >= 1 %}
       <dl>
-        <dt>{{ _('Downloads') }}</dt>
+        <dt><span class="fa fa-download">{{ _(' Downloads') }}</span></dt>
         {% for type, url in downloads %}
           <dd><a href="{{ url }}">{{ type }}</a></dd>
         {% endfor %}

doc/conf.py.in

@@ -63,7 +63,9 @@ extensions = [
 suppress_warnings = [
     'epub.unknown_project_files',
     'misc.highlighting_failure',
-    'toc.excluded'
+    'toc.excluded',
+    'myst.*',
+    'breathe.*'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -164,14 +166,26 @@ repo = Repo( search_parent_directories=True )
 tag_list = sorted(repo.tags, key=lambda t: t.commit.committed_datetime)
 latest_tag = tag_list[-1]
 versions = list()
+release_list = list()
 for tag in tag_list:
     versions.append(tag.name)
+    release_list.append(tag.name)
+
+omit_branch_list = ('release-0.5')
+branch_list = sorted(repo.branches, key=lambda t: t.commit.committed_datetime)
+for branch in branch_list:
+    if branch.name not in omit_branch_list:
+        versions.append(branch.name)
 
-versions.append('main')
 if ((repo.head.object.hexsha) == (latest_tag.commit.hexsha)):
     current_version = latest_tag.name
+    download_version = current_version
 else:
-    current_version = 'main'
+    download_version = '@DOC_TREE_VERSION@'
+    if ((download_version) == ('main')):
+        current_version = download_version + ' branch (unstable)'
+    else:
+        current_version = download_version + ' branch (unreleased)'
 
 print("Sphinx config found documentation candidates: %r." % (versions))
 print("Sphinx config current version: %r." % (current_version))
@@ -184,7 +198,13 @@ html_context['version'] = current_version
 # POPULATE LINKS TO OTHER VERSIONS
 html_context['versions'] = list()
 for version in versions:
-    html_context['versions'].append( (version, '/doc/' +version+ '/') )
+    if ((version) == ('main')):
+        html_context['versions'].append( (version + ' branch (unstable)', '/doc/' +version+ '/') )
+    else:
+        if (version not in release_list):
+            html_context['versions'].append( (version + ' branch (unreleased)', '/doc/' +version+ '/') )
+        else:
+            html_context['versions'].append( (version, '/doc/' +version+ '/') )
 
 html_sidebars = {
     '**': [
@@ -194,14 +214,14 @@ html_sidebars = {
 
 # POPULATE LINKS TO OTHER FORMATS/DOWNLOADS
 html_context['downloads'] = list()
-html_context['downloads'].append( ('pdf', '/doc/' +current_version+ '/pdf/' +project+ '-' +current_version+ '.pdf') )
-html_context['downloads'].append( ('epub', '/doc/' +current_version+ '/epub/' +project+ '-' +current_version+ '.epub') )
+html_context['downloads'].append( ('pdf', '/doc/' +download_version+ '/pdf/' +project+ '-' +download_version+ '.pdf') )
+html_context['downloads'].append( ('epub', '/doc/' +download_version+ '/epub/' +project+ '-' +download_version+ '.epub') )
 
 # -- Options for PDF output -------------------------------------------------
 
 rinoh_documents = [dict(
   doc=master_doc,
-  target=project+ '-' +current_version,
+  target=project+ '-' +download_version,
   logo='@CMAKE_CURRENT_SOURCE_DIR@/src/_static/AtomVM-logo.png',
   template='pdf_template.rtt'
 )]
@@ -212,4 +232,4 @@ today_fmt = "%B %d, %Y"
 
 epub_tocdepth = 3
 epub_show_urls = 'no'
-epub_basename = project+ '-' +current_version
+epub_basename = project+ '-' +download_version

doc/pdf_stylesheet.rts

@@ -8,3 +8,6 @@ base = sphinx
 
 [linked reference]
 type = custom
+
+[chapter]
+page_break = any