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

Jump to bottom

Adding installation instructions for Linux #65

Merged
merged 11 commits into from
Oct 25, 2022
Merged

Adding installation instructions for Linux #65

Changes from 2 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
1c2ee7b
Adding installation instructions for Linux
llrs Sep 3, 2022
0cb147f
Fix level of the first title
llrs Sep 3, 2022
ca087f0
Update 02-getting_started.Rmd
llrs Sep 13, 2022
54b63ef
Update 02-getting_started.Rmd
llrs Sep 13, 2022
64d9e15
Update 02-getting_started.Rmd
llrs Sep 13, 2022
a3efc32
Addressing review of Heather Turner
llrs Sep 27, 2022
9ff76a7
Merge remote-tracking branch 'refs/remotes/origin/install' into install
llrs Sep 28, 2022
73b2b5f
Address comments and use BUILDDIR
llrs Oct 1, 2022
7c1eeb4
Add instructions for RStudio in linux
llrs Oct 1, 2022
f518f28
Merged origin/main into install
llrs Oct 25, 2022
2ca7a3e
Update system packages
llrs Oct 25, 2022
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
134 changes: 101 additions & 33 deletions 02-getting_started.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,67 +1,135 @@
# Getting Started {#GetStart}
hturner marked this conversation as resolved.
Show resolved Hide resolved

These instructions cover how to install R in Windows. The tools required to build R and R packages in Windows are also discussed.
These instructions cover how to install R from source.
llrs marked this conversation as resolved.
Show resolved Hide resolved
The tools required to build R and R packages are also discussed.
For the most up to date and complete instructions you can check the [R installation and administration manual](https://cran.r-project.org/doc/manuals/r-devel/R-admin.html) .

## General instructions
## Brief introduction to R source code:
llrs marked this conversation as resolved.
Show resolved Hide resolved

1. If you install the latest version or R-patched or R-devel, it will not over-write the previous installation(s) in your Windows machine.
R uses [svn](https://subversion.apache.org/ "SVN official page") as a version control tool hosted at <https://svn.r-project.org> and uses a 'major.minor.patchlevel' version numbering scheme[^02-getting_started-1].
hturner marked this conversation as resolved.
Show resolved Hide resolved

2. R uses a ‘major.minor.patchlevel’ version numbering scheme. Accordingly there are three main releases of R available to install:
[^02-getting_started-1]: Also known as [semantic versioning](https://en.wikipedia.org/wiki/Software_versioning#Semantic_versioning "Wikipedia explanation of semantic versioning")

* The official release (`r-release`),
There are three releases of R available to install:
hturner marked this conversation as resolved.
Show resolved Hide resolved

* The patched release (`r-patched`), and
- The latest official release (`r-release`),

* The development release (`r-devel`).
- The patched release (`r-patched`), and

The `r-devel` is the next minor or eventually major release development version of R. Mostly, bug fixes are introduced in `r-patched`, while `r-devel` is for introducing new features.
- The development release (`r-devel`).

## Installing R {#installR}
The source code of released versions of R can be found at [R/tags](https://svn.r-project.org/R/tags/ "svn release source code folder"), the patched versions are at [R/branch](https://svn.r-project.org/R/branches/ "svn patched source code folder").

1. The binary builds of R for Windows can be downloaded and installed from [here](https://cran.r-project.org/bin/windows/base/). Along with the link to the latest stable release, this page also contains links to the binary builds of r-patched and r-devel.
The `r-devel` at [R/trunk](trunk "svn devel source code folder") is the next minor or eventually major release development version of R.
llrs marked this conversation as resolved.
Show resolved Hide resolved
Mostly, bug fixes are introduced in `r-patched` and `r-devel`, while `r-devel` is for introducing new features.
llrs marked this conversation as resolved.
Show resolved Hide resolved

2. Click on the download links to download an executable installer.
## Installing R in Linux

3. Select the language while installing, read the GNU general public license information, and select the destination location to start the installation. You will be prompted to select components at this stage: `User installation`, `32-bit User installation`, `64-bit User installation`, or `Custom installation`. The default option may be chosen for the questions from this step onwards to complete the installation.
Here are the basic steps needed meant as a checklist.For complete instructions please see the section in [R-admin](https://cran.r-project.org/doc/manuals/r-devel/R-admin.html#Installing-R-under-Unix_002dalikes)
llrs marked this conversation as resolved.
Show resolved Hide resolved

## Building R and R packages
1. Retrieve R source code via into `TOPSRCDIR`, note that we retrieve the r-devel source code:
llrs marked this conversation as resolved.
Show resolved Hide resolved

### What tools do you need to build R from source on Windows?
svn checkout https://svn.r-project.org/R/trunk/ TOP_SRCDIR

1. [RTools](https://github.com/r-windows/docs/blob/master/faq.md#what-is-rtools) is the toolchain bundle that you can use to build R base and R packages containing compiled code, on Windows.
If you need to install svn you can use your distribution manager to install it.
llrs marked this conversation as resolved.
Show resolved Hide resolved
In Ubuntu you can use :

2. You also need a distribution of LaTeX installed for building R and checking packages. The MiKTeX distribution of LaTeX that is used on CRAN can be downloaded from https://miktex.org.
sudo apt-get install subversion

### How to setup `RTools`?
2. Download the latest recommended packages[^02-getting_started-2]:

1. The latest version of `RTools` can be downloaded from https://cran.r-project.org/bin/windows/Rtools/ and run in the Windows-style installer. You will need to know if you have a 32-bit or 64-bit Windows machine (right-click `This PC` in Windows Explorer and check the properties if you are unsure).
TOP_SRCDIR/tools/rsync-recommended

2. Don't forget to add `RTools` to the path as documented on the download page.
3. Configure indicating where R should be installed (`BUILDDIR`):

### How to build R?
TOP_SRCDIR/configure –prefix=BUILDDIR

To build R for Windows using `RTools` follow the instructions in this [README](https://github.com/r-windows/r-base#readme) file. There are two options available to build R. One is the quick development build and the other option is the full installer build.
or

For development and testing, you need only the quick development build. The quick build avoids building the manuals, which are generally not needed for development and testing.
cd BUILDDIR
TOP_SRCDIR/configure
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two are not equivalent. With the first, when we run make, R will be built in whatever directory we are in - we would need to then run make install to install into BUILDDIR. With the second (if we had created BUILDDIR first) running make would build R inside BUILDDIR (allowing us to run R without installation via BUILDDIR/bin/R) and if we then ran make install it would install in the default location of /usr/local/bin, possibly overwriting an existing R installation!

So there are potentially three locations to consider:

  • source directory (created from tarball/SVN/github) TOP_SRCDIR: say ~/R-svn
  • build directory BUILDDIR: say ~/R-devel-build
    • this is where we run TOP_SRCDIR/configure and make, to keep our source directory clean
  • install directory INSTALLDIR: say ~/R-devel or /usr/local/lib/R-devel or /opt/R/${R_VERSION}.
    • an advantage of using something in the home directory is that you don't need sudo privileges to install, i.e. can just run make install

However, installation is optional, we can just run R from where it is built. This makes sense for a "temporary" version of R, like R-patched or R-devel. So here - as you have done - we can skip the make install. This means we don't have to set the prefix option, but we do need to create a build directory.

I suggest we help readers by getting them to set BUILDDIR and TOP_SRCDIR explicitly, e.g.

export TOP_SRCDIR=$HOME/R-devel-svn
export BUILDDIR=$HOME/R-devel

This means we can make all the instructions ready to copy-paste:

mkdir $BUILDDIR
cd $BUILDDIR
$TOP_SRCDIR/configure
make
make check

It would also be helpful to add instructions for how to build R after you have done it once (not tested):

cd $TOP_SRCDIR
svn update
tools/rsync-recommended
cd $BUILDDIR
$TOP_SRCDIR/configure
make
make check

The problem here is that $TOP_SRCDIR and $BUILDDIR will need to be defined again, or manually edited. Maybe it is better to substitute the recommended values as $HOME is always defined?

I think we should also add instructions for RStudio users, they will need

$TOP_SRCDIR/configure --enable-R-shlib

e.g. "If you plan to use this version of R with RStudio: ... Otherwise:". Note that -- had been turned into an en dash in your code above so make sure it is double dash in the R markdown file.

If users have used the recommended values they can then run R-devel from terminal as follows

$HOME/R-devel/bin/R

or from RStudio (if configured correctly)

export RSTUDIO_WHICH_R=R-devel/bin/R
rstudio

I think it's important to add this so people know how to use the installed R-devel and to make it clear this is separate from their existing R installation, which they can use as normal.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The guide says that " To build in BUILDDIR, run" and just the instructions I have in the guide (but I didn't test without building in the same directory as the source code.

Good point about the three directories (it wasn't really clear to me). Some more comments about it.
Linux users are usually recommended to install optional packages in /opt or $HOME/bin (although I have the TOP_SRCDIR in $HOME/R). As you mention the permission, I think it would be better to just use the later if we use the INSTALLDIR in the guide.

Maybe we can set the source code in TOP_SRCDIR=$HOME/Downloads/R. It might help to think as svn up as a download and the need up upate/"download again".

I am a bit uncomfortable with the BUILDDIR being $HOME/R-devel as it is dangerous close to $HOME/R-dev that devtools::dev_mode() uses as a library directory. I am not sure if we could use $HOME/bin directory for that?

I don't know about the differences between building and installing 😅
Could we use R without installing it for RStudio and other IDEs? If

I tried configuring from $BUILDDIR and building it and I got an error (despite successful $TOP_SRCDIR/configure):

make[1]: Nothing to be done for 'front-matter'.
make[1]: Nothing to be done for 'html-non-svn'.
SVN-REVISION is unchanged
make[1]: Nothing to be done for 'R'.
make[1]: Nothing to be done for 'R'.
make[2]: Nothing to be done for 'R'.
Rmath.h is unchanged
make[3]: Nothing to be done for 'R'.
make[4]: '/home/lluis/Documents/Projects/R/trunk/src/extra/blas/libRblas.so' is up to date.
cp: cannot stat 'libRblas.so': No such file or directory
make[4]: *** [Makefile:56: Rblas_install] Error 1
make[3]: *** [Makefile:39: R] Error 2
make[2]: *** [Makefile:35: make.blas] Error 2
make[1]: *** [Makefile:28: R] Error 1
make: *** [Makefile:61: R] Error 1

Not sure if a bug but it seems that libRblas is assumed to already be in the BUILDDIR and not ported over from TOP_SRCDIR. in the BUILDDIR/src/extras there is a Makefile that doesn't use the BUILDDIR:

# ${R_HOME}/src/extra/blas/Makefile

VPATH = /home/lluis/Documents/Projects/R/trunk/src/extra/blas
srcdir = /home/lluis/Documents/Projects/R/trunk/src/extra/blas
top_srcdir = /home/lluis/Documents/Projects/R/trunk

top_builddir = ../../..
subdir = src/extra/blas
R_HOME = $(top_builddir)


...

For completeness:

TOP_SRCDIR=/home/lluis/Documents/Projects/R/trunk
BUILDDIR=/home/lluis/bin/R-build
# The one liner of configure and building:
cd $TOP_SRCDIR; svn update; tools/rsync-recommended; cd $BUILDDIR; $TOP_SRCDIR/configure; make; make check

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it is important to show how to use the installed from source version it will help for checking packages as well as contributing to R itself. But is this the right place to mention RStudio and the special configuration it needs? I thought to write a separate section for IDEs as many people might not need to use an IDE after a successful make check after modifying the code.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will correct and look for -- and not a em-dash

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea of using TOP_SRCDIR=$HOME/Downloads/R since contributors will only ever be "downloading" from the repository.

I agree using BUILDDIR=$HOME/bin/R-devel should be safer than making an R-devel directory in the users home directory.

This discussion supports the idea of using variables though, as people might want to adjust these locations to their preference and if we define them up front that should be clear and simple.

It is not necessary to install R to use it with RStudio. I doubt this is an issue for Emacs either, not sure about other IDEs.

I think since we are writing these instructions for individual contributors (not sys admins) and we don't want to interfere with any existing installation, then we don't need to run make install. If we did then /opt/R/R-devel would be a good place to install I think, but I can't see any advantage in doing this (we can check about this).

I think we should add to the instructions to delete all files in BUILDDIR before rebuilding as I think not doing this might cause problems like you had.

I think this is the right place to mention configuration options like the one for RStudio as it is annoying if people follow the instructions then find they have to do it all again (or most of it) to use with RStudio.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also as we are not necessarily installing R, perhaps this section should be called "Building R on Linux".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I will change and add the variables and add the RStudio required option for the users


However, even for the quick build there are some [default requirements](https://github.com/r-windows/r-base/blob/master/quick-build.sh). For instance, MikTeX is to be installed in `C:/Program Files` and you have 64-bit R. If necessary, these defaults can be customised. The installation path of MikTex can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L13) whereas the Windows bit can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L6).
4. Build R on the desired folder

If you are a maintainer of the Windows CRAN releases then, the full installer build is available for building the complete installer as it appears on CRAN. It will build both the 32-bit and 64-bit R, the pdf manuals, and the installer program. You will use this to create the binary builds and not when building R from the source yourself.
make

## How to download the R sources directly or from the svn repository?
5. Check that R works as expected:

* To download the R sources on Windows, you can use `tar` from the RStudio terminal.

* If you want to checkout the sources from svn, it is probably best to install an SVN client. Either TortoiseSVN (https://tortoisesvn.net/, command line tool, and Windows Explorer integration) or SlikSVN (https://sliksvn.com/download/, just the command line tool) is recommended. They have simple Windows installers and you can use svn straight-away from Windows cmd or RStudio terminal.
make check

There are other checks you can run:

make check-devel
hturner marked this conversation as resolved.
Show resolved Hide resolved
make check-recommended

[^02-getting_started-2]: Recommended packages are not in the subversion repository.

Once you successfully build R from source you can modify R source code to fix an issue: Prepare a patch (See [this guide](https://www.r-project.org/bugs.html#how-to-submit-patches)) and after checking that R works as intended (`make check-devel`) submit the patch for the R core consideration.
(See the [lifecycle of a patch](#FixBug) chapter).

## Windows

### Installing R {#installR}

1. The binary builds of R for Windows can be downloaded and installed from [here](https://cran.r-project.org/bin/windows/base/).
Along with the link to the latest stable release, this page also contains links to the binary builds of r-patched and r-devel.

2. Click on the download links to download an executable installer.

3. Select the language while installing, read the GNU general public license information, and select the destination location to start the installation.
You will be prompted to select components at this stage: `User installation`, `32-bit User installation`, `64-bit User installation`, or `Custom installation`.
The default option may be chosen for the questions from this step onwards to complete the installation.

### Building R and R packages

#### What tools do you need to build R from source on Windows?

1. [RTools](https://github.com/r-windows/docs/blob/master/faq.md#what-is-rtools) is the toolchain bundle that you can use to build R base and R packages containing compiled code, on Windows.

2. You also need a distribution of LaTeX installed for building R and checking packages.
The MiKTeX distribution of LaTeX that is used on CRAN can be downloaded from <https://miktex.org>.

#### How to setup `RTools`?

1. The latest version of `RTools` can be downloaded from <https://cran.r-project.org/bin/windows/Rtools/> and run in the Windows-style installer.
You will need to know if you have a 32-bit or 64-bit Windows machine (right-click `This PC` in Windows Explorer and check the properties if you are unsure).

2. Don't forget to add `RTools` to the path as documented on the download page.

#### How to build R?

To build R for Windows using `RTools` follow the instructions in this [README](https://github.com/r-windows/r-base#readme) file.
There are two options available to build R.
One is the quick development build and the other option is the full installer build.

For development and testing, you need only the quick development build.
The quick build avoids building the manuals, which are generally not needed for development and testing.

However, even for the quick build there are some [default requirements](https://github.com/r-windows/r-base/blob/master/quick-build.sh).
For instance, MikTeX is to be installed in `C:/Program Files` and you have 64-bit R.
If necessary, these defaults can be customised.
The installation path of MikTex can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L13) whereas the Windows bit can be customised [here](https://github.com/r-windows/r-base/blob/50a229fc76c50a5fb42c0daa367466aaf2318171/quick-build.sh#L6).

If you are a maintainer of the Windows CRAN releases then, the full installer build is available for building the complete installer as it appears on CRAN.
It will build both the 32-bit and 64-bit R, the pdf manuals, and the installer program.
You will use this to create the binary builds and not when building R from the source yourself.

### How to download the R sources directly or from the svn repository?

- To download the R sources on Windows, you can use `tar` from the RStudio terminal.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What could I do w/o RStudio? Couldn't I just dl using a browser? Or maybe using something like wget via Win cmd? Maybe also mention an URL like https://cloud.r-project.org/src/base-prerelease/R-devel.tar.gz? "Untaring" would then be the next step.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As explained in the PR, I didn't touch this section.
I don't assume the guide is only for RStudio users and I will likely modify this section.


- If you want to checkout the sources from svn, it is probably best to install an SVN client.
Either TortoiseSVN (<https://tortoisesvn.net/>, command line tool, and Windows Explorer integration) or SlikSVN (<https://sliksvn.com/download/>, just the command line tool) is recommended.
They have simple Windows installers and you can use svn straight-away from Windows cmd or RStudio terminal.

## See also
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's also https://cran.r-project.org/bin/windows/base/howto-R-devel.html


1. [CRAN official website](https://cran.r-project.org)
1. [CRAN official website](https://cran.r-project.org)

2. [R installation and administration manual](https://cran.r-project.org/doc/manuals/r-patched/R-admin.html)
2. [R installation and administration manual](https://cran.r-project.org/doc/manuals/r-patched/R-admin.html)

3. [R for Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html)
3. [R for Windows FAQ](https://cran.r-project.org/bin/windows/base/rw-FAQ.html)

4. [Rtools40 manual for Windows](https://cran.r-project.org/bin/windows/Rtools/)
4. [Rtools40 manual for Windows](https://cran.r-project.org/bin/windows/Rtools/)

5. [R FAQ](https://cran.r-project.org/doc/FAQ/R-FAQ.html)
5. [R FAQ](https://cran.r-project.org/doc/FAQ/R-FAQ.html)