How to go from a clean M1 Mac to an RStudio IDE development machine. This will enable building and debugging RStudio Server and RStudio Desktop (both QtWebEngine and Electron flavors).

These steps can also be used on an Intel Mac; just leave out the parts annotated with (M1 Only).

If you're familiar with setting up an Intel Mac for RStudio development, here are the differences:

• Homebrew package manager (https://brew.sh/) must be installed twice; once for M1, once for Intel
• RStudio Server and Electron desktop can be built and executed entirely M1 native
• RStudio Desktop (Qt) can only be built for Intel (Qt limitation); UPDATE: as of Elsbeth Geranium (starting summer 2022) we are no longer building the Qt-based open-source desktop, only Electron, so it is no longer necessary to install Qt unless you need to build Qt-based Desktop IDE for Spotted-Wakerobin or older or need to build RStudio Desktop Pro, which is still Qt-based but will be converted to Electron in a future release.

• (M1 Only) Install Rosetta2 so Intel binaries will work. You will be prompted to do this when necessary, but I like to get it out of the way up front. From the terminal: /usr/sbin/softwareupdate --install-rosetta --agree-to-license
  • You might see a "Package Authoring Error" message when running this command. You can ignore this.
• Install R x86_64. For M1, this is fine because when running RStudio Desktop because both will be x86_64 and run with Rosetta2.
• Install the XCode command-line tools (C++ compiler and friends), from the terminal: xcode-select --install
• (Spotted Wakerobin or older only) Install Qt 5.12.10 via "Download the Qt Online Installer" near bottom of https://www.qt.io/download-open-source
  • As of this writing, the installer warns that you need to install XCode and the command-line tools. You already installed the command-line tools and can ignore this erroneous warning.
  • Use the default installation folder (~/Qt)
  • Select "Custom installation" (the default)
  • On "Select Components" screen, select Archive then click Filter button, otherwise you won't see version 5.12.10
  • Find Qt 5.12.10, expand it, and select the macOS and Qt WebEngine components

• Install using command shown at https://brew.sh; when it completes
  • (M1 Only) execute the two suggested commands at end of setup to ensure "brew" is on the path
• (M1 Only) Run the install command again, prefixed with arch -x86_64 to force it to install the Intel flavor
• (M1 Only) At this point confirm (in terminal) that which brew points to /opt/homebrew/bin/brew; this is the native M1 brew and is what you normally want to use
  • (M1 Only) If /usr/local/bin is first on the path you will need to adjust your path to put /opt/homebrew/bin first

• configure "git" the way you like it
• go to https://github.com/rstudio/rstudio and clone the repo (steps below assume you cloned to ~/rstudio but that's not required)

• cd ~/rstudio/dependencies/osx
• install-dependencies-osx
  • Note: if your terminal uses .zsh you may need to run this as ./install-dependencies-osx
• The initial run takes a long time and may prompt you for credentials along the way
• Good idea to re-run that script after each git pull (it doesn't take nearly as long on subsequent runs)

• This is normally how you want to work; only build RStudio Desktop if you are making desktop-specific changes (fairly rare)

• cd ~/rstudio/src
• mkdir build-server
• cd build-server
• Note: important that you name this folder build or build-*
• cmake ../cpp -DRSTUDIO_TARGET=Server -GNinja
• ninja
• ./rserver-dev and leave it running
• code changes to the rserver process (src/cpp/server) require you to stop it, recompile with ninja, and run it again
• changes to the rsession process (src/cpp/session) require you to stop existing session(s), recompile, and start a new session (no need to stop the rserver)

• In another terminal...
• cd ~/rstudio/src/gwt
• ./ant devmode
  • NOTE the above ./ant invokes a shell script named ant which tries to configure appropriate JDK then launches ant itself to do the build
  • If you encounter an error like node: No such file or directory, you may need to install node and/or ensure the path to your node installation is correct
    • install: brew install node@16 (you may also need to brew link node@16)
• Once the "GWT Development Mode" window appears, and the button "Launch Default Browser" is available, load http://localhost:8787 in web browser
• You can now sign-in and run RStudio Server (use the same credentials you use to login to the Mac)
• GWT code changes (src/gwt/...) will recompile on demand when you refresh the web browser
• TROUBLESHOOTING TIP: If builds are failing with errors like "class file has wrong version", trying doing ./ant clean the re-running the build command

• UPDATE: only applies to Spotted-Wakerobin (July 2022 release) or older; starting with Elsbeth Geranium we are only building the Electron version of Desktop so these steps no longer apply
• this can only be built for Intel; Qt itself is only available for Intel Mac
• the trick is to run the Intel version of cmake when generating the build (done below by using /usr/local/bin/cmake)
• mkdir ~/rstudio/src/build-desktop
• cd ~/rstudio/src/build-desktop
• /usr/local/bin/cmake ../cpp -DRSTUDIO_TARGET=Desktop -GNinja
• ninja

• cd ~/rstudio/src/gwt
• ./ant desktop
• Once the "GWT Development Mode" window appears...
• cd ~/rstudio/src/build-desktop
• ./rstudio-dev

The Electron desktop can be built entirely M1 native (unlike Qt desktop).

To build and execute RStudio Electron, you must have node.js installed and on the path. For this tutorial we'll install them directly via brew, but you might want to consider using the node version manager, as it will let you switch between different versions of node.

• brew install node@16 (you may also need to brew link node@16)

In developer mode, the Electron Desktop requires you have a native build of the C++ code. So, M1 on an M1 machine, Intel on an Intel machine. Thus a Qt desktop build as described above does not meet this requirement on an M1 machine.

The most direct way is:

• cd ~/rstudio/src
• mkdir build
• cd build
• cmake ../cpp -DRSTUDIO_TARGET=Electron -GNinja
• ninja

For GWT, either use ant desktop or the results of ant or ant draft.

• cd ~/rstudio/src/node/desktop
• npm ci
• npm start

• In VS Code, create a launch.json and add this target:

{
    "type": "node",
    "request": "launch",
    "name": "RStudio Electron",
    "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron-forge",
    // runtimeArgs will be passed directly to your Electron application
    "runtimeArgs": [
        "start"
    ],
    "cwd": "${workspaceFolder}"
}

A "package build" is what is produced by the official build. On Mac, by default, it creates a DMG containing the Intel version of desktop, and both the Intel and M1 versions of the rsession binary.

• cd ~/rstudio/package/osx
• ./make-package

To produce the Electron package:

• ./make-package --electron

For running Windows VMs on an M1 Mac, we recommend using the native ARM architecture for Windows. This has not officially been released yet, but Microsoft provides preview releases of Windows 11 on ARM64 here: https://www.microsoft.com/en-us/software-download/windowsinsiderpreviewARM64.

• Note: you may need to register an account for the Windows Insider Program in order to download the preview releases

You can use whatever VM software you prefer/are the most comfortable with, but if you have no preference, Parallels tends to be the easiest for new users to set up.

Once you have a Windows VM, you will need to go through all the steps detailed on Installing Rstudio Dependencies - Windows.

The x86/x64 emulation done by Windows is pretty good, but in some cases you may want to install ARM64-native tools where possible.

• Java JDK: https://github.com/microsoft/openjdk-aarch64/releases
  • Make sure to add Java to your system path when installing

When installing R, there are some important things to watch out for during the installation. It is recommended to run the installation as Administrator in order to ensure your registry is appropriately updated.

1. Change the install path. Typically, you should install R into C:\R\R-{version}
2. Uncheck the 32-bit installation, and check the 64-bit installation to make sure you are installing the x64 version of R.
   • Note: R versions 4.0.3 through 4.1.2 do not work with Windows ARM architecture.
   • R versions 3.6.3, 4.0.0, and 4.2.0 64-bit versions have been verified to run successfully on Windows ARM.
3. Make sure the checkbox for "Save version number in registry" is checked.
4. [Optional] In the start menu, search for Settings > View advanced system settings > Environment variables, and edit the Path variable to point to the folder containing the R.exe executable version you wish to use.

Note that you can install multiple versions of R, but the most recently installed one will be the one available on the registry that Qt Creator will use in different builds. If you want to flip between different versions of R, you will need to take the following steps:

• From the Start menu, open the Registry Editor. Look for the entries from R-Core. They will generally be under HKEY_LOCAL_MACHINE/SOFTWARE if you installed R as an Administrator, or under HKEY_CURRENT_USER/SOFTWARE if you installed as a user. For Windows ARM, they may be under SOFTWARE\WOW6432Node\R-core.
  • If you did not check the box for Save version number in registry, they may be missing -- you may need to re-install R or manually add them to the Registry.
  • For each version of R, there should be an entry under both R and R64. Each entry should contain a InstallPath, where the value is set to the path where the R executable was installed (e.g. C:\R\R-devel). In addition, the R and R64 keys should have values for Current Version (set to your desired R version) and InstallPath (the InstallPath for the desired CurrentVersion). If these registry entries are missing, you can manually add them, or try re-installing R. For example:

HKEY_LOCAL_MACHINE/
└── SOFTWARE/
    └── WOW6432Node/
        └── R-core/
            ├── R/ [Current Version: 4.2.0 Pre-release; InstallPath: C:\R\R-devel]
            │   ├── 4.2.0 Pre-release [InstallPath: C:\R\R-devel]
            │   ├── 3.6.3 [InstallPath: C:\R\R-3.6.3]
            │   └── 4.0.0 [InstallPath: C:\R\R-4.0.0]
            └── R64/ [Current Version: 4.2.0 Pre-release; InstallPath: C:\R\R-devel]
                ├── 4.2.0 Pre-release [InstallPath: C:\R\R-devel]
                ├── 3.6.3 [InstallPath: C:\R\R-3.6.3]
                └── 4.0.0 [InstallPath: C:\R\R-4.0.0]

• Open a Command Prompt as Administrator, and Navigate to the RStudio repo base folder
• Run the following command: <Path to R installation>\bin\x64\Rscript.exe src\cpp\tools\dll2lib.R.
• [Optional] In the start menu, search for Settings > View advanced system settings > Environment variables, and edit the Path variable to point to the folder containing the R executable version you wish to use.
• In Qt Creator, select Build > Clear CMake Configuration and then Build > Run CMake

• Open Qt Creator, select Projects, Open, navigate to CMakeLists.txt in the rstudio repo.
• Select the Projects tab, then Manage Kits. Make sure the MSVC 2017 kit is the default.
• Under the Projects tab, select Run to view the Run Settings. In the drop-down menu for Run configuration, select RStudio.
• Under the Projects tab, select Build to view the Build Settings. In the list of key-value pairs, you should be able to confirm that the LIBR variables point to the R x64 executable and directory of interest (i.e. LIBR_EXECUTABLE: C:/R/R-devel/bin/x64/R.exe, LIBR_HOME: C:/R/R-devel). The QT variables should point to the MSVC 2017 kit (i.e. QT_INSTALL_PATH: C:/Qt/5.12.10/msvc2017_64).
• If you run into issues, in the menu bar, select Build > Clear CMake Configuration and then Build > Run CMake
• Select the Hammer icon on the lower-left to kick off a build.
• In a command prompt, navigate to the rstudio/src/gwt directory and run ant desktop.
• Select the Run/Play icon to run the desktop application.

There is not currently a 4.x binary version of R for aarch64 available in the focal-cran40 package repository, so you may have to build R from source for your architecture.

If you are using a Linux ARM VM, you will not be able to use the Qt online installer to install Qt and the Qt web engine in order to run the RStudio Desktop. You can install qmake and dependencies with

sudo apt install -y qt5-qmake qtbase5 qtwebengine5 libqt5x11extras5 libqt5sensors5 libqt5svg5 libqt5xmlpatterns5

And then after creating and navigating to your build directory, running

cmake ../cpp -DQT_QMAKE_EXECUTABLE=/usr/lib/qt5/bin/qmake -DRSTUDIO_DESKTOP=TRUE

which will build both Desktop and Server. If qmake is installed to another location, adjust the DQT_QMAKE_EXECUTABLE argument accordingly.