README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# macrtools

<!-- badges: start -->
[![R-CMD-check](https://github.com/coatless-mac/macrtools/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/rmacoslib/macrtools/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

**This is a work in progress package. Features may be unstable.**

**This is an _unofficial_ project to support users on macOS.**

The repository includes source code for `macrtools`, which is an _R_ package
exclusively for [Apple](https://www.apple.com/)'s macOS operating system. 
This package is designed to recreate the compiled code toolchain used to 
compile the [official macOS R binary on CRAN](https://cran.r-project.org/bin/macosx/) 
by following the steps described on the 
[r-project developer page for macOS `tools`](https://mac.r-project.org/tools/).
The package is able to to setup the compilation toolchain on any Mac that 
meets the standards required to install the official CRAN _R_ binary on macOS.

**Note:** The installer package was developed by [James Joseph Balamuta](https://thecoatlessprofessor.com/) 
and has no connection with the R project’s macOS CRAN maintainers.

## Quick Start

For an overview of how to use the package, please see the following video: 

[![Video: Installing and using the `{macrtools}` package to setup the R Compilation Toolchain for macOS](http://img.youtube.com/vi/_fckF0fefXQ/0.jpg)](https://www.youtube.com/watch?v=_fckF0fefXQ)


### Install the R Package

You can install the development version of `macrtools` from [GitHub](https://github.com/) with:

``` r
# install.packages("remotes")
remotes::install_github("coatless-mac/macrtools")
```

### Install the R Compilation Toolchain using the R Package

With the package installed, the required components can be installed using:

```r
macrtools::macos_rtools_install()
```

This will attempt to install:

- Xcode CLI
- gfortran
- R Development binaries from the Recipes project

The compilation toolchain can be removed by using: 

```r
macrtools::macos_rtools_uninstall()
```

You can optionally install OpenMP support as well using:

```r
macrtools::openmp_install()
```

**Note:** Apple does not include OpenMP in their version of clang. 
OpenMP usage is optional, but recommended for advanced users who wish to
compile packages that use OpenMP for parallel processing.

## Usage

The package is designed to help diagnose, install, and uninstall different 
parts of the macOS R compilation toolchain. 

### Diagnose

The package features two tools that seek to identify if core components are installed: 

```r
# We can check if Xcode CLI is present using:
macrtools::is_xcode_cli_installed()

# We can verify gfortran is present as well
macrtools::is_gfortran_installed()
```

The package can also check to see if the full version of the Xcode (Xcode.app IDE)
is installed.

```r
# See if Xcode.app IDE is in use
macrtools::is_xcode_app_installed()
```

The Xcode.app is a significantly larger development toolkit compared to Xcode CLI.

Optionally, you can also check to see if OpenMP is installed and configured:

```r
# Check if OpenMP is installed and configured
macrtools::is_openmp_installed()
```


### Installation

The next set of functions focus primarily on installing 
different binary packages into the required locations. 

```r
# We can perform a non-interactive installation of Xcode CLI with:
macrtools::xcode_cli_install() 

# We can install gfortran using:
macrtools::gfortran_install()

# And other binaries required for compiling R using:
macrtools::recipes_binary_install('r-base-dev')

# Installs OpenMP and configures Makevars
macrtools::openmp_install()
```

### Uninstall

If we no longer have interest in having development tools present, we can
remove the development tools using: 

```r
# We can remove Xcode CLI using
macrtools::xcode_cli_uninstall()
```

**Note:** This does not remove binaries obtained from recipes, OpenMP, or Xcode.app IDE.

We can individually remove components as well:

```r
# Remove just Xcode CLI
macrtools::xcode_cli_uninstall()

# Remove just gfortran
macrtools::gfortran_uninstall()

# Remove just OpenMP (includes Makevars cleanup)
macrtools::openmp_uninstall()
```

**Note:** This does not yet uninstall the _R_ development binaries.

## Design Decisions

> Why not a macOS installer package (`.pkg`) or Apple Disk Image (`.dmg`) ?

We previously wrote two very successful installer packages (
[`r-macos-rtools`](https://github.com/coatless-mac/r-macos-rtools) and 
[`r-macos-clang`](https://github.com/coatless-mac/r-macos-clang)).
However, as part of the up-keep of the installer package, we needed to have
a yearly subscription to Apple's [Developer program](https://developer.apple.com/),
which has a base cost of ~\$99 and sales tax of about ~\$6 leading to an 
annual expense of ~\$105 per year. Given that we only used the Developer 
account to sign and notarize only the installers packages, we opted not
to continue on this path.

That said, we are grateful to 
Professor Timothy Bates of the [University of Edinburgh](http://www.ed.ac.uk/). He provided the
[initial financial support](https://github.com/coatless-mac/r-macos-clang/issues/5) that allowed for the installer to be
signed and tested.

Moreover, we hope that by placing the logic inside of an _R_ package, the
community of _R_ developers will be able to play a more active role in 
feature development.

### Acknowledgements

We would like to thank the following individuals for their contributions to this project:

- Professor Timothy Bates of the [University of Edinburgh](http://www.ed.ac.uk/) for his financial support in the initial development of the installer package.
- [Anonymous](https://buymeacoffee.com/coatless/t/3983674) for providing a general financial contribution.

## License

AGPL (>=3)