Skip to content

Commit

Permalink
Touch up the README
Browse files Browse the repository at this point in the history
  • Loading branch information
@coatless
coatless committed Jan 25, 2024
1 parent 694dd73 commit c903509
Show file tree
Hide file tree
Showing 4 changed files with 296 additions and 87 deletions.
209 changes: 158 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,60 @@


# Unified GH Action for webR/R WASM Package Binaries and {pkgdown} Deployment

<!-- badges: start -->

[![R-CMD-check](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/actions/workflows/R-CMD-check.yaml)
[![webr-build-binary](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/actions/workflows/deploy-cran-repo.yml/badge.svg)](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries/actions/workflows/deploy-cran-repo.yml)
[![R-CMD-check](https://github.com/coatless-tutorials/webr-unified-gh-workflow/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/coatless-tutorials/webr-unified-gh-workflow/actions/workflows/R-CMD-check.yaml)
[![webr-build-binary](https://github.com/coatless-tutorials/webr-unified-gh-workflow/actions/workflows/webr-pkgdown-build-and-deploy.yml/badge.svg)](https://github.com/coatless-tutorials/webr-unified-gh-workflow/actions/workflows/webr-pkgdown-build-and-deploy.yml)
<!-- badges: end -->

Example GitHub Action workflow combining creation of developmental
webR/R WASM Package binaries and `{pkgdown}` websites.
## Introduction

Welcome to this tutorial on combining compiling an R package for
[webR](https://docs.r-wasm.org/webr/latest/) and creating a `{pkgdown}`
website using GitHub Actions. In this guide, you will find sample GitHub
Action workflows designed to generate developmental webR/R WASM Package
binaries alongside a `{pkgdown}` website. If you’re eager to streamline
the process of building and deploying your R packages for webR while
also creating a `{pkgdown}` website, you’ve come to the right place.

This repository is part of a series of repositories exploring the topic.
This repository is part of a series exploring three different
approaches:

- [Org-focused webR/WASM Package Repository without a `{pkgdown}`
website
(Preferred)](https://github.com/coatless-tutorials/webr-org-gh-action)
website](https://github.com/coatless-tutorials/webr-org-gh-action)
- This repository serves as an example implementation of the webR
Project’s [Build R packages using GitHub
Actions](https://r-wasm.github.io/rwasm/articles/github-actions.html)
documentation. It focuses on creating an organizational webR/WASM
Package Repository without the inclusion of a `{pkgdown}` website
that is meant to be triggered through workflow dispatches or changes
to a `packages` file. Explore this repository for insights into
structuring your own organization-centric webR package repository
using GitHub Actions.
- **[Unified GitHub Action Deployment using artifacts of R WASM Package
binaries and {pkgdown}
website](https://github.com/coatless-tutorials/webr-unified-gh-workflow)
binaries and
{pkgdown}](https://github.com/coatless-tutorials/webr-unified-gh-workflow)
\[This repository\]**
- This repository introduces a unified approach to GitHub Action
deployment by using artifacts. Unlike the previous strategy, this
allows for the simultaneous deployment of R WASM binaries and the
associated `{pkgdown}` website by using artifacts. This approach
helps prevent a continuous increase in repository size. Explore this
repository to understand how the use of artifacts can streamline
your deployment process while maintaining a clean and efficient
version control history.
- [Separate GitHub Action Deployment onto `gh-pages` branch of R WASM
Package binaries and {pkgdown}
website](https://github.com/coatless-tutorials/webr-github-action-wasm-binaries)
- This repository adopts a workflow approach familiar to R package
developers using `usethis`. It employs separate GitHub Actions for
generating the R WASM package binaries and `{pkgdown}` website. The
key aspect of this approach is the merging and deployment of both
outputs through the `gh-pages` branch. This strategy enhances
clarity in tracking file changes and provides a transparent view of
the deployed content. Explore this repository to understand how this
approach can streamline your R package deployment workflow.

# Overview

Expand All @@ -33,42 +66,124 @@ this is the repository for you! Here’s a summary of what you can find in
the repository:

- [`.github/workflows/webr-pkgdown-build-and-deploy.yml`](.github/workflows/webr-pkgdown-build-and-deploy.yml):
Modified version of [`r-wasm/actions`’
deploy-cran-repo.yml](https://github.com/r-wasm/actions/blob/d21bf7da50e539df543bbee973087ec585deaba6/examples/deploy-cran-repo.yml)
A combined workflow leveraging the
[`r-wasm/actions/build-rwasm`](https://github.com/r-wasm/actions/blob/d21bf7da50e539df543bbee973087ec585deaba6/build-rwasm/README.md)
action to create R WASM packages,
[`r-lib/actions/examples/pkgdown.yml`](https://github.com/r-lib/actions/blob/46e9e5f2d0dd3aa6ee94b8f49bcc146201e90959/examples/pkgdown.yaml)
action to build a `{pkgdown}` website,
[`actions/upload-artifact`](https://github.com/actions/upload-artifact)
action to make available content in a later portion of the workflow,
[`actions/download-artifact`](https://github.com/actions/download-artifact)
action to retrieve a previously created artifact,
[`actions/upload-pages-artifact`](https://github.com/actions/upload-pages-artifact)
to upload an artifact onto GitHub Pages, and
[`actions/deploy-pages`](https://github.com/actions/deploy-pages) to
deploy the artifact onto GitHub Pages.
- [`_pkgdown.yml`](_pkgdown.yml): Usual configuration for a `{pkgdown}`
website.
- [`DESCRIPTION`](DESCRIPTION): Standard description information for an
R package
- [`R/in-webr.R`](R/in-webr.R): Check to see if we’re inside of webR or
not.

## Deployment
## Deployment Strategy

This approach moves away from tracking website deployments in a
`gh-pages` to generating artifacts with GitHub Actions and, then,
deploying them onto GitHub Pages. As a result, the size of the
repository should not grow large with the addition of a webR/R WASM
Package binary. Though, this means that changes associated with new
This strategy diverges from the traditional approach of tracking website
deployments in a `gh-pages` branch. Instead, it opts for generating
artifacts through GitHub Actions and subsequently deploying them onto
GitHub Pages. This alteration ensures that the repository’s size remains
manageable even with the inclusion of a webR/R WASM Package binary.
However, it comes with the trade-off that changes related to new
`{pkgdown}` deployments are no longer tracked in the `gh-pages` branch.
The deployments can be downloaded and explored separately from a `tar`
file as discussed below.

## Setup

You can re-create the necessary parts to automatically compile R WASM
package binaries and make them available on GitHub Pages with:
For the setup, we’re going to aim to use [`{usethis}` R
package](https://github.com/r-lib/usethis) to enable GitHub Pages and
retrieve a workflow for building both R WASM packages and `{pkgdown}`
websites.

``` r
if(!requireNamespace("usethis", quietly = TRUE)) {install.packages("usethis")}
### Setup Github Pages on the Repository

We can enable GitHub pages directly from `usethis` with:

# Ensure GitHub Pages is setup
``` r
if(!requireNamespace("usethis", quietly = TRUE)) {
install.packages("usethis")
}

# Ensure GitHub Pages is set up
usethis::use_github_pages()
```

Another option is directly enabling GitHub Pages on the repository by
following:

1. Click on the **Settings** tab for the repository
2. Under “Code and automation”, select the **Pages** menu item.
3. Under the “Source” option select **GitHub Actions** from the drop
down.
4. In the “Custom Domain” settings, make sure that **Enforce HTTPS** is
checked.

![Example configuration of GitHub
Pages](man/figures/gh-pages-setup-options.png)

### Setup the R WASM Package Build GitHub Action

Next, obtain a copy of the modified GitHub Action workflow that compiles
the R WASM package binaries and deploys them onto GitHub Pages by
committing into the `gh-pages` branch with the following R code:

``` r
# Obtain the modified version of the rwasm repo setup
usethis::use_github_action(
"https://github.com/coatless-tutorials/webr-unified-gh-workflow/blob/main/.github/workflows/webr-pkgdown-build-and-deploy.yml"
)
```

Viola! Binaries will automatically be built on each new commit and
published on the repository’s website served by GitHub Pages.
Or, you can re-create what `usethis` is doing by using:

``` r
# Create the GitHub workflows directory if not present
dir.create(".github/workflows", showWarnings = FALSE, recursive = TRUE)

# Download the GitHub Action workflow into the repository
download.file(
url = "https://github.com/coatless-tutorials/webr-unified-gh-workflow/blob/main/.github/workflows/webr-pkgdown-build-and-deploy.yml",
destfile = ".github/workflows/webr-pkgdown-build-and-deploy.yml"
)

# Block R build from including the GitHub folder
writeLines(
text = "^\.github$",
con = file(".Rbuildignore", "a")
)
```

That’s it! Binaries alongside a `{pkgdown}` website will now be
automatically built upon each new commit and published on the
repository’s website served by GitHub Pages.

## Observing Data Uploaded

When the workflow completes, the packages and `{pkgdown}` website are
uploaded onto GitHub Pages through an artifact. The artifacts are stored
for 90 days (by default) and can be found under the workflow summary:

1. Click on the **Actions** tab for the repository
2. Select a completed build
3. Press the **Summary** option
4. Under “Artifacts”, click on **github-pages** to download the built
repository

![](man/figures/github-actions-webr-repo-github-pages-artifact.png)

**Note:** The size of the `github-pages` deployment is 9.88 MB of
compressed space, while the size of the `rwasmrepo` is only 3.97 MB of
the total compressed space.

## Accessing Binaries

Expand All @@ -92,46 +207,44 @@ The easiest is probably to define the location webR should search for in
`options()`.

``` r
# Run once at the start of the session
options(
webr_pkg_repos = c(
## Run once at the start of the session

# Specify where to search for the R WASM packages
list_of_repos = c(
"https://gh-username.github.io/repo-name",
"https://other-gh-username.github.io/another-repo",
"https://username.r-universe.dev",
"https://repo.r-wasm.org/"
)

# Set the repository URLs
options(
repos = list_of_repos,
webr_pkg_repos = list_of_repos
)

# Call
# Install the R WASM Package
webr::install("pkgname")
```

<div>

> **Note**
> [!NOTE]
>
> This is different than the `repos` option one would usually set since
> webR only checks the [`webr_pkg_repos`
> key](https://github.com/r-wasm/webr/blob/010223433079d1a9ef3eb9bbf73d8eccb38e6adc/packages/webr/R/install.R#L23)
</div>
> key](https://github.com/r-wasm/webr/blob/010223433079d1a9ef3eb9bbf73d8eccb38e6adc/packages/webr/R/install.R#L23);
> however, other R functions like `available.packages()` check the
> `repos` parameter.
Otherwise, you can specify it each time in the `webr::install()`
command:

``` r
webr::install("pkgname", c(
"https://gh-username.github.io/repo-name",
"https://other-gh-username.github.io/another-repo",
"https://username.r-universe.dev",
"https://repo.r-wasm.org/"
)
)
```
webr::install("pkgname", repos = "https://gh-username.github.io/repo-name")

<div>
webr::install("pkgname", repos = list_of_repos)
```

> **Note**
> [!NOTE]
>
> We do not suggest modifying at the initialization phase the
> [`repoUrl`](https://docs.r-wasm.org/webr/latest/api/js/interfaces/WebR.WebROptions.html#repourl)
Expand All @@ -140,11 +253,7 @@ webr::install("pkgname", c(
> as that will limit the packages to only one repository (e.g. the
> custom repository).
</div>

<div>

> **Important**
> [!IMPORTANT]
>
> Please make sure the repository’s [GitHub Pages website is available
> over
Expand All @@ -160,8 +269,6 @@ webr::install("pkgname", c(
>
> Warning: unable to access index for repository http://gh-username.github.io/repo-name/bin/emscripten/contrib/4.3
</div>

## Verify

Go to the [webR REPL Editor](https://webr.r-wasm.org/v0.2.2/) (pinned to
Expand Down
Loading

0 comments on commit c903509

Please sign in to comment.