├── .gitignore ├── faq.md ├── packages.md ├── readme.md ├── render_html.R ├── rtools40.md ├── style.inc └── ucrt.md /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | .Ruserdata 5 | *.html 6 | readme_files 7 | -------------------------------------------------------------------------------- /faq.md: -------------------------------------------------------------------------------- 1 | # R on Windows FAQ 2 | 3 | These are some common issues related to installing R packages on Windows with Rtools. This complements the official [R-FAQ](https://cran.r-project.org/doc/FAQ/R-FAQ.html) from CRAN. 4 | 5 | 6 | ## What is Rtools 7 | 8 | Rtools is the toolchain bundle that is used on Windows to build R base and R packages that contain compiled code. You can download it from [CRAN](https://cran.r-project.org/bin/windows/Rtools/). The latest builds of rtools4 contain 3 toolchains: 9 | 10 | - `C:\rtools40\mingw32`: the 32-bit gcc-8-3.0 toolchain used as of R 4.0.0 11 | - `C:\rtools40\mingw64`: the 64-bit gcc-8-3.0 toolchain used as of R 4.0.0 12 | - `C:\rtools40\ucrt64`: a new 64-bit gcc-10.3.0 toolchain targeting ucrt 13 | 14 | You only need Rtools if you want to compile R packages from source that contain C/C++/Fortran. By default, R for Windows installs the precompiled _binary packages_ from CRAN, for which you do not need rtools. 15 | 16 | ## How to install Rtools40: 17 | 18 | Please see instructions in: https://github.com/r-windows/docs 19 | 20 | 21 | ## Why does Rtools not put itself on the PATH automatically? 22 | 23 | Some versions of rtools in the past would automatically alter the global windows system PATH variable and add the rtools path. This was problematic for several reasons: 24 | 25 | The main problem is that other Windows programs may also attempt to do this (Strawberry Perl for example) and hence if those programs are installed after rtools, they may mask the rtools utilities from the PATH. But it would also hold vice-versa: prepending the windows system PATH with the rtools utilities could have undesired side-effects for other software relying on the path. 26 | 27 | For these reasons, the best way to set the PATH for R is in your `~/.Renviron` file. 28 | 29 | 30 | ## What is the difference between the msys, mingw32, and mingw64 shells? 31 | 32 | These are almost the same, the only difference is the default PATH. The mingw32/mingw64 shell automatically put the respective gcc version on the path, whereas the msys shell has no toolchain on the path. Other than that there is no difference. 33 | 34 | 35 | ## Does Rtools40 include git or svn? Why not? 36 | 37 | Rtools40 does not include git or svn clients. Most Windows users have [Git for Windows](https://git-scm.com/download/win) or [TortoiseSVN](https://tortoisesvn.net/) installed and configured, so we recommend to use these. 38 | 39 | 40 | ## Is Git-for-Windows compatible with rtools40? 41 | 42 | Yes. If you have [Git for Windows](https://git-scm.com/download/win) you will be able to use `git` commands from the rtools40 shell as well. Note that Git for Windows also includes it's own shell called "Git Bash" which looks very similar to Rtools Bash. That is because they use exactly the same system. 43 | 44 | Most git commands will work the same in Rtools as Git Bash, however for git commands that use vim for interactive editing things, it is safer to use Git Bash (because it includes a special vim that rtools doesn't have). 45 | 46 | 47 | ## How to extract a tarball with symlinks 48 | 49 | Windows does not support symlinks. Cygwin has several ways to emulate symlinks, but each has limitations. To extract a tarball which contains symlinks (such as the official R source releases) you can set this environment variable: 50 | 51 | ``` 52 | MSYS="winsymlinks:lnk" 53 | ``` 54 | 55 | This will create symlinks as Windows shortcuts with a special header and the R/O attribute set. 56 | 57 | 58 | ## How does R find compilers 59 | 60 | The most important thing is that the rtools40 `make` is on the path. It is not needed to put gcc on the path. 61 | 62 | ```r 63 | # Check your path 64 | Sys.getenv('PATH') 65 | 66 | # Confirm that make.exe is on the PATH 67 | Sys.which('make') 68 | ## "C:\\rtools40\\usr\\bin\\make.exe" 69 | ``` 70 | 71 | Once `make` is available, R will lookup make variables via `R CMD config` to find the path to gcc and other tools. To test this manually in R, let's lookup the path to the C++11 compiler: 72 | 73 | ```r 74 | tools::Rcmd(c('config', 'CXX11')) 75 | # C:/Rtools/mingw_64/bin/g++ 76 | ``` 77 | 78 | This system is the same on all operating systems (Windows, MacOS, Linux). 79 | 80 | 81 | ## How to test if the compiler is available in R? 82 | 83 | The script below looks up the compiler via `R CMD config` and then tests that it works. The same script can be used on any platform (not just windows). 84 | 85 | ```r 86 | r_cmd_config <- function(var){ 87 | tools::Rcmd(c("config", var), stdout = TRUE) 88 | } 89 | 90 | test_compiler <- function(){ 91 | testprog <- '#include \nint main() {std::cout << "Hello World!";}' 92 | make <- Sys.which('make') 93 | if(!nchar(make)) 94 | stop("Did not find 'make' on the PATH") 95 | CXX <- r_cmd_config("CXX") 96 | src <- tempfile(fileext = '.cpp') 97 | obj <- sub('cpp$', 'o', src) 98 | writeLines(testprog, con = src) 99 | out <- system2('make', c(obj, sprintf('CXX="%s"', CXX))) 100 | if(!file.exists(obj)) 101 | stop("Failed to compile example program: ", out) 102 | TRUE 103 | } 104 | ``` 105 | 106 | ## How to build base R on Windows 107 | 108 | See the [r-windows/r-base](https://github.com/r-windows/r-base) repository for scripts and documenation for building the R for Windows installer from source. 109 | 110 | 111 | ## Does rtools40 include a debugger 112 | 113 | Yes, both [GDB](https://www.gnu.org/software/gdb/) and [drmingw](https://github.com/jrfonseca/drmingw) via the package manager. To install the 64-bit version run this in the mingw64 shell: 114 | 115 | ```sh 116 | pacman -Sy mingw-w64-x86_64-gdb 117 | ``` 118 | 119 | To install 32-bit gdb use: 120 | 121 | ```sh 122 | pacman -Sy mingw-w64-i686-gdb 123 | ``` 124 | 125 | Same for `pacman -Sy mingw-w64-x86_64-drmingw` (which easier to use for simple debugging). 126 | 127 | See the [FAQ 8.4 *How do I debug code that I have compiled and dyn.load-ed?*](https://cran.r-project.org/bin/windows/base/rw-FAQ.html#How-do-I-debug-code-that-I-have-compiled-and-dyn_002eload_002ded_003f) to get started with debugging R packages. 128 | 129 | ## How to install rJava on Windows? 130 | 131 | The latest CRAN version of rJava will find the `jvm.dll` automatically, without manually setting the `PATH` or `JAVA_HOME`. However note that: 132 | 133 | - To use rJava in 32-bit R, you need [_Java for Windows x86_](https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html) ([direct download](https://github.com/portapps/untouched/releases/tag/oracle-jdk-8u251)) 134 | - To use rJava in 64-bit R, you need [_Java for Windows x64_](https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html) ([direct download](https://github.com/portapps/untouched/releases/tag/oracle-jdk-8u251)) 135 | - To build or check R packages with multi-arch (the default) you need to __install both__ _Java For Windows x64_ as well as _Java for Windows x86_. On Win 64, the former installs in `C:\Program files\Java\` and the latter in `C:\Program Files (x86)\Java\` so they do not conflict. 136 | 137 | As of Java version 9, support for x86 (win32) has been discontinued. Hence the latest working multi-arch setup is to install both [jdk-8u251-windows-i586.exe](https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html) and [jdk-8u251-windows-x64.exe](https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html) and then the binary package from CRAN: 138 | 139 | ```r 140 | install.packages("rJava") 141 | ``` 142 | 143 | The binary package from CRAN should pick up on the jvm by itself. __Experts only__: to build rJava from source, you need the `--merge-multiarch` flag: 144 | 145 | ```r 146 | install.packages('rJava', type = 'source', INSTALL_opts='--merge-multiarch') 147 | ``` 148 | 149 | 150 | 151 | -------------------------------------------------------------------------------- /packages.md: -------------------------------------------------------------------------------- 1 | # Package fixes 2 | 3 | Some CRAN packages have hardcoded configurations for winbuilder and need some extra help. Here we list how to install these using rtools40, until the problem is fixed in the package itself. 4 | 5 | ## XML 6 | 7 | You need the libxml2 system library: 8 | 9 | ```sh 10 | pacman -S mingw-w64-{i686,x86_64}-libxml2 11 | ``` 12 | 13 | The XML package wants to have an `LIB_XML` variable: 14 | 15 | ```r 16 | Sys.setenv(LIB_XML = "$(MINGW_PREFIX)") 17 | install.packages("XML", type= "source") 18 | ``` 19 | 20 | A backward compatible fix for the package author would be to set a default `LIB_XML ?= $(MINGW_PREFIX)` in Makevars.win 21 | 22 | 23 | ## RCurl 24 | 25 | You need the curl system library: 26 | 27 | ```sh 28 | pacman -S mingw-w64-{i686,x86_64}-curl 29 | ``` 30 | 31 | Now you can install RCurl: 32 | 33 | ```r 34 | install.packages("RCurl", type= "source") 35 | ``` 36 | 37 | This spits out a lot of warnings that you can ignore (The package author should set `-DSTRICT_R_HEADERS` in Makevars.win). 38 | 39 | 40 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # Using Rtools4 on Windows 2 | 3 | Starting with R 4.0.0 (released April 2020), R for Windows uses a toolchain bundle called **rtools4**. This version of Rtools is based on [msys2](https://www.msys2.org/), which makes easier to build and maintain R itself as well as the system libraries needed by R packages on Windows. The latest builds of rtools4 contain 3 toolchains: 4 | 5 | - `C:\rtools40\mingw32`: the 32-bit gcc-8-3.0 toolchain for R 4.0 - 4.1 6 | - `C:\rtools40\mingw64`: the 64-bit gcc-8-3.0 toolchain for R 4.0 - 4.1 7 | - `C:\rtools40\ucrt64`: a 64-bit gcc-10.3.0 ucrt toolchain for R 4.2 [^1] 8 | 9 | The [msys2 documentation](https://www.msys2.org/docs/environments/#msvcrt-vs-ucrt) gives an overview of the supported environments in msys2 and a comparison of MSVCRT and UCRT. The main difference between upstream msys2 and rtools4 is that our toolchains and libraries are configured for static linking, whereas upstream msys2 prefers dynamic linking. The references at the bottom of this document contain more information. 10 | 11 | The current version of Rtools is maintained by Jeroen Ooms. [Older editions](https://cran.r-project.org/bin/windows/Rtools/history.html) were put together by Prof. Brian Ripley and Duncan Murdoch. The best place for reporting bugs is via the [r-windows](https://github.com/r-windows) organization on GitHub. 12 | 13 | ## Installing Rtools 14 | 15 | Note that Rtools is only needed build R packages with C/C++/Fortran code from source. By default, R for Windows installs the precompiled "binary packages" from CRAN, for which you do not need Rtools. 16 | 17 | To use rtools, download the installer from CRAN: 18 | 19 | - On Windows 64-bit: [rtools40-x86_64.exe](https://cran.r-project.org/bin/windows/Rtools/rtools40-x86_64.exe) (includes both i386 and x64 compilers). Permanent url: [rtools40-x86_64.exe](https://github.com/r-windows/rtools-installer/releases/download/2022-02-06/rtools40-x86_64.exe). 20 | - On Windows 32-bit: [rtools40-i686.exe](https://cran.r-project.org/bin/windows/Rtools/rtools40-i686.exe) (i386 compilers only). Permanent url: [rtools40-i686.exe](https://github.com/r-windows/rtools-installer/releases/download/2020-05-05/rtools40-i686.exe). 21 | 22 | __Note for RStudio users:__ you need at least RStudio version `1.2.5042` to work with rtools4. 23 | 24 | 25 | ![](https://user-images.githubusercontent.com/216319/79896057-25fa8000-8408-11ea-9069-d01bfbd67786.png) 26 | 27 | 28 | ## Putting Rtools on the PATH 29 | 30 | After installation is complete, you need to perform __one more step__ to be able to compile R packages: we put the location of the Rtools _make utilities_ (`bash`, `make`, etc) on the `PATH`. The easiest way to do so is by creating a text file `.Renviron` in your Documents folder which contains the following line: 31 | 32 | ``` 33 | PATH="${RTOOLS40_HOME}\usr\bin;${PATH}" 34 | ``` 35 | 36 | You can do this with a text editor, or from R like so (note that in R code you need to escape backslashes): 37 | 38 | ```r 39 | write('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', file = "~/.Renviron", append = TRUE) 40 | ``` 41 | 42 | Restart R, and verify that `make` can be found, which should show the path to your Rtools installation. 43 | 44 | ```r 45 | Sys.which("make") 46 | ## "C:\\rtools40\\usr\\bin\\make.exe" 47 | ``` 48 | 49 | Now try to install an R package from source: 50 | 51 | ```r 52 | install.packages("jsonlite", type = "source") 53 | ``` 54 | 55 | If this succeeds, you're good to go! See the links below to learn more about rtools4 and the Windows build infrastructure. 56 | 57 | 58 | ## Further Documentation 59 | 60 | More documentation about using rtools4 for R users and package authors: 61 | 62 | - [Using pacman](https://github.com/r-windows/docs/blob/master/rtools40.md#readme): the new rtools package manager to build and install C/C++ system libraries. 63 | - [Installing R packages](https://github.com/r-windows/docs/blob/master/packages.md#readme): Some older R packages that need extra help to compile. 64 | - [Testing packages with ucrt64](https://github.com/r-windows/docs/blob/master/ucrt.md#readme): Instructions for building and testing using the experimental UCRT toolchains. 65 | - [FAQ](https://github.com/r-windows/docs/blob/master/faq.md#readme): Common questions about Rtools40 and R on Windows. 66 | 67 | Advanced information about building R base and building system libraries: 68 | 69 | - [r-base](https://github.com/r-windows/r-base#readme): Scripts for building R for Windows using rtools4. 70 | - [rtools-packages](https://github.com/r-windows/rtools-packages#readme): Toolchains and static libraries for rtools4 (GCC 8+) 71 | - [rtools-backports](https://github.com/r-windows/rtools-backports#readme): Backported C/C++ libraries for the gcc-4.9.3 legacy toolchain (for R 3.3 - 3.6) 72 | - [rtools-installer](https://github.com/r-windows/rtools-installer#readme): Builds the rtools4 installer bundle. 73 | 74 | [^1]: the ucrt64 toolchain in rtools4 uses the same version of mingw-w64, gcc, and additional patches as the cross-compiled MXE bundle from Tomas Kalibera (tentatively known as [rtools42](https://developer.r-project.org/WindowsBuilds/winutf8/ucrt3/howto.html)) and they are fully compatible. 75 | -------------------------------------------------------------------------------- /render_html.R: -------------------------------------------------------------------------------- 1 | # Todo: can we just get a nice simple light theme? 2 | library(rmarkdown) 3 | render("readme.md", html_document(self_contained = FALSE, mathjax = NULL, highlight = 'pygments')) 4 | txt <- readLines('readme.html') 5 | txt <- sub('.*', 'Using Rtools40 on Windows', txt) 6 | txt <- sub('readme_files/bootstrap-([.0-9]+)/css/bootstrap.min.css', 'https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/\\1//css/bootstrap.min.css', txt) 7 | txt <- sub('https://cran.r-project.org/bin/windows/Rtools/', '', txt, fixed = TRUE) 8 | txt <- sub('.*