Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Linux install instructions #207

Merged
merged 2 commits into from
Nov 12, 2024
+46 −53
Merged

Update Linux install instructions #207

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b244aa8
update linux install
ErinBecker Oct 29, 2024
028e6eb
updates Linux install instructions
ErinBecker Oct 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 46 additions & 53 deletions learners/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
the required software in the following order.

1. **[Git]** (≥ 2.28 recommended)
2. **[R]** (≥ 4.x)

Check warning on line 30 in learners/setup.md

View workflow job for this annotation

GitHub Actions / Build markdown source files if valid 

 [link text too short]: [R](https://cran.rstudio.org/)
3. **[pandoc]** (≥ 3.x)
4. The lesson infrastructure R packages
i. **[{sandpaper}]** (development version)
Expand Down Expand Up @@ -167,7 +167,7 @@

#### Test your installation

We will wait to test the pandoc installation after we install the
We will wait to test the pandoc installation after we have installed the
infrastructure packages, to make sure it's discoverable by R.

### Infrastructure R packages
Expand Down Expand Up @@ -289,7 +289,7 @@

#### Test your installation

We will wait to test the pandoc installation after we install the
We will wait to test the pandoc installation after we have installed the
infrastructure packages, to make sure it's discoverable by R.

### Infrastructure R packages
Expand All @@ -311,20 +311,18 @@

## Installing on Linux {#linux}

A lot of the documentation for Linux is nuanced because it assumes that if you
use Linux, then you automatically know how to install things by the command
line. I will be providing instructions as best I can for Ubuntu Linux and point
to resourced for other distributions. For Ubuntu/Debian, the default `apt`
repository is often out of date, so you will need to use a
Instructions for installing on Linux are nuanced due to the variety and availability of
libraries and dependencies for each distribution, e.g. Ubuntu is Debian based whereas
Fedora is Red Hat based. These instructions will use Ubuntu as the preferred distribution.
The default `apt` repository is often out of date, so you will need to use a
[Personal Package Archive aka PPA](https://itsfoss.com/ppa-guide/) to install
the latest version of a particular software, which I will include in these
the latest version of a particular software, which will be included in these
instructions.

### Git

You should have git pre-installed on your computer, but it will likely be
outdated. It's okay if this is the case, but if you want to update via `apt`,
you can add the git-core ppa:
Many distributions include git by default, but it is often outdated.
It is useful to try to update in case a newer version is available:

```bash
sudo add-apt-repository ppa:git-core/ppa
Expand All @@ -345,9 +343,9 @@

### R

To install R, you can visit <https://cran.r-project.org/bin/linux/> to check if
your platform is supported. For Ubuntu, there are detailed instructions at:
<https://cran.r-project.org/bin/linux/ubuntu/>. Here are the commands to register
To install R, you can visit [CRAN's Linux page](https://cran.r-project.org/bin/linux/) to check if
your platform is supported. Detailed instructions exist [for Ubuntu](https://cran.r-project.org/bin/linux/ubuntu/).
Here are the commands to register
the PPA on your machine and then install R:

```bash
Expand Down Expand Up @@ -393,11 +391,11 @@

#### Via RStudio (recommended)

Since pandoc comes bundled with RStudio, you can install it by installing the
latest version of RStudio. You can [download the installer from the RStudio
Pandoc comes bundled with RStudio. You can [download the installer from the RStudio
website][RStudio]. When installing RStudio for Linux, your distribution may not
be shown on the landing page (e.g. Ubuntu 20.04). In this case, choose the most
recent version and download it to your Downloads folder or install it directly.
be shown on the landing page. If your Ubuntu version is not listed, check the
[RStudio Previous Versions](https://docs.posit.co/previous-versions/rstudio.html) page
to see if there are builds available.

::::::::::: callout

Expand All @@ -411,45 +409,42 @@

#### Via the pandoc website

If are more comfortable using R from the command line, then you can install
pandoc by clicking the "Download the latest installer" button at
<https://pandoc.org/installing.html>. This will bring you to the release page
on GitHub with a list of installers, and you should choose one of the ones that
says "linux" according to what chip architecture you have (AMD vs ARM).
If you are more comfortable using R from the command line, then you can install
pandoc from the [releases page](https://pandoc.org/installing.html). From the list on the GitHub page,
for Ubuntu, choose the appropriate `.deb` file for your chip architecture (i.e. AMD64 or ARM64).

#### Test your installation

We will wait to test the pandoc installation after we install the
We will wait to test the pandoc installation after we have installed the
infrastructure packages, to make sure it's discoverable by R.

### Infrastructure R packages

Linux packages normally need to be compiled by your system, which can take a
Linux packages normally need to be compiled into binaries by your system, which can take a
long time the first time it happens. RStudio provides a package manager that
pre-compiles Linux binaries. Note that you do not have to be using RStudio to
take advantage of these binaries. The one we are using is set up for Ubuntu
20.04 (focal).
22.04 (jammy).

::::: callout

#### Dependencies of Dependencies

If you are not used to installing software on Linux, it can be frustrating
sometimes because few things ever "just work" when you try to install them. The
sometimes because things can go wrong and it’s not always immediately clear why. The
same is true for some R packages with compiled code.

Some packages require underlying C libraries (e.g. the xml2 library), which are
catalogued for Ubuntu in [The Carpentries R
Universe](https://carpentries.r-universe.dev/ui#builds) and [available via the
API](https://carpentries.r-universe.dev/ui#api). If you want to view the
packages that are required (some of which may already be on your system), you
can use `curl` and `jq` to produce a list:
API](https://carpentries.r-universe.dev/apis). To produce a list
(you may need to `sudo apt install jq` if it is not already on your system):

```bash
curl https://carpentries.r-universe.dev/stats/sysdeps 2> /dev/null | jq -r '.headers[0] | select(. != null)'
```

This list can be sent to `apt-get install` to install everything:
This list can be sent to `apt install` to install everything:

```bash
sudo apt-get install -y \
Expand Down Expand Up @@ -504,9 +499,8 @@

#### Saving these settings for later

Having binary packages for Linux was a game changer when they appeared and it's
a good idea to have the above code run every time you start R so that you can
take advantage of them. Add the code below to your `~/.Rprofile`.
To not have to run this block of code every time you want to update,
add the following code into your `~/.Rprofile` to run it every time you open your terminal:

::::::::::::::::::::::::

Expand Down Expand Up @@ -567,6 +561,7 @@

Use the instructions in these logs to install the correct package from your
terminal and then open R or RStudio and retry installing the packages.
For example, for the error above, use `sudo apt install libxslt1-dev`.

:::::::::::::::::::::

Expand Down Expand Up @@ -620,27 +615,14 @@
```

If the installation did not work, please [raise an issue on
GitHub](https://github.com/carpentries/sandpaper-docs/issues/new) and I can help
troubleshoot.
GitHub](https://github.com/carpentries/sandpaper-docs/issues/new).

## Installation FAQ

### Why does it take 5 lines of code to install the infrastructure?

In the future, this will be ONE line of code!

Since we are currently in the alpha phase of testing, the infrastructure can
update at any moment. Normally, packages will come from
[CRAN](https://glosario.carpentries.org/en/#cran), but our development packages
are not yet on CRAN, so the are stored in The Carpentries and rOpenSci
development repositories.

### Do I really need to use RStudio?

No. We recommend using RStudio for [several reasons that pertain to ease of
use and standardisation across systems](#recommend), but we do not absolutely
require it. If you are able to get Git, R, and pandoc installed on your system,
then you do not need to use RStudio.
As the Workbench packages are in The Carpentries R-Universe and not CRAN,
we need to tell R to get the packages from R-Universe.

### What is an R Library?

Expand All @@ -653,17 +635,25 @@
(as ‘lib’ is unspecified)
```

On Ubuntu, this may look like:

```
Installing packages into ‘/home/<user>/R/x86_64-pc-linux-gnu-library/4.4’
```

This folder is where all of the R packages you install via `install.packages()`
will live. If you ever need to look this up, you can use the `.libPaths()`
function.
function.

### Using a personal library

Sometimes, your R session will issue a warning that says a folder is not
writeable and asks if you would like to use a personal library instead. In this
case, select "yes".

## Using the lesson engine
## Opening your R environment

Throughout the lesson, I will ask you to **open R or RStudio**. If you are using
If you are using
RStudio, you can open it by double-clicking on the RStudio icon in your
application launcher; you do not have to open R separately to use RStudio.

Expand Down Expand Up @@ -712,6 +702,9 @@
](https://docs.github.com/en/github/getting-started-with-github/about-remote-repositories)
and then set them up according to the instructions from GitHub.

It’s recommended to use the SSH protocol, unless you explicitly cannot,
e.g. behind an institutional firewall or proxy.

:::::::::::::::: callout

### Is GitHub's Documentation Confusing?
Expand Down
Loading