[Doc] clarify distinction between rwasm::build() and rwasm::add_pkg()

[JosiahParry]

I am trying to build an R package for webr but am getting quite confused by the documentation. The docs indicate to use rwasm::build() to build a package. Then in order to add the package to repo so that it can be installable, you must use rwasm::add_pkg() which will build the package again and then add it. When would i use rwasm::build() and not rwasm::add_pkg()?

Additionally, after using rwasm::build(), how can I make the package installable without having to recompile it again with add_pkg()?

[remlapmot]

A cheat solution here is simply to setup a personal r-universe, because that will build a WASM version of all your packages (as well as binary packages for several other operating systems and architectures).

See

• https://ropensci.org/blog/2023/11/17/runiverse-wasm/
• https://github.com/r-universe-org/help?tab=readme-ov-file#how-to-setup-your-personal-universe

[JosiahParry]

Sure, that is helpful but it does not make the doc clearer 🙈 Also, r-universe is on a once-every-hour update schedule so being able to test the build process locally is important.

[georgestagg]

If you are using rwasm::add_pkg() to build an R package and add it to a repo, you can skip the rwasm::build() step. As you have seen, add_pkg() also builds the package from source in any case.

When would i use rwasm::build() and not rwasm::add_pkg()?

The rwasm::build() command is useful for users who have their own R package repository mechanisms already in place. For example, I believe r-universe uses it behind the scenes for building Wasm binaries for its existing personal package repository system.

It is also useful if you are building webR from source, and want to build and bundle additional packages as part of the base installation of webR. Here you would not build a repository, but instead place the built packages in the webR source tree under the packages directory. (This is not current documented, and a more advanced webR developer technique).

If you do not already host an R package repository somewhere, you can use rwasm::add_pkg() to both build the package and add it to a R package repository in a single step, and skip the rwasm::build() step entirely.

---

I agree this is not made clear in the docs that you can skip build() if you're just building packages for a custom webR repo. I'll try to take a look at it when I can, but I'm also happy to accept PRs to improve documentation if anyone would like to do so once they are comfortable building packages.