diff --git a/.github/workflows/build-and-test-macos.yaml b/.github/workflows/build-and-test-macos.yaml index 355d7c19f..2ef2e29b4 100644 --- a/.github/workflows/build-and-test-macos.yaml +++ b/.github/workflows/build-and-test-macos.yaml @@ -29,7 +29,7 @@ on: - '*.md' concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/build-and-test-on-freebsd.yaml b/.github/workflows/build-and-test-on-freebsd.yaml index 476e63bbe..adaa6bd2f 100644 --- a/.github/workflows/build-and-test-on-freebsd.yaml +++ b/.github/workflows/build-and-test-on-freebsd.yaml @@ -29,7 +29,7 @@ on: - '*.md' concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/build-and-test-other.yaml b/.github/workflows/build-and-test-other.yaml index 7b0e08295..ceee03c0b 100644 --- a/.github/workflows/build-and-test-other.yaml +++ b/.github/workflows/build-and-test-other.yaml @@ -29,7 +29,7 @@ on: - '*.md' concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true env: diff --git a/.github/workflows/build-and-test.yaml b/.github/workflows/build-and-test.yaml index 7df971de0..1d0b779e7 100644 --- a/.github/workflows/build-and-test.yaml +++ b/.github/workflows/build-and-test.yaml @@ -29,7 +29,7 @@ on: - '*.md' concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/build-docs.yaml b/.github/workflows/build-docs.yaml index 05f425ad2..ce35e350f 100644 --- a/.github/workflows/build-docs.yaml +++ b/.github/workflows/build-docs.yaml @@ -10,12 +10,13 @@ name: Build Docs # Controls when the workflow will run on: - # Triggers the workflow on push request and tag events on master branch + # Triggers the workflow on push request and tag events on main branch pull_request: - tag: + tags: - '**' branches: - - 'master' + - 'main' + - 'release-**' paths: - '.github/workflows/**' - 'CMakeLists.txt' @@ -36,7 +37,7 @@ on: workflow_dispatch: concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true # A workflow run is made up of one or more jobs that can run sequentially or in parallel diff --git a/.github/workflows/check-formatting.yaml b/.github/workflows/check-formatting.yaml index 347cae21e..94cd0dbcf 100644 --- a/.github/workflows/check-formatting.yaml +++ b/.github/workflows/check-formatting.yaml @@ -23,7 +23,7 @@ on: - '**/*.erl' concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/codeql-analysis.yaml b/.github/workflows/codeql-analysis.yaml index a16be2419..08cb38fe9 100644 --- a/.github/workflows/codeql-analysis.yaml +++ b/.github/workflows/codeql-analysis.yaml @@ -33,7 +33,7 @@ on: - cron: '45 18 * * 5' concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/esp32-build.yaml b/.github/workflows/esp32-build.yaml index 09326bc75..638e6778c 100644 --- a/.github/workflows/esp32-build.yaml +++ b/.github/workflows/esp32-build.yaml @@ -22,7 +22,7 @@ on: - 'src/libAtomVM/**' concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/esp32-mkimage.yaml b/.github/workflows/esp32-mkimage.yaml index 528d5c7bf..96c3e2321 100644 --- a/.github/workflows/esp32-mkimage.yaml +++ b/.github/workflows/esp32-mkimage.yaml @@ -25,7 +25,7 @@ permissions: contents: write concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/pico-build.yaml b/.github/workflows/pico-build.yaml index 422b6e769..c8a5954b5 100644 --- a/.github/workflows/pico-build.yaml +++ b/.github/workflows/pico-build.yaml @@ -26,7 +26,7 @@ permissions: contents: write concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/publish-docs.yaml b/.github/workflows/publish-docs.yaml index 30b9532e9..04052c6f1 100644 --- a/.github/workflows/publish-docs.yaml +++ b/.github/workflows/publish-docs.yaml @@ -10,12 +10,13 @@ name: Publish Docs # Controls when the workflow will run on: - # Triggers the workflow on pull request, tag events and pushes on master + # Triggers the workflow on pull request, tag events and pushes on main push: tags: - '**' branches: - - 'master' + - 'main' + - 'release-**' paths: - '.github/workflows/publish-docs.yaml' - 'CMakeLists.txt' diff --git a/.github/workflows/reuse-lint.yaml b/.github/workflows/reuse-lint.yaml index 2c71d7c68..9df27c3df 100644 --- a/.github/workflows/reuse-lint.yaml +++ b/.github/workflows/reuse-lint.yaml @@ -7,7 +7,7 @@ name: REUSE Compliance Check on: [push, pull_request] concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/run-tests-with-beam.yaml b/.github/workflows/run-tests-with-beam.yaml index 897b19eeb..626f7ebd0 100644 --- a/.github/workflows/run-tests-with-beam.yaml +++ b/.github/workflows/run-tests-with-beam.yaml @@ -29,7 +29,7 @@ on: - '*.md' concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/stm32-build.yaml b/.github/workflows/stm32-build.yaml index a23153ea0..08fd82d67 100644 --- a/.github/workflows/stm32-build.yaml +++ b/.github/workflows/stm32-build.yaml @@ -21,7 +21,7 @@ on: - 'src/libAtomVM/**' concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true jobs: diff --git a/.github/workflows/wasm-build.yaml b/.github/workflows/wasm-build.yaml index 3be3ab825..ecbad4059 100644 --- a/.github/workflows/wasm-build.yaml +++ b/.github/workflows/wasm-build.yaml @@ -26,7 +26,7 @@ permissions: contents: write concurrency: - group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/master' && github.ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }} cancel-in-progress: true env: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e8fb7a9e..8f297221c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ AtomVM is open to any contribution. However before contributing, please read carefully our [Code of Conduct](CODE_OF_CONDUCT.md) and the following contribution guidelines. -Please, also make sure to understand the [Apache 2.0 license](LICENSE.md) and the +Please, also make sure to understand the [Apache 2.0 license](LICENSES/Apache-2.0.txt) and the [Developer Certificate of Origin](https://developercertificate.org/). Last but not least, **do not use GitHub issues for vulnerability reports**, read instead the @@ -66,13 +66,13 @@ All source code modules should include copyright headers that are formatted for ### C Code -C source code style is enforced with [clang-format-13](https://releases.llvm.org/13.0.1/tools/clang/docs/ClangFormat.html). To automatically fix a file, run: +C source code style is enforced with [`clang-format-16`](https://releases.llvm.org/16.0.0/tools/clang/docs/ClangFormat.html). To automatically fix a file, run: - clang-format-13 --style=file -i file.c + clang-format-16 --style=file -i file.c #### Indentation -* [K&R identation and braces style](https://en.wikipedia.org/wiki/Indentation_style#K&R_style) +* [K&R indentation and braces style](https://en.wikipedia.org/wiki/Indentation_style#K&R_style) * [Mandatory braces](https://en.wikipedia.org/wiki/Indentation_style#Variant:_mandatory_braces) * 4 space indentation (no tabs) @@ -169,7 +169,7 @@ C source modules (`.c`) should be organized as follows: #### Documentation -[Doxygen Javadoc style](https://www.doxygen.nl/manual/docblocks.html) code comments will be picked up and added to the documentation. Changes will automatically be added to the [libAtomVM Source Files](https://www.atomvm.net/doc/master/c_api_docs.html#libatomvm-source-files) and the [libAtomVM Index](https://www.atomvm.net/doc/master/apidocs/libatomvm/index.html#libatomvm-index). But to have `Data Strucures`, `Types`, `MACROS`, and `Functions` appear in the correct C Library APIs section the corresponding entries must be added to the similarly named `*.rst` files in the `AtomVM/doc/src/apidocs/libatomvm/` directory. The exact names of the flies that need to be altered are: `data_structures.rst`, `functions.rst`, `macros.rst`, and `types.rst`. The other files in the directory handle auto`generated content and do not need to be altered. +[Doxygen Javadoc style](https://www.doxygen.nl/manual/docblocks.html) code comments will be picked up and added to the documentation. Changes will automatically be added to the [libAtomVM Source Files](https://www.atomvm.net/doc/main/c_api_docs.html#libatomvm-source-files) and the [libAtomVM Index](https://www.atomvm.net/doc/main/apidocs/libatomvm/index.html#libatomvm-index). But to have `Data Structures`, `Types`, `MACROS`, and `Functions` appear in the correct C Library APIs section the corresponding entries must be added to the similarly named `*.rst` files in the `AtomVM/doc/src/apidocs/libatomvm/` directory. The exact names of the files that need to be altered are: `data_structures.rst`, `functions.rst`, `macros.rst`, and `types.rst`. The other files in the directory handle auto`generated content and do not need to be altered. In the rare case that a function declaration and definition are both in different header files (rather than the definition in a `*.c` file) this can cause rendering errors for `Doxygen`. The work around for these cases can be demonstrated with this example for the function `sys_listener_destroy` it is documented and declared in `sys.h` and defined as follows in `listeners.h`: diff --git a/README.Md b/README.Md index 382fc4c2d..e3fc08de4 100644 --- a/README.Md +++ b/README.Md @@ -27,10 +27,10 @@ might be supported in a near future. Getting Started =============== There is much more information, including a more complete -["Getting Started Guide"](https://www.atomvm.net/doc/master/getting-started-guide.html), -[extensive documentation](https://www.atomvm.net/doc/master/build-instructions.html), +["Getting Started Guide"](https://www.atomvm.net/doc/main/getting-started-guide.html), +[extensive documentation](https://www.atomvm.net/doc/main/build-instructions.html), [examples](https://www.atomvm.net/sample-code), -detailed [build instructions](https://www.atomvm.net/doc/master/build-instructions.html), +detailed [build instructions](https://www.atomvm.net/doc/main/build-instructions.html), and [contact information](https://www.atomvm.net/contact) available on the [AtomVM](https://atomvm.net) project website. @@ -77,19 +77,19 @@ $ ./src/AtomVM ./tests/libs/eavmlib/test_eavmlib.avm $ ./src/AtomVM ./tests/libs/alisp/test_alisp.avm ``` -Complete [Build Instructions](https://www.atomvm.net/doc/master/build-instructions.html) are +Complete [Build Instructions](https://www.atomvm.net/doc/main/build-instructions.html) are available in the documentation for -[Generic UNIX](https://www.atomvm.net/doc/master/build-instructions.html) (Linux, MacOS, FreeBSD), -[ESP32](https://www.atomvm.net/doc/master/build-instructions.html#building-for-esp32), -[STM32](https://www.atomvm.net/doc/master/build-instructions.html#building-for-stm32), -[Raspberry Pi Pico](https://www.atomvm.net/doc/master/build-instructions.html#building-for-raspberry-pi-pico) +[Generic UNIX](https://www.atomvm.net/doc/main/build-instructions.html) (Linux, MacOS, FreeBSD), +[ESP32](https://www.atomvm.net/doc/main/build-instructions.html#building-for-esp32), +[STM32](https://www.atomvm.net/doc/main/build-instructions.html#building-for-stm32), +[Raspberry Pi Pico](https://www.atomvm.net/doc/main/build-instructions.html#building-for-raspberry-pi-pico) (rp2040), and -[WASM](https://www.atomvm.net/doc/master/build-instructions.html#building-for-nodejs-web) (NodeJS/Web). +[WASM](https://www.atomvm.net/doc/main/build-instructions.html#building-for-nodejs-web) (NodeJS/Web). Project Status ============== -[![Build and Test](https://github.com/atomvm/AtomVM/actions/workflows/build-and-test.yaml/badge.svg?branch=master)](https://github.com/atomvm/AtomVM/actions/workflows/build-and-test.yaml) +[![Build and Test](https://github.com/atomvm/AtomVM/actions/workflows/build-and-test.yaml/badge.svg?branch=main)](https://github.com/atomvm/AtomVM/actions/workflows/build-and-test.yaml) AtomVM is still in its early stages, but it can run simple applications similar to those available in [examples](examples/) and [tests](tests/). diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 504e6766d..ba2365c5a 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -22,22 +22,22 @@ project(doc) # Prepare souces in build directory include(${CMAKE_SOURCE_DIR}/CMakeModules/GetVersion.cmake) -file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static) file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/edoc) file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/src DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/) file(COPY ${CMAKE_SOURCE_DIR}/CONTRIBUTING.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src) file(COPY ${CMAKE_SOURCE_DIR}/CHANGELOG.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src) file(COPY ${CMAKE_SOURCE_DIR}/UPDATING.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src) +file(COPY ${CMAKE_SOURCE_DIR}/CODE_OF_CONDUCT.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src) +file(COPY ${CMAKE_SOURCE_DIR}/LICENSES/Apache-2.0.txt DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src/LICENSES) +file(COPY ${CMAKE_SOURCE_DIR}/SECURITY.md DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/src) configure_file(${CMAKE_CURRENT_SOURCE_DIR}/release-notes.md.in ${CMAKE_CURRENT_BINARY_DIR}/src/release-notes.md @ONLY) file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/edoc/edown_dep DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/) # Configure libAtomVM restucturedtext skeleton. -file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/files) 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) -foreach(SOURCE_TARGET ${SOURCE_FILES}) - set(SOURCE_FILE ${SOURCE_TARGET}) - configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/apidocs/libatomvm/file.rst.in ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/libatomvm/files/${SOURCE_FILE}.rst @ONLY) -endforeach(SOURCE_TARGET) +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) # Support for edoc -> markdown. add_custom_target(edown-escript @@ -46,8 +46,8 @@ add_custom_target(edown-escript COMMENT "Preparing edown escript" VERBATIM ) -# Get the version tree name, tag if this is a tagged commit, otherwise master. -execute_process(COMMAND "bash" "-c" "tag=$(git for-each-ref --points-at=HEAD --format='%(refname:lstrip=2)' refs/tags); ( [ $tag ] && echo $tag ) || echo 'master'" +# 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 ) @@ -58,8 +58,14 @@ execute_process(COMMAND "bash" "-c" "tag=$(git for-each-ref --points-at=HEAD --f file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/erlang) file(COPY ${CMAKE_SOURCE_DIR}/libs/include DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/) -foreach(ERLANG_LIB estdlib eavmlib alisp etest) - set(ERL_LIB ${ERLANG_LIB}) # to allow passing ERL_LIB to gendoc.erl.in +set(ERLANG_LIBS + estdlib + eavmlib + alisp + etest +) + +foreach(ERLANG_LIB ${ERLANG_LIBS}) configure_file(${CMAKE_CURRENT_SOURCE_DIR}/edoc/gendoc.erl.in ${CMAKE_CURRENT_BINARY_DIR}/edoc/${ERLANG_LIB}/gendoc.erl @ONLY) file(COPY ${CMAKE_SOURCE_DIR}/libs/${ERLANG_LIB} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/edoc/) add_custom_target(edoc-${ERLANG_LIB} @@ -82,7 +88,6 @@ set(DOT_FILES find_package(Graphviz) if(GRAPHVIZ_FOUND) message("Graphiz found") - file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/src/_static) foreach(DOT_FILE ${DOT_FILES}) add_custom_command( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/src/_static/${DOT_FILE}.svg @@ -91,7 +96,7 @@ if(GRAPHVIZ_FOUND) WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Generating SVG for ${DOT_FILE}.dot" VERBATIM ) - set(ERLANG_DOTFILE_TARGETS ${ERLANG_DOTFILE_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/src/_static/${DOT_FILE}.svg) + set(DOTFILE_TARGETS ${DOTFILE_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/src/_static/${DOT_FILE}.svg) endforeach() else() message("WARNING: Graphviz not found. Some images may be missing in generated documentation.") @@ -102,30 +107,31 @@ 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}/) file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/apidocs/libatomvm) add_custom_target(sphinx-html - ${SPHINX_BUILD_EXECUTABLE} -b html -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/html/ + ${SPHINX_BUILD_EXECUTABLE} -q -b html -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/html/ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Generating Sphinx HTML documentation" VERBATIM - DEPENDS ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} + DEPENDS ${DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ) add_custom_target(sphinx-pdf - ${SPHINX_BUILD_EXECUTABLE} -D exclude_patterns=**/c_api_docs.rst,**/libatomvm/** -b rinoh -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/pdf/ + ${SPHINX_BUILD_EXECUTABLE} -q -D exclude_patterns=apidocs/libatomvm/** -b rinoh -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/pdf/ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Generating Sphinx PDF documentation" VERBATIM - DEPENDS ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py + DEPENDS ${DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ) add_custom_target(sphinx-epub - ${SPHINX_BUILD_EXECUTABLE} -D exclude_patterns=**/c_api_docs.rst,**/libatomvm/** -b epub -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/epub/ + ${SPHINX_BUILD_EXECUTABLE} -q -D exclude_patterns=apidocs/libatomvm/**,LICENSES/** -b epub -c ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/src/ ${CMAKE_CURRENT_BINARY_DIR}/epub/ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} COMMENT "Generating Sphinx EPub documentation" VERBATIM - DEPENDS ${ERLANG_DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ${CMAKE_CURRENT_BINARY_DIR}/conf.py + DEPENDS ${DOTFILE_TARGETS} ${ERLANG_EDOC_TARGETS} ) ## This target is intended for CI `Publish Docs` workflow. @@ -143,17 +149,19 @@ else() endif() ## Fix URLs and change title to include "library" instead of "application" -foreach(LIBAVM_ERL_LIB estdlib eavmlib alisp etest) - add_custom_command(TARGET edoc-${LIBAVM_ERL_LIB} - POST_BUILD +foreach(LIBAVM_ERL_LIB ${ERLANG_LIBS}) + add_custom_command(TARGET edoc-${LIBAVM_ERL_LIB} POST_BUILD + COMMAND find ./ -name *.md -exec sed -i -e "s/\#types/\#data-types/g" {} \; + COMMAND find ./ -name *.md -exec sed -i -e "s/\#index/\#function-index/g" {} \; + COMMAND find ./ -name *.md -exec sed -i -e "s/\#functions/\#function-details/g" {} \; COMMAND sed -i -e "s/\.md/\.html/g; s/application/library/g" ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/erlang/${LIBAVM_ERL_LIB}/README.md - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Fixing html link locations for ${LIBAVM_ERL_LIB}." VERBATIM + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/src/apidocs/erlang/${LIBAVM_ERL_LIB} + COMMENT "Fixing links in ${LIBAVM_ERL_LIB} documentation." VERBATIM ) endforeach(LIBAVM_ERL_LIB) add_custom_target(doc #ALL - DEPENDS ${ERLANG_EDOC_TARGETS} sphinx-html sphinx-pdf sphinx-epub + DEPENDS sphinx-html sphinx-pdf sphinx-epub ) if (TARGET GitHub_CI_Publish_Docs) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 3b3e0523d..48e973178 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -736,7 +736,7 @@ CITE_BIB_FILES = # messages are off. # The default value is: NO. -QUIET = NO +QUIET = YES # The WARNINGS tag can be used to turn on/off the warning messages that are # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES @@ -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 = +EXCLUDE_PATTERNS = */libAtomVM/opcodesswitch.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 @@ -1110,7 +1110,7 @@ IGNORE_PREFIX = # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. -GENERATE_HTML = YES +GENERATE_HTML = NO # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/doc/conf.py.in b/doc/conf.py.in index d25d0b696..20a0b8ff0 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -43,7 +43,7 @@ subprocess.call('doxygen Doxyfile', shell=True) import sphinx_rtd_theme project = 'AtomVM' -copyright = '2017-2023, AtomVM' +copyright = '2017-2024, AtomVM' author = 'github.com/atomvm' version = '@ATOMVM_BASE_VERSION@' release = '@ATOMVM_VERSION@' @@ -57,16 +57,13 @@ extensions = [ 'breathe', 'myst_parser', 'sphinx_rtd_theme', - 'sphinx.ext.graphviz', - 'sphinx.ext.autodoc', - 'sphinx.ext.intersphinx', - 'sphinx.ext.autosectionlabel', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.mathjax', - 'sphinx.ext.ifconfig', - 'sphinx.ext.viewcode', - 'sphinx.ext.inheritance_diagram' + 'sphinx.ext.graphviz' +] + +suppress_warnings = [ + 'epub.unknown_project_files', + 'misc.highlighting_failure', + 'toc.excluded' ] # Add any paths that contain templates here, relative to this directory. @@ -80,20 +77,30 @@ exclude_patterns = ['*/favicon/about.txt'] # The master toctree document. master_doc = 'index' -highlight_language = 'c' +highlight_language = 'guess' primary_domain = 'c' +source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'restructuredtext', + '.md': 'markdown' +} + +# -- Sphinx Extension configuration --------------------------------------------------- + # Breathe configuration breathe_projects = { "libatomvm": "@CMAKE_CURRENT_BINARY_DIR@/xml/" } breathe_default_project = "libatomvm" breathe_default_members = ('members', 'undoc-members') +breathe_show_enumvalue_initializer = True +breathe_show_define_initializer = True +breathe_domain_by_extension = { + "h" : "c", + "c" : "c" +} +breathe_use_project_refids = True -StandaloneHTMLBuilder.supported_image_types = [ - 'image/svg+xml', - 'image/gif', - 'image/png', - 'image/jpeg' -] +myst_heading_anchors = 5 # -- Options for HTML output ------------------------------------------------- @@ -105,21 +112,34 @@ html_logo = '@CMAKE_CURRENT_SOURCE_DIR@/src/_static/avm_logo_banner.png' html_theme_options = { 'logo_only': True, 'style_external_links': True, - 'display_version': True + 'display_version': True, + 'includehidden': False } +StandaloneHTMLBuilder.supported_image_types = [ + 'image/svg+xml', + 'image/gif', + 'image/png', + 'image/jpeg' +] + html_copy_source = False +language = "en" +html_meta = { + "description lang=en": "AtomVM Guides and API Documentation", + "keywords": "AtomVM, Erlang, Elixir, BEAM, IoT, embedded, ESP32, STM32, RP2040, Raspberry Pi Pico, WASM, libAtomVM, eavmlib, packbeam", + "property=og:locale": "en_US" +} + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['@CMAKE_CURRENT_BINARY_DIR@/src/_static'] -source_suffix = { - '.rst': 'restructuredtext', - '.txt': 'restructuredtext', - '.md': 'markdown', -} +html_css_files = [ + 'css/custom.css', +] html_favicon = '@CMAKE_CURRENT_SOURCE_DIR@/src/_static/favicon/favicon.ico' @@ -146,11 +166,11 @@ versions = list() for tag in tag_list: versions.append(tag.name) -versions.append('master') +versions.append('main') if ((repo.head.object.hexsha) == (latest_tag.commit.hexsha)): current_version = latest_tag.name else: - current_version = 'master' + current_version = 'main' print("Sphinx config found documentation candidates: %r." % (versions)) print("Sphinx config current version: %r." % (current_version)) @@ -171,21 +191,24 @@ html_sidebars = { ], } -# settings for creating PDF with rinoh -rinoh_documents = [( - master_doc, - project+ '-' +current_version, - project+ ' Documentation', - '© ' +copyright, +# 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') ) + +# -- Options for PDF output ------------------------------------------------- + +rinoh_documents = [dict( + doc=master_doc, + target=project+ '-' +current_version, + logo='@CMAKE_CURRENT_SOURCE_DIR@/src/_static/AtomVM-logo.png', + template='pdf_template.rtt' )] + today_fmt = "%B %d, %Y" -# settings for EPUB -epub_tocdepth = 6 +# -- Options for EPUB output ------------------------------------------------- + +epub_tocdepth = 3 epub_show_urls = 'no' epub_basename = project+ '-' +current_version - -# 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') ) diff --git a/doc/edoc/edown_dep/rebar.config b/doc/edoc/edown_dep/rebar.config index 82ff3eb51..96f55f60c 100644 --- a/doc/edoc/edown_dep/rebar.config +++ b/doc/edoc/edown_dep/rebar.config @@ -3,7 +3,5 @@ % SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later {erl_opts, [debug_info]}. -{deps, [{edown, {git, "https://github.com/pguyot/edown.git", {ref, "e0201c8ec6444d8d41891f0a5ed2bce42fe944d0"}}}]}. -{plugins, [ - ex_doc -]}. +{deps, [{edown, "~> 0.9.1"}]}. +{plugins, []}. diff --git a/doc/edoc/gendoc.erl.in b/doc/edoc/gendoc.erl.in index 825edf540..aa2ee0be8 100644 --- a/doc/edoc/gendoc.erl.in +++ b/doc/edoc/gendoc.erl.in @@ -30,7 +30,7 @@ main([LibraryName, SrcDir, TgtDir]) -> {ok, AllFiles} = file:list_dir(SrcDir), ErlFiles = [SrcDir ++ "/" ++ F || F <- AllFiles, ends_with(F, ".erl")], ok = edoc:application( - @ERL_LIB@, + @ERLANG_LIB@, ".", [ {doclet, edown_doclet}, @@ -42,7 +42,7 @@ main([LibraryName, SrcDir, TgtDir]) -> {dir, TgtDir} ] ), - io:format("Generated documentation for application ~p using source files ~p into ~s~n", [ + io:format("Generated documentation for library ~p using source files ~p into ~s~n", [ LibraryName, ErlFiles, TgtDir ]). diff --git a/doc/pdf_stylesheet.rts b/doc/pdf_stylesheet.rts new file mode 100644 index 000000000..db0065732 --- /dev/null +++ b/doc/pdf_stylesheet.rts @@ -0,0 +1,10 @@ +# Copyright 2024 Winford (Uncle Grumpy) +# +# SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later + +[STYLESHEET] +name = Restore section link names style sheet +base = sphinx + +[linked reference] +type = custom diff --git a/doc/pdf_template.rtt b/doc/pdf_template.rtt new file mode 100644 index 000000000..349a71ea0 --- /dev/null +++ b/doc/pdf_template.rtt @@ -0,0 +1,8 @@ +# Copyright 2024 Winford (Uncle Grumpy) +# +# SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later + +[TEMPLATE_CONFIGURATION] +name = PDF +template = book +stylesheet = pdf_stylesheet.rts diff --git a/doc/src/_static/css/custom.css b/doc/src/_static/css/custom.css new file mode 100644 index 000000000..04957a5ce --- /dev/null +++ b/doc/src/_static/css/custom.css @@ -0,0 +1,9 @@ +/* SPDX-FileCopyrightText: 2024 Winford (Uncle Grumpy) + * + * SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later +*/ + +/* Fix table widths too wide */ +.wy-table-responsive table td, .wy-table-responsive table th { + white-space: inherit; +} diff --git a/doc/src/atomvm-tooling.md b/doc/src/atomvm-tooling.md index f1c7795cb..5ee743378 100644 --- a/doc/src/atomvm-tooling.md +++ b/doc/src/atomvm-tooling.md @@ -246,7 +246,7 @@ To create an AtomVM packbeam file (ending in `.avm`), first use the `mix.deps` t remote: Counting objects: 100% (17/17), done. remote: Compressing objects: 100% (10/10), done. remote: Total 17 (delta 6), reused 16 (delta 6), pack-reused 0 - origin/HEAD set to master + origin/HEAD set to main You can now use the `atomvm.packbeam` target to create a packbeam (ending in `.avm`) file: diff --git a/libs/eavmlib/src/atomvm.erl b/libs/eavmlib/src/atomvm.erl index f9778a6f6..e9cd15e1c 100644 --- a/libs/eavmlib/src/atomvm.erl +++ b/libs/eavmlib/src/atomvm.erl @@ -178,7 +178,7 @@ add_avm_pack_file(_AVMPath, _Options) -> erlang:nif_error(undefined). %%----------------------------------------------------------------------------- -%% @param name the AVM name. +%% @param Name the AVM name. %% @param Options Options, as a property list. %% @returns `ok | error' %% @doc Close previously opened AVM binary from your application. diff --git a/libs/eavmlib/src/emscripten.erl b/libs/eavmlib/src/emscripten.erl index 1fc0515a6..f0dfadab3 100644 --- a/libs/eavmlib/src/emscripten.erl +++ b/libs/eavmlib/src/emscripten.erl @@ -298,7 +298,7 @@ run_script(_Script) -> %% is run on the main thread. If `async', the script is run asynchronously, i.e. %% the caller does not wait for completion. Only applies if `main_thread' is specified. %% @returns ok --spec run_script(iodata(), [run_script_opt()]) -> ok. +-spec run_script(_Script :: iodata(), _Options :: [run_script_opt()]) -> ok. run_script(_Script, _Options) -> erlang:nif_error(undefined). @@ -316,15 +316,15 @@ promise_resolve(_Promise) -> %% ''' %% and if an Erlang process is registered as `some_proc`, then the process %% will receive a message: -%% ``` +%% 

 %% {emscripten, {call, Promise, <<"message">>}}
-%% '''
+%%
%% and the Javascript caller will wait until `promise_resolve' or `promise_reject' %% is called. If the process doesn't exist, the promise will be rejected with %% 'no_proc'. Likewise if the Promise is garbage collected by the Erlang VM. %% @param _Promise Opaque promise resource %% @param _Value Value to send to Javascript, must be an integer or a string. --spec promise_resolve(promise(), integer() | iodata()) -> ok. +-spec promise_resolve(_Promise :: promise(), _Value :: integer() | iodata()) -> ok. promise_resolve(_Promise, _Value) -> erlang:nif_error(undefined). @@ -337,7 +337,7 @@ promise_reject(_Promise) -> %% This is similar to `promise_resolve' except the promise is rejected. %% @param _Promise Opaque promise resource %% @param _Value Value to send to Javascript, must be an integer or a string. --spec promise_reject(promise(), integer() | iodata()) -> ok. +-spec promise_reject(_Promise :: promise(), _Value :: integer() | iodata()) -> ok. promise_reject(_Promise, _Value) -> erlang:nif_error(undefined). @@ -383,7 +383,10 @@ register_keypress_callback(_Target, _Options) -> %% @param _Target target to register keypress on %% @param _Options options for event handling %% @param _UserData user data passed back --spec register_keypress_callback(html5_target(), register_options(), any()) -> register_result(). +-spec register_keypress_callback( + _Target :: html5_target(), _Options :: register_options(), _UserData :: any() +) -> + register_result(). register_keypress_callback(_Target, _Options, _UserData) -> erlang:nif_error(undefined). @@ -405,7 +408,7 @@ register_keypress_callback(_Target, _Options, _UserData) -> %% %% @param _TargetOrHandle Target or handle %% @returns ok or an error --spec unregister_keypress_callback(html5_target() | listener_handle()) -> +-spec unregister_keypress_callback(_TargetOrHandle :: html5_target() | listener_handle()) -> ok | {error, register_error_reason()}. unregister_keypress_callback(_TargetOrHandle) -> erlang:nif_error(undefined). diff --git a/libs/eavmlib/src/esp.erl b/libs/eavmlib/src/esp.erl index da256c403..c72f12e04 100644 --- a/libs/eavmlib/src/esp.erl +++ b/libs/eavmlib/src/esp.erl @@ -157,7 +157,10 @@ sleep_get_wakeup_cause() -> erlang:nif_error(undefined). %%----------------------------------------------------------------------------- -%% @returns Configure ext0 wakeup +%% @doc Configure gpio wakeup from deep sleep +%% @param Pin number of the pin to use as wakeup event +%% @param Level is the state to trigger a wakeup +%% @returns `ok | error' %% @end %%----------------------------------------------------------------------------- -spec sleep_enable_ext0_wakeup(Pin :: pos_integer(), Level :: 0..1) -> ok | error. @@ -165,10 +168,25 @@ sleep_enable_ext0_wakeup(_Pin, _Level) -> erlang:nif_error(undefined). %%----------------------------------------------------------------------------- -%% @returns Configure ext1 wakeup +%% @doc Configure multiple gpio pins for wakeup from deep sleep +%% @param Mask bit mask of GPIO numbers which will cause wakeup +%% @param Mode used to determine wakeup events +%% +%% The available modes are: +%% +%% +%% +%% +%% +%% +%%
Mode Description
`0' WAKEUP_ALL_LOW
`1' WAKEUP_ANY_HIGH (When chip is ESP32-S2, ESP32-S3, ESP32-C6 or ESP32-H2)
`2' WAKEUP_ANY_LOW
`3' WAKEUP_ANY_HIGH
+%% +%% Note: The operation of these modes can vary with builds from previous versions +%% of the ESP-IDF. The modes described here are valid for AtomVM built with ESP-IDF-v5.1.x. +%% @returns `ok | error' %% @end %%----------------------------------------------------------------------------- --spec sleep_enable_ext1_wakeup(Mask :: non_neg_integer(), Mode :: 0..1) -> ok | error. +-spec sleep_enable_ext1_wakeup(Mask :: non_neg_integer(), Mode :: 0..3) -> ok | error. sleep_enable_ext1_wakeup(_Mask, _Mode) -> erlang:nif_error(undefined). diff --git a/libs/eavmlib/src/gpio.erl b/libs/eavmlib/src/gpio.erl index 6ae3e6367..7a5b345e5 100644 --- a/libs/eavmlib/src/gpio.erl +++ b/libs/eavmlib/src/gpio.erl @@ -25,7 +25,8 @@ %% (General Purpose Input and Output) pins. %% %% Note: `-type pin()' used in this driver refers to a pin number on Espressif -%% chips, or a tuple {GPIO_BANK, PIN} for stm32 chips. +%% chips and normal Raspberry Pi Pico pins, or a tuple {GPIO_BANK, PIN} for STM32 +%% chips and the "extra" GPIOs available on the Pico-W. %% @end %%----------------------------------------------------------------------------- -module(gpio). @@ -197,7 +198,7 @@ set_direction(GPIO, Pin, Direction) -> %%----------------------------------------------------------------------------- %% @param GPIO pid that was returned from `gpio:start/0' %% @param Pin number of the pin to write -%% @param Desired output level to set +%% @param Level the desired output level to set %% @returns ok | error | {error, Reason} %% @doc Set GPIO digital output level %% @@ -443,7 +444,7 @@ deep_sleep_hold_dis() -> %%----------------------------------------------------------------------------- %% @param Pin number of the pin to write -%% @param Desired output level to set +%% @param Level the desired output level to set %% @returns ok | error | {error, Reason} %% @doc Set GPIO digital output level %% diff --git a/libs/eavmlib/src/pico.erl b/libs/eavmlib/src/pico.erl index b504f9e53..4edfb499f 100644 --- a/libs/eavmlib/src/pico.erl +++ b/libs/eavmlib/src/pico.erl @@ -33,11 +33,12 @@ ]). %%----------------------------------------------------------------------------- +%% @param Datetime `calendar:datetime()' to set rtc clock. %% @doc Set the datetime on the RTC. %% The datetime can be obtained through bif erlang:localtime() %% @end %%----------------------------------------------------------------------------- --spec rtc_set_datetime(calendar:datetime()) -> ok. +-spec rtc_set_datetime(Datetime :: calendar:datetime()) -> ok. rtc_set_datetime(_Datetime) -> erlang:nif_error(undefined). diff --git a/libs/eavmlib/src/port.erl b/libs/eavmlib/src/port.erl index 2bcfc6897..c781d5060 100644 --- a/libs/eavmlib/src/port.erl +++ b/libs/eavmlib/src/port.erl @@ -23,7 +23,7 @@ %% @doc AtomVM port driver APIs %% %% This module contains functions that are intended to be used by drivers that -%% rely on a `port' interface rather than `niffs'. +%% rely on a `port' interface rather than `nifs'. %% %% The port driver should be initialized with: %% `open_port({spawn, "Name"}, Param)' @@ -41,7 +41,7 @@ -export([call/2, call/3]). %%----------------------------------------------------------------------------- -%% @param Pid Pid to which to send messages +%% @param Port Pid to which to send messages %% @param Message the message to send %% @returns term() | {error, Reason}. %% @doc Send a message to a given port driver pid. @@ -50,12 +50,12 @@ %% return a term or `{error, Reason}'. %% @end %%----------------------------------------------------------------------------- --spec call(pid(), Message :: term()) -> term(). +-spec call(Port :: pid(), Message :: term()) -> term(). call(Port, Message) -> call(Port, Message, infinity). %%----------------------------------------------------------------------------- -%% @param Pid Pid to which to send messages +%% @param Port Pid to which to send messages %% @param Message the message to send %% @param Timeout the timeout value in milliseconds %% @returns term() | {error, Reason}. @@ -65,7 +65,7 @@ call(Port, Message) -> %% a term or `{error, Reason}', or`{error, timeout}' if the TimeoutMs is reached first. %% @end %%----------------------------------------------------------------------------- --spec call(pid(), Message :: term(), Timeout :: timeout()) -> term() | {error, timeout}. +-spec call(Port :: pid(), Message :: term(), Timeout :: timeout()) -> term() | {error, timeout}. call(Port, Message, Timeout) -> MonitorRef = monitor(port, Port), Port ! {'$call', {self(), MonitorRef}, Message}, diff --git a/libs/estdlib/src/calendar.erl b/libs/estdlib/src/calendar.erl index 7b358192c..64d4fa5af 100644 --- a/libs/estdlib/src/calendar.erl +++ b/libs/estdlib/src/calendar.erl @@ -113,9 +113,10 @@ date_to_gregorian_days(Year, M, D) when Era * 146097 + DoE + 60. %%----------------------------------------------------------------------------- -%% @param DateTime -%% @returns Days number of days -%% @doc Computes the number of gregorian days starting with year 0 and ending at the specified date. +%% @param DateTime the date and time to convert to seconds +%% @returns Seconds number of seconds +%% @doc Computes the number of gregorian seconds starting with year 0 and ending +%% at the specified date and time. %% @end %%----------------------------------------------------------------------------- -spec datetime_to_gregorian_seconds(DateTime :: datetime()) -> integer(). @@ -129,7 +130,7 @@ datetime_to_gregorian_seconds({Date, {Hour, Minute, Second}}) when %%----------------------------------------------------------------------------- %% @equiv day_of_the_week(Y, M, D) -%% @param Date the date for which to retreive the weekday +%% @param Date the date for which to retrieve the weekday %% @returns Weekday day of the week %% @doc Computes the day of the week from the specified date tuple {Year, Month, Day}. %% Returns the day of the week as 1: Monday, 2: Tuesday, and so on. @@ -158,7 +159,7 @@ day_of_the_week(Y, M, D) -> %%----------------------------------------------------------------------------- %% @param Time the time, as an integer, in the specified unit %% @param TimeUnit the time unit -%% @param The date and time (in UTC) converted from the specified time and time unit +%% @returns DateTime The date and time (in UTC) converted from the specified time and time unit %% @doc Convert an integer time value to a date and time in UTC. %% @end %%----------------------------------------------------------------------------- diff --git a/libs/estdlib/src/erlang.erl b/libs/estdlib/src/erlang.erl index 89dd9330c..689325124 100644 --- a/libs/estdlib/src/erlang.erl +++ b/libs/estdlib/src/erlang.erl @@ -925,6 +925,7 @@ demonitor(_Monitor) -> %%----------------------------------------------------------------------------- %% @param Monitor reference of monitor to remove +%% @param Options options list %% @returns `true' %% @doc Remove a monitor, with options. %% If `flush', monitor messages are flushed and guaranteed to not be received. diff --git a/libs/estdlib/src/gen_statem.erl b/libs/estdlib/src/gen_statem.erl index 8429c34c1..539bbfb99 100644 --- a/libs/estdlib/src/gen_statem.erl +++ b/libs/estdlib/src/gen_statem.erl @@ -21,7 +21,7 @@ %%----------------------------------------------------------------------------- %% @doc An implementation of the Erlang/OTP gen_statem interface. %% -%% This module implements a strict susbset of the Erlang/OTP gen_statem +%% This module implements a strict subset of the Erlang/OTP gen_statem %% interface, supporting operations for local creation and management of %% gen_statem instances. %% @@ -169,6 +169,8 @@ stop(ServerRef) -> %%----------------------------------------------------------------------------- %% @param ServerRef a reference to the gen_statem acquired via start +%% @param Reason the reason to supply for stopping +%% @param Timeout maximum time to wait for shutdown %% @returns ok, if the gen_statem stopped; {error, Reason}, otherwise. %% @doc Stop a previously started gen_statem instance. %% diff --git a/libs/estdlib/src/gen_tcp.erl b/libs/estdlib/src/gen_tcp.erl index 8d75df972..b2876f8a2 100644 --- a/libs/estdlib/src/gen_tcp.erl +++ b/libs/estdlib/src/gen_tcp.erl @@ -172,7 +172,7 @@ listen(Port, Options) -> end. %%----------------------------------------------------------------------------- -%% @param ListenSocket the listening socket. +%% @param Socket the listening socket. %% @returns a connection-based (tcp) socket that can be used for reading and writing %% @doc Accept a connection on a listening socket. %% @end @@ -188,7 +188,7 @@ accept({?GEN_TCP_MONIKER, Socket, Module}) -> end. %%----------------------------------------------------------------------------- -%% @param ListenSocket the listening socket. +%% @param Socket the listening socket. %% @param Timeout amount of time in milliseconds to wait for a connection %% @returns a connection-based (tcp) socket that can be used for reading and writing %% @doc Accept a connection on a listening socket. diff --git a/libs/estdlib/src/gen_udp.erl b/libs/estdlib/src/gen_udp.erl index 870a2de4c..8e2efe373 100644 --- a/libs/estdlib/src/gen_udp.erl +++ b/libs/estdlib/src/gen_udp.erl @@ -69,7 +69,7 @@ open(PortNum) -> open(PortNum, []). %%----------------------------------------------------------------------------- -%% @param Port the port number to bind to. Specify 0 to use an OS-assigned +%% @param PortNum the port number to bind to. Specify 0 to use an OS-assigned %% port number, which can then be retrieved via the inet:port/1 %% function. %% @param Options A list of configuration parameters. @@ -98,7 +98,7 @@ open(PortNum, Options) -> %%----------------------------------------------------------------------------- %% @param Socket the socket over which to send a packet %% @param Address the target address to which to send the packet -%% @param Port the port on target address to which to send the packet +%% @param PortNum the port on target address to which to send the packet %% @param Packet the packet of data to send %% @returns ok | {error, Reason} %% @doc Send a packet over a UDP socket to a target address/port. @@ -153,7 +153,7 @@ recv({?GEN_UDP_MONIKER, Socket, Module}, Length, Timeout) -> %% @doc Close the socket. %% @end %%----------------------------------------------------------------------------- --spec close(inet:socket()) -> ok. +-spec close(Socket :: inet:socket()) -> ok. close({?GEN_UDP_MONIKER, Socket, Module}) -> Module:close(Socket). diff --git a/libs/estdlib/src/lists.erl b/libs/estdlib/src/lists.erl index a735b2be9..ce4db474a 100644 --- a/libs/estdlib/src/lists.erl +++ b/libs/estdlib/src/lists.erl @@ -22,7 +22,7 @@ %%----------------------------------------------------------------------------- %% @doc An implementation of the Erlang/OTP lists interface. %% -%% This module implements a strict susbset of the Erlang/OTP lists +%% This module implements a strict subset of the Erlang/OTP lists %% interface. %% @end %%----------------------------------------------------------------------------- @@ -125,7 +125,7 @@ delete(E, [H | T], Accum) -> %% @returns the elements of L in reverse order %% @equiv lists:reverse(L, []) %% @doc Erlang/OTP implementation of this function actually handles few simple -%% cases and calls lists:reverse/2 for the more genertic case. Consequently, +%% cases and calls `lists:reverse/2' for the more generic case. Consequently, %% calling `lists:reverse/1' without a list or with an improper list of two %% elements will fail with a function clause exception on Erlang/OTP and with a %% badarg exception with this implementation. @@ -139,7 +139,7 @@ reverse(_L) -> %% @param L the list to reverse %% @param T the tail to append to the reversed list %% @returns the elements of L in reverse order followed by T -%% @doc Reverse the elements of L, folled by T. +%% @doc Reverse the elements of L, followed by T. %% If T is not a list or not a proper list, it is appended anyway and the result %% will be an improper list. %% @@ -306,7 +306,7 @@ keyreplace(K, I, [H | T], L, NewTuple, NewList) -> %%----------------------------------------------------------------------------- %% @param Fun the function to apply -%% @param Accum0 the initial accumulator +%% @param Acc0 the initial accumulator %% @param List the list over which to fold %% @returns the result of folding Fun over L %% @doc Fold over a list of terms, from left to right, applying Fun(E, Accum) @@ -464,6 +464,7 @@ seq(From, To) when is_integer(From) andalso is_integer(To) andalso From =< To -> %% %% @end %%----------------------------------------------------------------------------- +-spec seq(From :: integer(), To :: integer(), Incr :: integer()) -> list(). seq(From, To, Incr) when (not is_integer(From) orelse not is_integer(To) orelse not is_integer(Incr)) orelse (To < (From - Incr) andalso Incr > 0) orelse diff --git a/libs/estdlib/src/socket.erl b/libs/estdlib/src/socket.erl index 2eb527236..c7f95c807 100644 --- a/libs/estdlib/src/socket.erl +++ b/libs/estdlib/src/socket.erl @@ -445,7 +445,7 @@ sendto(Socket, Data, Dest) -> %%----------------------------------------------------------------------------- %% @param Socket the socket -%% @param Option the option +%% @param SocketOption the option %% @param Value the option value %% @returns `{ok, Address}' if successful; `{error, Reason}', otherwise. %% @doc Set a socket option. diff --git a/libs/estdlib/src/unicode.erl b/libs/estdlib/src/unicode.erl index 7a5172ac5..5f5e87f61 100644 --- a/libs/estdlib/src/unicode.erl +++ b/libs/estdlib/src/unicode.erl @@ -122,7 +122,7 @@ characters_to_binary(_Data, _InEncoding) -> %% for which this function merely returns an error tuple.

%% @param Data data to convert to UTF8 %% @param InEncoding encoding of input data -%% @param InEncoding output encoding +%% @param OutEncoding output encoding %% @return an encoded binary or a tuple if conversion failed. -spec characters_to_binary( Data :: chardata() | latin1_chardata(), InEncoding :: encoding(), OutEncoding :: encoding() diff --git a/libs/etest/src/etest.erl b/libs/etest/src/etest.erl index 7b1a54a5f..2b0ca3b37 100644 --- a/libs/etest/src/etest.erl +++ b/libs/etest/src/etest.erl @@ -49,7 +49,7 @@ %% returns the atom fail. %% @end %%----------------------------------------------------------------------------- --spec test(list(module())) -> ok | fail. +-spec test(Tests :: list(module())) -> ok | fail. test(Tests) -> Results = [{Test, run_test(Test)} || Test <- Tests], case erlang:system_info(machine) of @@ -65,7 +65,7 @@ test(Tests) -> %% @returns ok if X and Y unify; fail otherwise. %% @end %%----------------------------------------------------------------------------- --spec assert_match(term(), term()) -> ok | fail. +-spec assert_match(X :: term(), Y :: term()) -> ok | fail. assert_match(X, X) -> ok; assert_match(_, _) -> fail. @@ -75,7 +75,7 @@ assert_match(_, _) -> fail. %% @returns ok if X and Y are equal; fail otherwise. %% @end %%----------------------------------------------------------------------------- --spec assert_equals(term(), term()) -> ok | fail. +-spec assert_equals(X :: term(), Y :: term()) -> ok | fail. assert_equals(X, Y) -> case X == Y of true -> ok; @@ -87,7 +87,7 @@ assert_equals(X, Y) -> %% @returns ok if X is true; fail otherwise. %% @end %%----------------------------------------------------------------------------- --spec assert_true(boolean()) -> ok | fail. +-spec assert_true(X :: boolean()) -> ok | fail. assert_true(true) -> ok; assert_true(_) -> fail. @@ -96,7 +96,7 @@ assert_true(_) -> fail. %% @returns ok if evaluating F results in Error being raised; fail, otherwise %% @end %%----------------------------------------------------------------------------- --spec assert_exception(fun()) -> ok | fail. +-spec assert_exception(F :: fun()) -> ok | fail. assert_exception(F) -> try F(), @@ -112,7 +112,7 @@ assert_exception(F) -> %% raised; fail, otherwise %% @end %%----------------------------------------------------------------------------- --spec assert_exception(fun(), Class :: throw | error | exit) -> ok | fail. +-spec assert_exception(F :: fun(), Class :: throw | error | exit) -> ok | fail. assert_exception(F, Class) -> try F(), @@ -130,7 +130,7 @@ assert_exception(F, Class) -> %% value E being raised; fail, otherwise %% @end %%----------------------------------------------------------------------------- --spec assert_exception(fun(), Class :: throw | error | exit, E :: any()) -> ok | fail. +-spec assert_exception(F :: fun(), Class :: throw | error | exit, E :: any()) -> ok | fail. assert_exception(F, Class, E) -> try F(), diff --git a/src/libAtomVM/context.h b/src/libAtomVM/context.h index c8ef56da2..2606ff3b9 100644 --- a/src/libAtomVM/context.h +++ b/src/libAtomVM/context.h @@ -399,7 +399,7 @@ bool context_get_process_info(Context *ctx, term *out, term atom_key); * the link. * * @param ctx context to link - * @param link_pid process to link ctx to + * @param monitor_pid process to link ctx to * @return 0 on success */ int context_link(Context *ctx, term monitor_pid); @@ -430,7 +430,7 @@ struct ResourceMonitor *context_resource_monitor(Context *ctx, void *resource); * the link. * * @param ctx context to monitor - * @param link_id process to unlink + * @param monitor_pid process to unlink */ void context_unlink(Context *ctx, term monitor_pid); diff --git a/src/libAtomVM/erl_nif.h b/src/libAtomVM/erl_nif.h index c829a15a6..23d3f256a 100644 --- a/src/libAtomVM/erl_nif.h +++ b/src/libAtomVM/erl_nif.h @@ -231,7 +231,7 @@ int enif_monitor_process(ErlNifEnv *env, void *obj, const ErlNifPid *target_pid, /** * @brief Unmonitor a process * - * @param env current environment + * @param caller_env current environment * @param obj resource used by monitor * @param mon monitor * @return 0 on success diff --git a/src/libAtomVM/externalterm.c b/src/libAtomVM/externalterm.c index 5ec70e993..e82c0d983 100644 --- a/src/libAtomVM/externalterm.c +++ b/src/libAtomVM/externalterm.c @@ -76,11 +76,13 @@ static int serialize_term(uint8_t *buf, term t, GlobalContext *glb); /** * @brief * @param external_term buffer containing external term + * @param size size of the external_term * @param ctx current context in which terms may be stored * @param opts additional opts, such as ExternalTermToHeapFragment for storing parsed * terms in a heap fragment. * are stored in the context heap. * @param bytes_read the number of bytes read off external_term in order to yield a term + * @param copy whether to copy binary data and atom strings (pass `true', unless `external_term' is a const binary and will not be deallocated) * @return the parsed term */ static term externalterm_to_term_internal(const void *external_term, size_t size, Context *ctx, diff --git a/src/libAtomVM/globalcontext.h b/src/libAtomVM/globalcontext.h index b2beb7cd0..9edf703d0 100644 --- a/src/libAtomVM/globalcontext.h +++ b/src/libAtomVM/globalcontext.h @@ -310,7 +310,7 @@ bool globalcontext_is_atom_index_equal_to_atom_string(GlobalContext *glb, int at * @brief Compares a term with an AtomString. * * @details Checks if the given term and the given AtomString refers to the same atom. - * @param glb the global context. + * @param global the global context. * @param atom_a any term of any type, when it is not an atom false is always returned. * @param atom_string_b an atom string, which is the atom length followed by atom characters. * @returns true if they both refer to the same atom, otherwise false. diff --git a/src/libAtomVM/inet.h b/src/libAtomVM/inet.h index a6971201b..e422bcd50 100644 --- a/src/libAtomVM/inet.h +++ b/src/libAtomVM/inet.h @@ -69,7 +69,7 @@ enum inet_protocol /** * @brief Parse an inet protocol - * @param type the inet protocol atom + * @param protocol the inet protocol atom * @param global the global context * @returns the parsed protocol */ diff --git a/src/libAtomVM/module.h b/src/libAtomVM/module.h index e21af0ad7..1af43e65e 100644 --- a/src/libAtomVM/module.h +++ b/src/libAtomVM/module.h @@ -240,6 +240,7 @@ term module_load_literal(Module *mod, int index, Context *ctx); * @details Gets an AtomString for the given local atom id from the global table. * @param mod the module that owns the atom. * @param local_atom_id module atom table index. + * @param glb the global context. * @return the AtomString for the given module atom index. */ static inline AtomString module_get_atom_string_by_id(const Module *mod, int local_atom_id, GlobalContext *glb) diff --git a/src/libAtomVM/opcodesswitch.h b/src/libAtomVM/opcodesswitch.h index e4675e10b..b27df2be3 100644 --- a/src/libAtomVM/opcodesswitch.h +++ b/src/libAtomVM/opcodesswitch.h @@ -1506,9 +1506,7 @@ static bool maybe_call_native(Context *ctx, AtomString module_name, AtomString f int read_core_chunk(Module *mod) #else #ifdef IMPL_EXECUTE_LOOP - #ifndef DOXYGEN_SKIP_SECTION /* documented in context.h */ int context_execute_loop(Context *ctx, Module *mod, const char *function_name, int arity) - #endif /* DOXYGEN_SKIP_SECTION */ #else #error Need implementation type #endif diff --git a/src/libAtomVM/otp_net.c b/src/libAtomVM/otp_net.c index 2befda00f..db8ea77a0 100644 --- a/src/libAtomVM/otp_net.c +++ b/src/libAtomVM/otp_net.c @@ -106,7 +106,7 @@ static term eai_errno_to_term(int err, GlobalContext *glb) * @param inner_addr IP address that will be stored in both address and addr * entries of the map * @param global the global context - * @returrn the getaddrinfo result item term + * @return the getaddrinfo result item term * @param heap the heap to create terms in, should have sufficient free space * @details This function is called in a loop to create optimized maps that * share keys. diff --git a/src/libAtomVM/otp_socket.h b/src/libAtomVM/otp_socket.h index e42e3abd7..95143649b 100644 --- a/src/libAtomVM/otp_socket.h +++ b/src/libAtomVM/otp_socket.h @@ -56,6 +56,7 @@ void otp_socket_init(GlobalContext *global); * * @param socket_term the term with the socket * @param otp_socket on output, the socket resource + * @param ctx the current context * @return true in case of success */ bool term_to_otp_socket(term socket_term, struct SocketResource **otp_socket, Context *ctx); @@ -71,7 +72,7 @@ bool term_is_otp_socket(term socket_term); /** * @brief Send data to a socket (without blocking) * - * @param otp_socket the socket resource + * @param socket the socket resource * @param buf buffer to send * @param len number of bytes * @param dest destination address or invalid term for sendto/send @@ -82,7 +83,7 @@ ssize_t socket_send(struct SocketResource *socket, const uint8_t *buf, size_t le /** * @brief Read data from a socket. * - * @param otp_socket the socket resource + * @param socket the socket resource * @param buf buffer to store data * @param len number of bytes * @param flags flags passed to recvfrom diff --git a/src/libAtomVM/resources.h b/src/libAtomVM/resources.h index 9295894a1..cc36f2d5d 100644 --- a/src/libAtomVM/resources.h +++ b/src/libAtomVM/resources.h @@ -89,8 +89,8 @@ static inline void resource_type_destroy(struct ResourceType *resource_type) * * This function calls `sys_unregister_select_event`. * - * @param select_event the event to notify - * @param is_write if the event was selected for reading + * @param event the event to notify + * @param is_read if the event was selected for reading * @param is_write if the event was selected for writing * @param global the global context * @return true if the event was found diff --git a/src/platforms/esp32/tools/CMakeLists.txt b/src/platforms/esp32/tools/CMakeLists.txt index d3d6b0d77..aedcd3389 100644 --- a/src/platforms/esp32/tools/CMakeLists.txt +++ b/src/platforms/esp32/tools/CMakeLists.txt @@ -28,6 +28,8 @@ if(${CONFIG_IDF_TARGET} STREQUAL "esp32s3") set(BOOTLOADER_OFFSET "0x0") elseif(${CONFIG_IDF_TARGET} STREQUAL "esp32c3") set(BOOTLOADER_OFFSET "0x0") +elseif(${CONFIG_IDF_TARGET} STREQUAL "esp32c6") + set(BOOTLOADER_OFFSET "0x0") elseif( ${CONFIG_IDF_TARGET} STREQUAL "esp32s2") set(BOOTLOADER_OFFSET "0x0") endif() diff --git a/tools/test/smoke-test/README.md b/tools/test/smoke-test/README.md index c9a626fa5..7b74cd568 100644 --- a/tools/test/smoke-test/README.md +++ b/tools/test/smoke-test/README.md @@ -151,7 +151,7 @@ Your ESP32 device is now flashed with the ESP32 image you specified. The [`atomvm_examples`](https://github.com/atomvm/atomvm_examples) repo is a good place to start smoke testing. We assume you know how to clone this repo using git. -Note that you will need a supported OTP version and at least a recent version of the [rebar3](https://rebar3.org) tool. If you want to smoke test Elixir programs, you should also have a comaptible version of the Elixir compiler and runtime available. Consult the AtomVM [Relaase Notes](https://www.atomvm.net/doc/master/release-notes.html) for compatibility information. +Note that you will need a supported OTP version and at least a recent version of the [rebar3](https://rebar3.org) tool. If you want to smoke test Elixir programs, you should also have a comaptible version of the Elixir compiler and runtime available. Consult the AtomVM [Relaase Notes](https://www.atomvm.net/doc/main/release-notes.html) for compatibility information. To run an example program, `cd` into the appropriate example directory, and build and flash the program. We will show an example with the [`hello_world`](https://github.com/atomvm/atomvm_examples/tree/master/erlang/hello_world) program.