Skip to contents

Installation and troubleshooting

Source: vignettes/installation-and-troubleshooting.Rmd
installation-and-troubleshooting.Rmd

Requirements

polyglotSQL has a compiled Rust backend. To install from source you need:

  • R >= 4.2
  • Rust: cargo and rustc >= 1.88
  • the xz utility (to unpack the vendored dependencies; present on virtually every system)

No Rust is needed when installing a prebuilt binary (e.g. from CI artifacts or a binary repository).

Installing Rust

The recommended path on every platform is rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Alternatives: brew install rust (macOS), apt-get install cargo rustc (Debian/Ubuntu — check the version!), the official Windows installer from https://forge.rust-lang.org/infra/other-installation-methods.html. On Windows, the gnu toolchain targeting x86_64-pc-windows-gnu is required for R; rustup installs it with:

rustup target add x86_64-pc-windows-gnu

The package’s configure script checks the toolchain up front and prints exactly what is missing (it never installs anything itself).

Installing the package 

# install.packages("remotes")
remotes::install_github("StrategicProjects/polyglot-sql-r")

Offline / air-gapped builds

The source package ships all Rust dependencies as a vendored archive (src/rust/vendor.tar.xz), and the build runs cargo with --offline. Nothing is downloaded during R CMD INSTALL — an internet connection is only needed to obtain the package itself.

Build details you may care about

  • Compilation uses at most 2 parallel jobs (CRAN policy).
  • The Rust static library is linked into a single shared object; the installed package has no runtime dependency on cargo.
  • DEBUG=true R CMD INSTALL . produces a debug build (faster compile, slower runtime).

Troubleshooting

cargo: command not found / configure fails

Rust is not on the PATH R uses. After installing via rustup, restart R so ~/.cargo/bin (added to your shell profile) is visible, or add it manually:

Sys.setenv(PATH = paste0(Sys.getenv("PATH"), ":", path.expand("~/.cargo/bin")))

rustc >= 1.88 required

Distribution packages are often too old. Install via rustup, or update with rustup update stable.

Linker errors on macOS

Install the Xcode command-line tools: xcode-select --install.

Windows: cannot find -lpolyglotsql or wrong target

Make sure the x86_64-pc-windows-gnu target is installed (see above) and that you are using Rtools matching your R version.

Updating the embedded engine (for developers)

The upstream crate version is pinned in src/rust/Cargo.toml and Cargo.lock, and its sources are vendored. To upgrade:

tools/update-vendor.sh 0.6.3   # bumps polyglot-sql, re-vendors, re-packs

then update Config/polyglotSQL/upstream in DESCRIPTION, run the test suite, and check polyglot_version() reports the new version.

Verifying an installation 

library(polyglotSQL)
polyglot_version()
sql_transpile("SELECT IFNULL(a, b) FROM t", from = "mysql", to = "postgres")