update macOS instructions

Author: hturner

working_documents/comments_on_install_r_macOS.md

@@ -61,6 +61,8 @@ I worked through Heather's notes during the RProject Sprint, on Sept 1st
     > with the idea that if you had multiple builds of R you could have
     > them nested under those directories. Will poll R Contributors to
     > help decide what is best.
+    >
+    > (gone with second option for now)
 
 3.  In Build R, point 3 for Apple Silicon only, in line before `EOF`,
     need to add CPPFLAGS to link to the headers for liblzma:
@@ -115,8 +117,7 @@ from `config.site` (it's not needed once gfortran is in the PATH).
     --without-recommended-packages
     ```
     
-    > HT: We should try to find a non-hacky way to build with recommended 
-    packages.
+    > HT: Fixed by updating LDFLAGS. Not sure if this applies to Intel too.
 
 6.  Need to install java or turn it off!
 
@@ -139,5 +140,4 @@ from `config.site` (it's not needed once gfortran is in the PATH).
 After `make check`, if still in `build` directory, need to run `bin/R`
 to start newly build
 
-> HT: Assume that people will switch with RSwitch/rig and then use RStudio/usual 
-IDE.
+> HT: Fixed by adding `make install` step.

working_documents/install_r_macos.Rmd

@@ -1,7 +1,7 @@
 ---
 title: "Installing R from Source on macOS"
 output: github_document
-date: "2023-08-11"
+date: "2023-12-11"
 editor_options: 
   markdown: 
     wrap: 72
@@ -13,23 +13,30 @@ knitr::opts_chunk$set(eval = FALSE)
 
 ## Prerequisites
 
+Some details and notes are hidden by default - click the black arrowhead to 
+expand or collapse these sections.
+
 ### Set up R installation directory
 
 Open Terminal.app and follow these instructions:
 
-1.  Set `LOCAL` as an environment variable to match your architecture
+1.  Set `LOCAL` as a temporary environment variable to match your architecture
+    ```{sh}
+# Intel
+export LOCAL=/opt/R/x86_64 
+    ```
     ```{sh}
-set LOCAL=/opt/R/x86_64 # Intel
-set LOCAL=/opt/R/arm64  # Apple Silicon (e.g. M1)
+# Apple Silicon (e.g. M1)
+export LOCAL=/opt/R/arm64  
     ```
 2.  Make your account own `/opt/R` so that we can install prerequisites for 
 building from source with the helper R script described in the next subsection.
     ```{sh}
 sudo chown -R $USER /opt/R
     ```
-    <details><summary>Details</summary> If this is skipped, get errors when 
-running `install.libs("r-base-dev")`, e.g. " Can't restore time", 
-"Can't unlink already-existing object"
+    <details><summary><i>Details...</i></summary> If this is skipped, you get errors when 
+running `install.libs("r-base-dev")`, e.g. "Can't restore time", 
+"Can't unlink already-existing object".
     </details>
 3.  Add `$LOCAL/bin` to your path
     ```{sh}
@@ -38,17 +45,17 @@ cat << EOF >> /Users/$USER/.zprofile
 export PATH="$LOCAL/bin:\${PATH}"
 EOF
     ```
+   <details><summary><i>Note if using RStudio terminal, or using Terminal.app on macOS < 10.15 (Catalina)...</i></summary> The code above assumes you are using a Zsh shell (the default on macOS &ge; 10.15). If you are using a bash shell, replace <code>.zprofile</code> with <code>.bash_profile</code>. The type of terminal in RStudio can be set in Terminal Options from the terminal or in Global Options.
+</details>
+   </details>
 4.  If you have previously installed R on the computer, make your account own the existing R framework folder
     ```{sh}
 sudo chown -R $USER /Library/Frameworks/R.framework/
    ```
-   Otherwise, download the installer for the latest release of R from CRAN and install with the default settings.
+   Otherwise, download the installer for the latest release of R from CRAN and install with the default settings first. 
 
 ### Install prerequisites
 
-It is best to install prerequisites before first building R from source, 
-even if you think you may have installed some of the prerequisites before.
-
 1.  Install Xcode Command Line Tools from the terminal
     ```{sh}
     xcode-select --install
@@ -69,25 +76,34 @@ install.libs("r-base-dev")
     ```{r}
 install.libs("pango")
     ```
-6.  TODO, guidance for installing MacTex for those that need it
+6.  Check if you have a current version of MacTeX installed:
+    ```{sh}
+ls /usr/local/texlive
+    ```
+    If the `/usr/local/texlive` directory exists, you will see one or more subdirectories named by year, e.g.
+    ```
+    2022            2023            texmf-local
+    ```
+    If this check doesn't show a subdirectory for the current year, install MacTex from the binary at <https://tug.org/mactex/mactex-download.html>.
 7.  In the terminal, check if you already have Subversion installed:
 
     ```{sh}
     which svn
     ```
     
-    This with show a path where Subversion is installed, or `svn not found`. 
+    This will show a path where Subversion is installed, or `svn not found`. 
     If necessary, install Subversion from within R:
 
     ```{r}
     install.libs("subversion", dep = FALSE)
     ```
     
-    <details><summary>Troubleshooting</summary> If this does not work, try installing via your preferred package manage, e.g. with Homebrew: <code>brew install svn</code>.
+    <details><summary><i>Troubleshooting...</i></summary> If this does not work, try installing via your preferred package manage, e.g. with Homebrew: <code>brew install svn</code>.
     </details>
     
 8. (Recommended)  If you are not already using a tool such as [rig](https://github.com/r-lib/rig) 
-to install and manage multiple R versions, install RSwitch from <https://rud.is/rswitch/>.
+to install and manage multiple R versions, install RSwitch from <https://rud.is/rswitch/>. These tools are not part of the R Project, but 
+make it easy to switch R versions.
     
 [//]: # (
 * Skip readline (use editline) 
@@ -105,9 +121,6 @@ dependencies at same time
 
 Run the following commands within Terminal.app: 
 
-<details><summary>Note if you prefer to use an RStudio terminal</summary> The PATH setting in <code>~/.zprofile</code> will only work for a zsh terminal, so you may need to change your Global Options or add the PATH setting to <code>~/.bash_profile</code>
-</details>
-
 0. Retrieve R source code into `TOP_SRCDIR`, note that we retrieve the `r-devel` source code:
     ```{sh}
 export TOP_SRCDIR="$HOME/svn/R-devel"
@@ -121,9 +134,9 @@ $TOP_SRCDIR/tools/rsync-recommended
 
 2.  Create the build directory in the `BUILDDIR`:
     ```{sh}
-export BUILDDIR="$HOME/bin/R"
-mkdir -p "$BUILDDIR"
-cd "$BUILDDIR"
+export BUILDDIR="$HOME/build/R-devel"
+mkdir -p $BUILDDIR
+cd $BUILDDIR
     ```
 
 3.  Create `config.site` within the build directory to set some configuration flags as recommended by the [R-admin manual](https://cran.r-project.org/doc/manuals/r-devel/R-admin.html#Prerequisites).
@@ -143,18 +156,18 @@ cat << EOF >> config.site
 CFLAGS="-falign-functions=8 -g -O0"
 FFLAGS="-g -O2 -mmacosx-version-min=11.0"
 FCFLAGS="-g -O2 -mmacosx-version-min=11.0"
-LDFLAGS=-L$LOCAL/lib
+LDFLAGS="-L$LOCAL/lib -L/opt/gfortran/lib"
 CPPFLAGS="-isystem $LOCAL/include -I$LOCAL/include"
 EOF
     ```
-    <details><summary>Details</summary> Some modifications to th: `-O0` to enable debugging symbols and disable compiler optimisations for better debugging experience; `-mmacos-version-min` corrected [?] to `-mmacosx-version-min`; `LDFLAGS=-L$LOCAL/lib` added so that liblzma can be found. CPPFLAGS modified for Apple Silicon to link to the headers for liblzma.
+    <details><summary><i>Details...</i></summary> Some modifications to the recommendations in R-admin: `-O0` to enable debugging symbols and disable compiler optimisations for better debugging experience; `-mmacos-version-min` corrected [?] to `-mmacosx-version-min`; `LDFLAGS="-L$LOCAL/lib -L/opt/gfortran/lib"` added so that liblzma (in `$LOCAL/lib`) and gfortran libraries can be found. CPPFLAGS modified for Apple Silicon to link to the headers for liblzma.
     </details>
 
-4. Configure the R installation with `--enable-R-framework` to install as an application framework so that we can switch between R versions with Rswitch:
+4. Configure the R installation with `--enable-R-framework` to install as an application framework so that we can switch between R versions with RSwitch:
     ```{sh}
 "$TOP_SRCDIR/configure" --enable-R-framework
     ```
-    <details><summary>Details</summary> This assumes you only want to work with one development version of R that will be identified by the Major.Minor version number. To customize the version name use `--enable-R-framework FW=VERSION` where e.g. VERSION=4.4-dev. The compilation options in [R-admin manual](https://cran.r-project.org/doc/manuals/r-devel/R-admin.html#Prerequisites) to define the location of X11 and tcltk libraries do not seem to be necessary.
+    <details><summary><i>Working with multiple devel versions...</i></summary> The code above assumes you only want to work with one development version of R that will be identified by the Major.Minor version number. To customize the version name use `--enable-R-framework FW=VERSION` where e.g. `VERSION=4.4-dev`. The configure options in [R-admin manual](https://cran.r-project.org/doc/manuals/r-devel/R-admin.html#Prerequisites) to define the location of X11 and tcltk libraries do not seem to be necessary.
     </details>
     
 5.  Build R :
@@ -166,7 +179,11 @@ make
 make check
     ```
     `make` will exit with an error if there are any problems.
-    <details><summary>Note if you are using RStudio terminal</summary> `make check` will fail unless you run `unset R_HOME` first
+    <details><summary><i>Note if you are using RStudio terminal...</i></summary> `make check` will fail unless you run `unset R_HOME` first
     </details>
-    
-The built version of R will now be your default version of R. To switch versions, use RSwitch or rig.
+7.  Install the built version of R
+    ```{sh}
+make install
+    ```
+
+The built version of R will now be your default version of R, which you can start by typing `R` in the terminal, or restarting the R session in RStudio, etc. To switch versions, use RSwitch or rig, then restart your R session.