help-macos.in

// -*- mode: rust -*-

// ------------------------------------------------------------------------
// macOS help
// ------------------------------------------------------------------------

const HELP_ABOUT: &str = r#"
  On macOS, R versions installed by rig do not interfere. You can run
  multiple versions at the same time. rig also makes sure that packages
  are installed into a user package library, so reinstalling R will not
  wipe out your installed packages."#;

const HELP_EXAMPLES: &str = "\x1b[4m\x1b[1mExamples:\x1b[22m\x1b[24m
  # Add the latest development snapshot
  rig add devel

  # Add the latest release
  rig add release

  # Install specific version
  rig add 4.1.2

  # Install latest version within a minor branch
  rig add 4.1

  # List installed versions
  rig list

  # Set default version
  rig default 4.0";

const HELP_RESOLVE: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Resolve R versions. Checks the version number of an R version (e.g.
  release, devel, etc.), and looks up the URL of the installer for it,
  if an installer is available.

  It prints the R version number, and after a space the URL of the
  installer. If no installer is available for this R version and the
  current platform, the URL is `NA`.

  An R version can be specified in various ways:
  - `rig resolve devel` is the latest available development version,
  - `rig resolve next` is the next (patched, alpha, beta, etc.) version,
  - `rig resolve release` is the latest release.
  - `rig resolve x.y.z` is a specific version.
  - `rig resolve x.y` is the latest release within the `x.y` minor branch.
  - `rig resolve oldrel/n` is the latest release within the `n`th previous
    minor branch (`oldrel` is the same as `oldrel/1`).";

const HELP_RESOLVE_EXAMPLES: &str = "\x1b[4m\x1b[1mExamples:\x1b[22m\x1b[24m
  # Latest development snapshot
  rig resolve devel

  # Latest release (that has an installer available)
  rig resolve release

  # URL for a specific version
  rig resolve 4.1.2

  # Latest version within a minor branch
  rig resolve 4.1";

const HELP_ARCH: &str = "Select macOS arch: arm64 or x86_64";

const HELP_DEFAULT: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Print or set the default R version. The default R version is the one that
  is started with the `R` command, usually via the `/usr/local/bin/R`
  symbolic link.

  Call without any arguments to see the current default. Call with the
  version number/name to set the default. Before setting a default, you
  can call `rig list` to see the installed R versions.

  The default R version is set by updating the symbolic link at
  `/Library/Frameworks/R.framework/Versions/Current` and pointing it to the
  specified R version.

  This command can change the default version without `sudo` as long as
  the user is in the `admin` group. Otherwise you need to run it as
  `sudo rig default ...`.

  You don't need to update the default R version to just run a non-default R
  version. You can use the `R-<ver>` links, see `rig system make-links`.

  `rig switch` is an alias of `rig default`.";

const HELP_DEFAULT_EXAMPLES: &str = "\x1b[4m\x1b[1mExamples:\x1b[22m\x1b[24m
  # Query default R version
  rig default

  # Set the default version
  rig default 4.1";

const HELP_LIST: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  List installed R versions from `/Library/Framework/R.framework/Versions`.
  It does _not_ check if they are working properly.

  `rig ls` is an alias.";

const HELP_ADD: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Download and install an R version, from the official sources.
  It keeps the already installed R versions, except versions within the
  same minor branch, see below.

  The desired R version can be specified in various ways:
  - `rig add devel` adds the latest available development version,
  - `rig add next` is the next version (patched, alpha, beta, rc, etc.),
  - `rig add release` adds the latest release.
  - `rig add x.y.z` adds a specific version.
  - `rig add x.y` adds the latest release within the `x.y` minor branch.
  - `rig add oldrel/n` adds the latest release within the `n`th previous
    minor branch (`oldrel` is the same as `oldrel/1`).
  - `rig add <url>` uses a `.pkg` installer from `<url>`.
  - `rig add renv.lock` or `rig add <dir>` installs the R version specified
    in the renv.lock file. If a directory is given, rig looks for an
    renv.lock file in that directory.

  Usually you need to run this command with `sudo`: `sudo rig add ...`,
  otherwise rig will need to ask for your password.

  On macOS rig cannot add multiple R versions from the same minor branch.
  E.g. it is not possible to have R 4.1.1 and R 4.1.2 installed at the
 same time. Adding one of them will automatically remove the other.

  `rig add` will automatically call `rig system forget` before the
  installation, to make sure that already installed R versions are kept.
  It will also call the following rig command after the installation:
  - `rig system forget`
  - `rig system fix-permissions`
  - `rig system make-orthogonal`
  - `rig system create-lib`
  - `rig system make-links`
  See their help pages for details.";

const HELP_ADD_EXAMPLES: &str = "\x1b[4m\x1b[1mExamples:\x1b[22m\x1b[24m
  # Add the latest development snapshot
  rig add devel

  # Add the latest release
  rig add release

  # Install specific version
  rig add 4.1.2

  # Install latest version within a minor branch
  rig add 4.1

  # Install arm64 build of R (default on arm64 macs)
  rig add -a arm64 release

  # Install x86_64 build of R (default on x86_64 macs)
  rig add -a x86_64 release

  # Install the R version specified in renv.lock
  rig add renv.lock

  # Install R version from a project's renv.lock
  rig add path/to/project";

const HELP_RM: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Remove an R installation. It keeps the users' package libraries.
  It automatically calls `rig system forget` before removing the files.

  Usually you need to run this command with `sudo`: `sudo rig rm ...`,
  otherwise rig will ask for your password.";

const HELP_SYSTEM: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Various commands to modify and configure the installed R versions.
  See their help pages for details. E.g. run `rig system make-links --help`.";

const HELP_SYSTEM_ORTHO: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Make the current R installations orthogonal. This allows running multiple
  R versions at the same time, as long as they are started with their
  quick links (see `rig system make-links --help`). For example you
  can run a script using R 4.1.x in one terminal:

  R-4.1 -q -f script1.R

  while running another script using R 4.0.x in another terminal:

  R-4.0 -q -f script2.R

  `rig add` runs `rig system make-orthogonal`, so if you only use rig to
  install R, then you do not need to run it manually.

  This command probably needs `sudo`: `sudo rig system make-orthogonal`,
  otherwise rig will aks for your password.";

const HELP_SYSTEM_LINKS: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Create quick links in `/usr/local/bin` for the current R installations.
  These let you directly run a specific R version. E.g. `R-4.1` will start
  R 4.1.x.

  `rig add` runs `rig system make-links`, so if you only use rig to
  install R, then you do not need to run it manually.

  This command probably needs `sudo`: `sudo rig system make-links`,
  otherwise rig will ask for your password.";

const HELP_SYSTEM_ADDPAK: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Install/update pak for one or more R versions.

  * If `--all` is specified, then it installs pak for all current R
    installations.
  * If one or more R versions are specified, then it installs pak for
    those.
  * If no R versions are specified, then it installs pak for the default
    R installation (see `rig default`).";

const HELP_SYSTEM_FIXPERMS: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Update the permissions of the current R versions, so only the
  administrator can install R packages into the system library.
  Together with `rig system create-lib` this facilitates keeping
  additional packages in a user library, instead of the system library.

  `rig add` runs `rig system fix-permissions`, so if you only use rig to
  install R, then you do not need to run it manually.

  This command probably needs `sudo`: `sudo rig system fix-permissions`,
  otherwise rig will ask for your password.";

const HELP_SYSTEM_FORGET: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Tell macOS to forget about the currently installed R versions.
  This is needed to have multiple R installations at the same time.

  `rig add` runs `rig system forget` before and after the installation,
  so if you only use rig to install R, then you don't need to run this
  command manually.

  This command probably needs `sudo`: `sudo rig system forget`, otherwise
  rig will ask for your password.";

const HELP_SYSTEM_NO_OPENMP: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Remove -fopenmp flags from the R configuration, to make R work with
  the Apple compilers, instead of CRAN's custom compilers. This is only
  needed for R 3.6.x and before.

  `rig add` runs `rig system no-openmp` after the installation, so if
  only use rig to install R, then you don't need to run this command
  manually.

  This command probably needs `sudo`: `sudo rig system no-openmp`,
  otherwise rig will ask for your password.";

const HELP_SYSTEM_ALLOW_DEBUGGER: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Update the entitlements of the R process to allow debuggers. It adds
  the `get-task-allow` entitlement to the R binary. This is only needed
  for R installers 3.6 and later, previous versions are not signed.
  Call `R -d lldb` to start `lldb` on `R`. (Or `R-x.y -d lldb` if you
  want a non-default version.)

  See also `rig system allow-debugger-rstudio`, which does the same for
  R running in RStudio.

  This command is experimental. Please let us know at
  https://github.com/r-lib/rig/issues if it does not work as
  expected.

  This command probably needs `sudo`: `sudo rig system allow-debugger`,
  otherwise rig will ask for your password.";

const HELP_SYSTEM_ALLOW_DEBUGGER_RSTUDIO: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Update the entitlements of RStudio R process to allow debuggers. It adds
  the `get-task-allow` entitlement to the `rsession` (and `rsession-arm64`
  on arm64 hardware) binary.

  See also `rig system allow-debugger`, which does the same for
  R running outside of RStudio.

  This command is experimental. Please let us know at
  https://github.com/r-lib/rig/issues if it does not work as
  expected.

  This command probably needs `sudo`: `sudo rig system allow-debugger`,
  otherwise rig will ask for your password.";

const HELP_SYSTEM_ALLOW_CORE_DUMPS: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Update the entitlements of the R process to allow core dumps. This
  command is similar to `rig system allow-debugger` but it also makes
  sure that the `/cores` directory of core dumps is writeable by the
  current user. Don't forget to call `ulimit -c unlimited` from the
  same shell before starting R.

  This command is experimental. Please let us know at
  https://github.com/r-lib/rig/issues if it does not work as
  expected.

  This command probably needs `sudo`: `sudo rig system allow-core-dumps`,
  otherwise rig will ask for your password.";

const HELP_RSTUDIO: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Start RStudio with the specified R version.

  If `project-file` is an RStudio `.Rproj` file, or a directory containing
  an RStudio project file, RStudio will open the project.

  If `project-file` is a directory that does not contain an RStudio
  project file, then RStudio will start up without an active project,
  but will set the working directory to the specified directory.

  If `project-file` is a regular file that is not inside a directory
  containing an RStudio project, then RStudio will start up without an
  active project, but it will open the specified file, and will set the
  working directory to the directory of the file.

  If the RStudio project or the specified directory contains an `renv.lock`
  file (created by the renv package), and `version` is not specified, then
  rig will read the preferred R version from the `renv.lock` file.
  If the same exact version is not installed, then rig chooses
  the latest version with the same major and minor components. If no such
  version is available, rig throws an error.

  On macOS arm64 computers rig prefers arm64 R, unless an exact version
  match is only available with x86_64 R.

\x1b[4m\x1b[1mExamples:\x1b[22m\x1b[24m
  # With default R version
  rig rstudio

  # With another R version
  rig rstudio 4.0

  # Open project with default R version
  rig rstudio cli.Rproj

  # Open renv project with the R version specified in the lock file
  rig rstudio projects/myproject/renv.lock

  # Open RStudio project with specified R version, either is good
  rig rstudio 4.0 cli.Rproj
  rig rstudio cli.Rproj 4.0";

const HELP_SYSREQS: &str = "
\x1b[4m\x1b[1mDescription:\x1b[22m\x1b[24m
  Manage system libraries and tools. This currently includes a very
  restricted set of tools, that are needed for running `R CMD check`.
  Run `rig sysreqs list` for a complete list.";