diff --git a/.gitignore b/.gitignore index 5b6a065..7b732e7 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ .Rhistory .RData .Ruserdata +.DS_Store diff --git a/README.md b/README.md index 0df9cbd..e8b5803 100644 --- a/README.md +++ b/README.md @@ -42,3 +42,103 @@ visualize Warning message: In readLines("./packages") : incomplete final line found on './packages' ``` + +## Setup Github Pages on the Repository + +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 Action** from the drop down. +4. In the "Custom Domain" settings, make sure that **Enforce HTTPS** is checked. + +![Example configuration of GitHub Pages](figures/github-pages-configuration-for-org-repository.png) + +## Trigger a build + +The R WASM Package binaries are either built by updating/committing files in the repository or by manually triggering a workflow deploy. + +You can trigger a workflow deploy by: + +1. Go to the **Actions** tab of the repository +2. Selecting the **Build and deploy wasm R package repository** workflow +3. Clicking on **Run workflow** dropdown +4. Pressing the **Run workflow** button. + +![Example of triggering a manual deployment of the repository](figures/github-pages-trigger-cran-repo-build.png) + +## Usage inside webR + +Inside of a webR session, you can access the built binaries by using the +repository’s GitHub Pages URL, e.g. + +``` +https://gh-username.github.io/repo-name +``` + +This can be set either using `options()` or specifying the location in +each `webr::install()` call. + +The easiest is probably to define the location webR should search for in +`options()`. + +``` r +# Run once at the start of the session +options( + repos = c("https://gh-username.github.io/repo-name", + "https://repo.r-wasm.org/") +) + +# Call +webr::install("pkgname") +``` + +Otherwise, you can specify it each time: + +``` r +webr::install("pkgname", "https://gh-username.github.io/repo-name") +``` + +
+ +> **Important** +> +> Please make sure the repository’s [GitHub Pages website is available +> over +> `HTTPS`](https://docs.github.com/en/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https#enforcing-https-for-your-github-pages-site) +> not `HTTP` (notice the lack of an `s`). You can verify this option was +> selected by: +> +> 1. Going to the repository’s **Settings** page +> 2. Selecting **Pages** under **Code and automation** +> 3. Checking the **Enforce HTTPS** button. +> +> Otherwise, you will receive the error message of: +> +> Warning: unable to access index for repository http://gh-username.github.io/repo-name/bin/emscripten/contrib/4.3 + +
+ +## Verify + +Go to the [webR REPL Editor](https://webr.r-wasm.org/v0.2.2/) (pinned to +v0.2.2) and run the following: + +``` r +# Check if package `{drawr}` is installed +"drawr" %in% installed.packages()[,"Package"] +# Install the binary from a repository +webr::install( + "drawr", + repos = "https://tutorials.thecoatlessprofessor.com/webr-org-gh-action/" +) +# Check to see if the function works +mat_2x2 <- matrix(1:4, nrow = 2) +drawr::draw_matrix(mat_2x2, show_cell_indices = TRUE) +# View help documentation +?drawr::draw_matrix +``` + +You should receive: + +![Screenshot of the webR REPL editor showing how to download from +repository outside of repo.r-wasm.org an R package +binary](figures/webr-repl-example-workflow.png) diff --git a/github-pages-configuration-for-org-repository.png b/figures/github-pages-configuration-for-org-repository.png similarity index 100% rename from github-pages-configuration-for-org-repository.png rename to figures/github-pages-configuration-for-org-repository.png diff --git a/figures/github-pages-trigger-cran-repo-build.png b/figures/github-pages-trigger-cran-repo-build.png new file mode 100644 index 0000000..43c77ad Binary files /dev/null and b/figures/github-pages-trigger-cran-repo-build.png differ diff --git a/figures/webr-repl-example-workflow.png b/figures/webr-repl-example-workflow.png new file mode 100644 index 0000000..3c955b6 Binary files /dev/null and b/figures/webr-repl-example-workflow.png differ