-
Notifications
You must be signed in to change notification settings - Fork 9
Toolchain Installation
Building packages with C/C++ and Fortran code often requires a bit more than your usual R/RStudio installation. Packages with these code require building from source to compile them. Below is a step-by-step guide to walk you through installing additional components for that will maximize your experience with {EGAnet} (and many other packages).
The effect of these additional installations is maximized when done with a fresh R install and prior to installing any R packages
OS Quick Links: Windows | Mac | Ubuntu/Linux
R conveniently supplies toolchains called Rtools to allow you to build packages from source. There are different versions of Rtools that should correspond to your current version of R (type R.version.string into your console of R/RStudio to find out what version you have). Here are some quick links to jump you to your Rtools version:
It's a good idea to install Rtools before installing any packages in R because many packages have code that needs to be build from source. You can re-download packages from source if you need to though. To see if all went well, try installing {EGAnet} from source:
> install.packages("EGAnet")
If the package successfully installs, then you know you've set Rtools up properly!
Macs are a bit more involved than Windows, requiring several more steps. Most of these steps involve the terminal so go ahead and open it up (search "terminal" to find it).
More than likely, you already have Xcode installed. To check, use the following code in your terminal:
$ xcode-select --version
If you have Xcode, then you should see output that looks like this:
xcode-select version 2373
Your version might differ from the one above but if you can see a version number, then you have Xcode and can skip ahead to Homebrew.
If you don't have Xcode, then you'll need to install it. Installing XCode requires administrator privileges so make sure you are an admin and have your password handy. Type the following code into your terminal
$ sudo xcode-select --install
After the installation is complete, check your version with the code above. You should now see a version meaning you've successfully installed Xcode.
Homebrew is another software that you likely already have. You can use similar code as we did with Xcode to check the installation by checking the version:
$ brew --version
If you have Homebrew installed, then you should see the version pop up:
Homebrew 4.0.28
Your version might differ from the one above but if you can see a version number, then you have Homebrew. Assuming you've already added Homebrew to your PATH, you can skip ahead to gcc. If not, continue reading past the initial install.
If you don't see a version number, then you'll need to install Homebrew. Enter the following code in your terminal:
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Homebrew is used to install and compile many software making it handy regardless of installing R. Once Homebrew is installed, you can add it to your PATH. There is usually some output that says how to do this step after your Homebrew has installed. It will look something like this:
$ echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.bash_profile
and
$ eval "$(/usr/local/bin/brew shellenv)"
Run these lines of code in your terminal and you should be set. Check your version with the code above to ensure it's been installed.
gcc is a compiling engine that makes C/C++ and Fortran go. As with Xcode and Homebrew, you can check if you already have gcc on your computer:
$ gcc --version
gcc is unlikely to be on your computer unless you've installed it before. To install gcc, you can use Homebrew:
$ brew install gcc
The installation might take a while. There are several dependencies that will install prior to gcc, so hang tight. After the installation completes, you can check your version to ensure proper installation.
There are many, many libraries that need to be installed. These can all be installed at the same time but fair warning: This step will take some time.
$ brew install pkg-config gsl openssl libgit2 freetype harfbuzz fribidi libjpeg libtiff glpk
Many of these libraries have dependencies so although this list of libraries might seem long, the number of libraries that will be installed is longer.
This list is NOT exhaustive. Because Mac is Unix-based, it allows the freedom to install libraries as they are needed. This freedom puts some onus on the user to install libraries as they are needed. If you run across an error that says file not found about a some_file.h or some_file.o file, then more than likely you need to install a library. Some R packages will tell you which library while others will not. Copy and paste the error into ChatGPT or a conversational AI of your choice to have them help guide you through which files belong to which libraries.
{XML} is an R package dependency for many R packages and can be relatively tricky to set up. The reason ends up being that the xml2 library can be in multiple places across your computer and you need to use the proper configuration to install {XML}.
The libxml2 from Homebrew worked in this run and hopefully it will work for you. Here's what you need to do:
First, install libxml2 using Homebrew:
$ brew install libxml2
Second, pay attention to where this library installs. You'll need to use the path to tell R which xml2 to compile from. At the end of the installation, you should get something like:
==> Summary
[beer-mug] /usr/local/Cellar/libxml2/2.11.4_1
==> Running `brew cleanup libxml2`...
You'll want to use this path next...
In R, you can go ahead and install {XML} but you'll want to set up the configure.vars to include this path to the xml2-config file:
> install.packages("XML", configure.vars = "XML_CONFIG=/usr/local/Cellar/libxml2/2.11.4_1/bin/xml2-config")
Here's a template for the configure.vars: "XML_CONFIG=/your/path/to/libxml2/VERSION/bin/xml2-config"
With some luck, this install should work.
If you've made it this far, then you're ready to try to install {EGAnet} from source. Let's do it:
> install.packages("EGAnet")
If {EGAnet} successfully installs, then everything worked correctly.
Paths to your files and directories will likely differ than the exact paths that are listed here. You can quickly find paths to files and directories in the terminal using:
$ mdfind file_name
replacing file_name with a file you'd like to find and using:
$ mdfind kind:folder folder_name
replacing folder_name with a folder (directory) you'd like to find.
{data.table} installation guide
Much of the requirements for Ubuntu/Linux are in the form of libraries. There are many libraries that need to be installed but many of them are dependencies. The core libraries that need to be installed, which will automatically install other needed dependencies, are:
$ sudo apt install cmake gfortran libomp-dev libopenblas-dev libxml2-dev libgsl-dev libssl-dev libgit2-dev libfontconfig1-dev libharfbuzz-dev libfribidi-dev libfreetype6-dev libpng-dev libtiff5-dev libjpeg-dev libcurl4-openssl-dev -y
The biggest requirement for the installation process is patience (especially for a clean install). If performing a clean install of R/RStudio, then it's recommended to first install the libraries above before installing R. By installing the prerequisite libraries before R, you'll ensure that every R package has its needed libraries to operate at full capacity. Installing the libraries after packages have already been installed doesn't affect functionality but you may not achieve optimal performance.
The next step is to setup your Makevars file. Linux and R pull the proper compilers for everything but there are additional flags that are useful. For completeness, however, all gcc compilers are listed.
First, create/edit your Makevars file using the R code:
> file.edit("~/.R/Makevars")
Then, copy and paste the following into the file:
CC = gcc
CXX = g++
CXX11 = g++
CXX14 = g++
CXX17 = g++
CFLAGS += -O3 -fPIC -fopenmp
CXXFLAGS += -O3 -fPIC -fopenmp
CXX11FLAGS += -O3 -fPIC -fopenmp
CXX14FLAGS += -O3 -fPIC -fopenmp
CXX17FLAGS += -O3 -fPIC -fopenmp
Save and close the file, then restart R/RStudio.
If you follow through on enabling OpenBLAS below, then you can add the flags -llapack and -lopenblas after each -fopenmp in the code above. Be sure to save after adding these flags.
After installing these libraries, then installing {EGAnet} from source is a cinch:
> install.packages("EGAnet")
To use OpenBLAS (Open Basic Linear Algebra Subprograms), you need to tell your system to use it. With the libraries installed above, you've already installed OpenBLAS. To tell your system to use it, you can update your settings:
$ sudo update-alternatives --config liblapack.so.3-x86_64-linux-gnu
When running this code in your terminal, you'll see output that looks something like this:
There are 4 choices for the alternative liblapack.so.3-x86_64-linux-gnu (providing /usr/lib/x86_64-linux-gnu/liblapack.so.3).
Selection Path Priority Status
------------------------------------------------------------
0 /usr/lib/x86_64-linux-gnu/openblas-pthread/liblapack.so.3 100 auto mode
1 /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3 10 manual mode
2 /usr/lib/x86_64-linux-gnu/libopenblas.so.0 10 manual mode
* 3 /usr/lib/x86_64-linux-gnu/openblas-openmp/liblapack.so.3 95 manual mode
4 /usr/lib/x86_64-linux-gnu/openblas-pthread/liblapack.so.3 100 manual mode
Press <enter> to keep the current choice[*], or type selection number: 3
You'll want to select the option that reads /usr/lib/x86_64-linux-gnu/openblas-openmp/liblapack.so.3. For this demonstration, this selection was 3. Press ENTER after typing your selection.
You'll want to repeat this process for three other LAPACK and BLAS options:
$ sudo update-alternatives --config liblapack.so-x86_64-linux-gnu
$ sudo update-alternatives --config libblas.so.3-x86_64-linux-gnu
$ sudo update-alternatives --config libblas.so-x86_64-linux-gnu
For each one, you'll want to select the option that reads openblas-openmp.
Additional Resources
Performance and additional guidance on configuration: https://csantill.github.io/RPerformanceWBLAS/
Quick 'n' easy installation: https://prdm0.github.io/ropenblas/
Sometimes there are hiccups installing packages even though you have all the dependencies. Here are some common ones:
mv: cannot move '...' to '...':
Permission denied
ERROR: moving to final location failed
If you see this error, then you should try to install the first package you see associated with this error by itself. Sometimes R gets its hands full installing many packages and the locks on the packages don't allow packages to be stored in their final location.
If installing the package by itself doesn't work, then you can try an additional option that almost always works:
> install.packages("NAME_OF_PACKAGE", INSTALL_opts = "--no-lock")
Adding the INSTALL_opts = "--no-lock" option will avoid locking the package during installation, which is the source of the issue (most of the time, locking the package during installation is OK but sometimes not).