Add docs to Mix tasks #41

joustava · 2025-02-05T19:20:33Z

Made changes to the Mix task implementations so that

mix help will now list the available atomvm.* task
mix doc will generate ex docs

Am not sure how to word the moduledoc for the check task though, feedback welcome.

Closes #40

lib/mix/tasks/esp32_flash.ex

lib/mix/tasks/pico_flash.ex

lib/mix/tasks/esp32_flash.ex

petermm · 2025-02-06T08:40:01Z

Looking good, I would back out the readme changes - pending other PR, or wait for it to land and rebase..

And then just the minor nitpicks..

Thanks!

UncleGrumpy · 2025-02-06T22:59:05Z

The check task, if you want to document it verifies that the functions and modules used are either part of the application source (or deps) or supported by AtomVM. This will catch the use of any standard Elixir modules or functions used in the application that are not included in exavmlib.

The packbeam task depends on this one, so users will likely never need to use it directly, but just in case they are wondering what it is doing a short module doc description wouldn’t hurt.

UncleGrumpy · 2025-02-07T16:08:27Z

lib/mix/tasks/packbeam.ex

+  @shortdoc "Bundle the application into an AVM file"
+
+  @moduledoc """
+  Bundle an application into an AVM file that can be flashed to a micro-controller and executed by the AtomVM virtual machine.


Maybe mention running on generic_unix too?
...flashed to a micro-controller and (or directly on a unix host) executed by the AtomVM virtual machine.

UncleGrumpy

Sorry this is turning into a bigger job than you probably anticipated, we all really appreciate your work here ;-). I just found a couple small details. Also if you change your PR description to so say "Closes #40" instead, the issue will automatically be closed when the PR is merged.

UncleGrumpy · 2025-02-07T16:13:59Z

lib/mix/tasks/stm32_flash.ex

+  >
+  > Note. Before running this task, you must flash the AtomVM virtual machine to the target device.
+  >
+  > This tasks depends on a host installation of STM32 tooling, see [](https://www.atomvm.net/doc/main/build-instructions.html#building-for-stm32)


Missing the name for the link here. [STM32 Build Instructions]

Ah, nice catch.

UncleGrumpy · 2025-02-07T16:28:33Z

lib/mix/tasks/uf2create.ex

+  `atomvm.uf2create` task.
+
+    * `:app_start` - The flash address ,in hexademical format, to place the application, default `0x10180000`
+


the :family_id is also an important setting, but I just realized that #34 is still not merged yet, so the parameters and defaults for this setting will change. We can add that later, after we see which PR lands first.

Or create a new issue/PR later? I could pick it up when due.

We can definitely leave that for later. If #34 gets merged first that could be added here, or I can just as easily create a new PR to add documentation for that option.

Such documenting tasks are low-hanging contribution apples to me. 😃

But very appreciated! Documentation was one of the first areas I started making contributions in. It helped me learn a lot about how everything works. It is a big job to get everything documented and keep it accurate and up to date. Contributions of this kind are very valuable to the users, as well as developers - who often get caught up working on new features, or hunting down bugs. It's easy to not think about the documentation for months at a time ;-)

UncleGrumpy

Sorry I didn't catch this little detail sooner;-)

UncleGrumpy · 2025-02-07T18:33:09Z

lib/mix/tasks/packbeam.ex

+  Within your AtomVM mix project run
+
+  `
+  $ mix atomvm.packbeam --start MyProject


The --start module option should only be used to override the :start defined in the :atomvm mix.exs. This would not normally be needed, unless the user had an alternate mode of operation... like a client/server app that normally builds the client, but when building the server uses a different start module.

added. Also made the admonition blocks more prominent where applicable.

UncleGrumpy

Your fixes, brought up another little detail. But this is minor, so feel free to leave things as they are ;-)

UncleGrumpy · 2025-02-07T23:00:19Z

lib/mix/tasks/packbeam.ex

+
+  For example, you can use the `--start` option to specify or override the `start` property.
+  """
+


Since we mentioned the dependencies elsewhere, this is actually another that users will not often need to use directly. The various MCU.flash tasks depend on this one, it is only for generic_unix, or WASM (?) that this task will be required for users.

Not sure I follow. But this is only an example that it is possible to set this flag if needed. Or do you mean that this flag is always needed when running this particular task directly? (I've no problem with changing copy if wished)

I didn't mean the flag, I meant using the atomvm.packbeam task directly is not needed for micro-controllers. The atomvm.esp32.flash, atomvm.stm32.flash, and atomvm.pico.flash all depend on atomvm.packbeam, so using the packbeam task directly is only needed to create an AVM file for generic_unix... and possibly WASM, but I am not up to speed on deploying an Elixir WASM application, so I don't know all the details there.

We mentioned in the uf2create task that the atomvm.pico.flash task depends on uf2create task, so using it directly is not normally needed... I thought we might mention similarly about the atomvm.packbeam task.

UncleGrumpy

This looks fantastic! Just one little typo.

And we need you have you sign off on the commit. Looks like we need a workflow in place to check for that.

This is the very last little detail, I promise! ;-)

UncleGrumpy · 2025-02-09T18:22:24Z

lib/mix/tasks/packbeam.ex

+
+  > #### Info {: .info}
+  >
+  > Normally using this task manually is not required, it is called automatically by `atomvm.esp32.flash`, `atomvm.stm32.flash` nd `atomvm.pico.flash`.


Typo nd -> and ;-)

UncleGrumpy · 2025-02-10T00:00:55Z

To add a signoff to your commit you can use:

git commit --amend --signoff

…or the short option -s to add the sign off.

UncleGrumpy

This looks great! Should be ready to merge. Than you so much for all the effort and putting up with the nit-picking 😁

petermm · 2025-02-13T11:00:40Z

Let's back out mix.lock and it should be good to go.

Adding it at this stage only creates issues, and solves none. (eg is this mix.lock valid on elixir 1.X), will it load outdated ex_doc, once we start using that etc.

Surely we will add mix.lock once it's beneficial, but even then it may be sideloaded in Docs CI - since elixir 1.7-1.19 is theoretically supported, and I foresee a mix.lock conflicting with that, I could just be imagining that, but I'm not gonna investigate.

petermm · 2025-02-15T09:18:10Z

mix.exs

@@ -21,7 +32,8 @@ defmodule ExAtomVM.MixProject do
  # Run "mix help deps" to learn about dependencies.
  defp deps do
    [
-      {:uf2tool,  "1.1.0"}
+      {:uf2tool, "1.1.0"},
+      {:ex_doc, "~> 0.34", only: :dev, runtime: false}


"~> 0.34" -> "~> 0.20"

for maximum compatibility with anybody running old elixir versions..

Good catch!

petermm · 2025-02-15T09:25:12Z

great work @joustava - thank you, and apologies for things not being straightforward...

- mix help will now list the available atomvm task - mix doc will generate ex docs Signed-off-by: Joost Oostdijk <joustava@gmail.com>

petermm reviewed Feb 5, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Outdated Show resolved Hide resolved

petermm reviewed Feb 5, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Show resolved Hide resolved

petermm reviewed Feb 5, 2025

View reviewed changes

lib/mix/tasks/pico_flash.ex Outdated Show resolved Hide resolved

joustava force-pushed the add-help-to-mix-tasks branch from c7339fa to 06751af Compare February 6, 2025 07:22

joustava marked this pull request as draft February 6, 2025 07:24

petermm reviewed Feb 6, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Outdated Show resolved Hide resolved

petermm reviewed Feb 6, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Outdated Show resolved Hide resolved

petermm reviewed Feb 6, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Outdated Show resolved Hide resolved

joustava force-pushed the add-help-to-mix-tasks branch 2 times, most recently from 72daae7 to d2b7dfc Compare February 6, 2025 17:01

joustava marked this pull request as ready for review February 6, 2025 18:11

petermm approved these changes Feb 6, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from d2b7dfc to fb9d347 Compare February 7, 2025 12:28

petermm mentioned this pull request Feb 7, 2025

Use the Config module instead of Mix.Config is deprecated #42

Open

UncleGrumpy reviewed Feb 7, 2025

View reviewed changes

UncleGrumpy suggested changes Feb 7, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from fb9d347 to f61d985 Compare February 7, 2025 18:12

petermm approved these changes Feb 7, 2025

View reviewed changes

UncleGrumpy suggested changes Feb 7, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from f61d985 to ffaa819 Compare February 7, 2025 19:11

UncleGrumpy approved these changes Feb 7, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from ffaa819 to 84af458 Compare February 9, 2025 08:13

UncleGrumpy suggested changes Feb 9, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from 84af458 to 9da76d0 Compare February 9, 2025 20:44

joustava force-pushed the add-help-to-mix-tasks branch from 9da76d0 to 6c4cc2b Compare February 10, 2025 18:43

UncleGrumpy approved these changes Feb 11, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from 6c4cc2b to 14ceda8 Compare February 14, 2025 06:51

petermm reviewed Feb 15, 2025

View reviewed changes

Add docs to Mix tasks

3102630

- mix help will now list the available atomvm task - mix doc will generate ex docs Signed-off-by: Joost Oostdijk <joustava@gmail.com>

joustava force-pushed the add-help-to-mix-tasks branch from 14ceda8 to 3102630 Compare February 15, 2025 19:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs to Mix tasks #41

Add docs to Mix tasks #41

joustava commented Feb 5, 2025 •

edited

Loading

petermm commented Feb 6, 2025

UncleGrumpy commented Feb 6, 2025 •

edited

Loading

UncleGrumpy Feb 7, 2025

UncleGrumpy left a comment •

edited

Loading

UncleGrumpy Feb 7, 2025

joustava Feb 7, 2025

UncleGrumpy Feb 7, 2025

joustava Feb 7, 2025

UncleGrumpy Feb 7, 2025

joustava Feb 7, 2025

UncleGrumpy Feb 7, 2025

UncleGrumpy left a comment

UncleGrumpy Feb 7, 2025

joustava Feb 7, 2025

UncleGrumpy left a comment

UncleGrumpy Feb 7, 2025

joustava Feb 8, 2025

UncleGrumpy Feb 8, 2025 •

edited

Loading

UncleGrumpy Feb 8, 2025

UncleGrumpy left a comment •

edited

Loading

UncleGrumpy Feb 9, 2025

UncleGrumpy commented Feb 10, 2025

UncleGrumpy left a comment

petermm commented Feb 13, 2025

petermm Feb 15, 2025

UncleGrumpy Feb 15, 2025

petermm commented Feb 15, 2025

		`atomvm.uf2create` task.

		* `:app_start` - The flash address ,in hexademical format, to place the application, default `0x10180000`


		For example, you can use the `--start` option to specify or override the `start` property.
		"""

Add docs to Mix tasks #41

Are you sure you want to change the base?

Add docs to Mix tasks #41

Conversation

joustava commented Feb 5, 2025 • edited Loading

petermm commented Feb 6, 2025

UncleGrumpy commented Feb 6, 2025 • edited Loading

Choose a reason for hiding this comment

UncleGrumpy left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

UncleGrumpy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

UncleGrumpy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

UncleGrumpy Feb 8, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

UncleGrumpy left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

UncleGrumpy commented Feb 10, 2025

UncleGrumpy left a comment

Choose a reason for hiding this comment

petermm commented Feb 13, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

petermm commented Feb 15, 2025

joustava commented Feb 5, 2025 •

edited

Loading

UncleGrumpy commented Feb 6, 2025 •

edited

Loading

UncleGrumpy left a comment •

edited

Loading

UncleGrumpy Feb 8, 2025 •

edited

Loading

UncleGrumpy left a comment •

edited

Loading