10-Appendix.Rmd

# (APPENDIX) Appendix {-}

# Installing R Markdown {#install-rm}

Installing R markdown on your computer is pretty straight forward and should be painless. If you're getting started with R markdown we suggest that you use RStudio but of course RStudio is not required and there are other options available. You will also need to install some additional software if you want to render your R markdown documents to PDF format. The steps to do this are given in the following sections for Windows, Mac and Linux computers.

## MS Windows

This guide assumes you have already installed [R][r-proj] and the [RStudio IDE][rstudio]. RStudio is not required but recommended, because it makes it easier to work with R Markdown. If you don't have RStudio IDE installed, you will also have to install [Pandoc][pandoc]. If you have RStudio installed there is no need to install Pandoc separately because it's bundled with RStudio. Next you can install the `rmarkdown` package in RStudio using the following code:

```{r, eval = FALSE}
# Install from CRAN
install.packages('rmarkdown', dep = TRUE)
```

The `dep = TRUE` argument will also install a bunch of additional R packages on which rmarkdown depends.
  
If you want to generate PDF output, you will need to install LaTeX. For R Markdown users who have not installed LaTeX before, we recommend that you install [TinyTeX][tinytex]. You can install TinyTex from within RStudio using the following code:

```{r, eval = FALSE}
install.packages('tinytex')
tinytex::install_tinytex()  # install TinyTeX
```

TinyTeX is a lightweight, portable, cross-platform, and easy-to-maintain LaTeX distribution. The R companion package tinytex can help you automatically install missing LaTeX packages when compiling LaTeX or R Markdown documents to PDF. An alternative option would be to install MiKTeX instead. You can download the latest distribution of [MiKTeX][miktex]. Installing MiKTeX is pretty straight forward, but it can sometimes be a pain to get it to play nicely with RStudio. If at all possible we recommend that you use TinyTex. 

With the rmarkdown package, RStudio/Pandoc, and LaTeX, you should be able to compile most R Markdown documents.

## Mac OSX

This guide assumes you have already installed [R][r-proj] and the [RStudio IDE][rstudio]. RStudio is not required but recommended, because it makes it easier to work with R Markdown. If you do not have RStudio IDE installed, you will also have to install [Pandoc][pandoc]. If you have RStudio installed there is no need to install Pandoc separately because its bundled with RStudio. Next you can install the rmarkdown package in RStudio using the following code:

```{r, eval = FALSE}
# Install from CRAN
install.packages('rmarkdown', dep = TRUE)
```

The `dep = TRUE` argument will also install a bunch of additional R packages on which rmarkdown depends.
  
If you want to generate PDF output, you will need to install LaTeX. For R Markdown users who have not installed LaTeX before, we recommend that you install [TinyTeX][tinytex]. You can install TinyTex from within RStudio using the following code:

```{r, eval = FALSE}
install.packages('tinytex')
tinytex::install_tinytex()  # install TinyTeX
```

TinyTeX is a lightweight, portable, cross-platform, and easy-to-maintain LaTeX distribution. The R companion package tinytex can help you automatically install missing LaTeX packages when compiling LaTeX or R Markdown documents to PDF.

If for some reason TinyTeX does not work on your Mac computer then you can try to install MacTeX instead. You can download the latest version of [MacTeX][mactex]. Click on the *MacTeX.pkg* link to download. Please be aware that the file is quite large, approximately 3 GB, so it may take some time (also make sure you have enough available space on your computer hard disk). When your download is complete, run the downloaded installer. The installation procedure is quite straightforward. You are given a few options, for example you can choose not to install some components. I recommend you stick with the default settings, so having accepted the license agreement, you can basically just keep clicking 'Continue' on each screen. On the final screen of the wizard, click Install. It may ask for an administrator password. Enter the password, click 'Install Software' and go make a cup of coffee while the installation completes. When the program is done installing, click 'Close' to complete the installation.
  
With the rmarkdown package, RStudio/Pandoc, and LaTeX, you should be able to compile most R Markdown documents.

## Linux {#install-rm-linux}

This guide assumes you have already installed [R][r-proj] and the [RStudio IDE][rstudio]. As with Windows and Mac, RStudio is not required but is recommended. If you don't have RStudio installed you will also need to install [Pandoc][pandoc] using your OS package manager, but if you do have RStudio then there's no need as Pandoc is bundled with it. You can then install the `rmarkdown` package in the usual way:

```{r, eval = FALSE}
# Install from CRAN
install.packages('rmarkdown', dep = TRUE)
```

The `dep = TRUE` argument will also install a bunch of additional R packages on which rmarkdown depends.

If you want to generate PDF output you will need a LaTeX distribution. Most Linux distributions offer TeX Live through their package manager, but a full TeX Live installation is a very large download indeed and you almost certainly don't need all of it. We suggest you install [TinyTeX][tinytex] from within R instead:

```{r, eval = FALSE}
install.packages('tinytex')
tinytex::install_tinytex()  # install TinyTeX
```

TinyTeX is a lightweight, portable, cross-platform, and easy-to-maintain LaTeX distribution. The R companion package tinytex can help you automatically install missing LaTeX packages when compiling LaTeX or R Markdown documents to PDF. If you already have a working TeX Live installation on your machine then there's no need to install TinyTeX as well.

With the rmarkdown package, RStudio/Pandoc, and LaTeX, you should be able to compile most R Markdown documents.

\  

# Installing Git {#install_git}

Git is a separate program from R and RStudio and you'll need it installed on your computer before RStudio can do anything useful with it. This Appendix gives a slightly fuller version of the installation instructions in [Section 9.4.1](#install-git). Once Git is installed, head back to [Chapter 9](#github_r) to configure it and connect it to GitHub.

Before you install anything it's worth checking whether you already have Git, as there's a reasonable chance you do (especially on a Mac or Linux machine). Click on the Terminal tab in the Console window in RStudio and type `git --version` (the space after `git` matters). If you see something along the lines of `git version 2.39.3` then you're already sorted and can skip straight to the note on checking that RStudio can find it at the end of this Appendix. If instead you get an error along the lines of `git: command not found` then read on.

**Windows.** Download and run the installer for [Git for Windows][git-win]. There are a great many screens in this installer and you can safely accept the default on every single one of them. Amongst other things it installs a program called Git Bash, which we don't use anywhere in this book but which does no harm sitting there.

**Mac.** The simplest approach is to let macOS install Git for you. Type `git --version` into the Terminal as described above and, if Git isn't installed, macOS will offer to install the Xcode command line tools for you. Accept and wait for it to finish. If you'd rather use a proper installer then you can download one from [git-scm.com][git-mac] and install it by double clicking on the downloaded package in the usual way. If you have previously installed Xcode and want a more up to date version of Git than the one it gave you, there are a few more steps documented [here][git_xcode] (and if you've never heard of Xcode then don't worry about it!).

**Linux.** Git is very often installed already, so do check with `git --version` first. If it isn't, use your OS package manager to install it from the official repository. On Debian and Ubuntu (or variants of) open your Terminal and type

```markup
sudo apt update
sudo apt install git
```

whereas on Fedora you would use

```markup
sudo dnf install git
```

You will need administrative privileges to do either of these. For other flavours of Linux see [here][git-linux] for further installation instructions.

**Checking RStudio can find Git.** Whichever operating system you're using, once the installation has finished verify that it worked by running `git --version` in the Terminal tab in RStudio again. On some installations (MS Windows being the usual culprit) this can still produce an error even though Git installed perfectly well, because RStudio doesn't yet know where to look for it.

To sort this out go to `Tools` -> `Global Options` -> `Git/SVN` in RStudio, make sure that 'Enable version control interface for RStudio projects' is ticked and check that the 'Git executable:' path is correct for your installation. On Windows this path usually ends in `git.exe` and on Mac and Linux in `git`. If the box is empty or the path is wrong, click the `Browse...` button and navigate to where you installed Git. You will need to restart RStudio after doing this.

\  

```{r links, child="links.md"}
```