pkgr Configuration

Commands and Flags

All pkgr commands follow the format pkgr <command> <flags>

Commands and Subcommands

pkgr or pkgr --help

  • Prints a list of top level pkgr Commands

pkgr plan

  • Displays information about what pkgr would do if you were to run pkgr install

pkgr-plan

pkgr install

  • Installs packages according to the specifications set in the configuration file.

pkgr clean

  • Top level command for "cleaning" operations.

  • Subcommands:

    • pkgr clean cache
    • Removes the cache of downloaded packages (source/binary files) for the repos listed in the configuration file.
    • pkgr clean pkgdbs
    • Removes the saved package databases for repos listed in the configuration file
    • pkgr clean --all
    • Pass the --all flag to pkgr clean as a shortcut to run both pkgr clean cache and pkgr clean pkgdbs

pkgr inspect --deps

  • Prints detailed information about the installation plan pkgr would execute on a pkgr install -- provides insight into how pkgr determines dependencies. Must pass the --deps flag, or this becomes equivalent to pkgr install

pkgr add [package name]

  • Adds the given package to the config file. Does not check if package is available on any repos, and does not set any customizations.

pkgr remove [package name]

  • Removes the given package from the config file, if it is there.

Universal Flags (can be applied to any command)

  • --config [path]: Path to the pkgr.yml file, if not ./pkgr.yml.
  • --preview: Enable preview mode [[ unclear on what this does ]]
  • --library [path_to_directory]: Set location for packages to be installed.
  • --debug: Enable debug mode (developer only).
  • --loglevel [info/debug/trace]: Set the log level to "info", "debug", or "trace".
  • --update or --update=false: Set pkgr to update outdated packages it finds in the user's library.
  • --threads [number]: Set pkgr to use up to the specified number of threads.
  • --strict or --strict=false: Enable or disable strict mode (see notes)
  • --help: List information about a command.

pkgr.yml Configuration Options

Important Note: Any flags supplied to the command line will overwrite equivalent settings set in the configuration file.

The following item MUST be set at the top of your configuration file:

Version: 1

The following items can be set ONLY in the configuration file:

  • Packages to install (required)

    • Yaml syntax:
    Packages:
- <package_name1>
- <package_name2>
- dplyr

  • Repositories to use (required)

    • Repos must be named and a URL to the repository must be provided.
    • Unless otherwise configured, pkgr will use Repos in the order listed when searching for packages installation files for an individual package.
    • Yaml syntax:
    Repos:
- <repo_name>: "<repo_url>"
- CRAN_Micro: "https://cran.microsoft.com/snapshot/2018-11-18"

  • Customizations

    • Package-specific customizations
    • Repository to install a package from
    • Installation type for a package
    • Whether or not to install Suggested dependencies for the package.

    • Yaml syntax:

      Customizations:
Packages:
- data.table:
    Suggests: true
    Type: source
    Repo: CRAN_Micro
    • Repository-specific customizations
    • Installation type for packages pulled from a repo
    • Whether or not to install Suggested dependencies for packages pulled from a repo

    • Yaml syntax:

      Customizations:
Repos:
- <repo_name as listed in this config file>:
    Type: <source/binary>
- <repo_name as listed in this config file>:
    Suggests: <true/false>
- CRAN_Micro:
    Type: source
    Suggests: true

  • Libpaths

    • Extra locations (libPaths), in addition to the Library field, that pkgr will check when determining what packages are already installed.
    • Use of this feature is not recommended, as environments set up with pkgr ideally have all of their packages managed by pkgr, which will always install to a single directory.

    • Yaml syntax:

      Libpaths:
    • path/to/libpath1
    • path/to/libpath2 ...

    • path/to/libpathn

  • Rpath

    • Path to the R installation that pkgr should use. Useful for environments where R is not on the PATH, or where user needs their package to use non-default version of R.

    • Yaml syntax:

      Rpath: path/to/R
    • Note: should be a path to the R executable. E.g. Unix: /opt/R/3.6.1/bin/R, Windows: <path>/R.exe

  • Cache directory

    • Directory to use for storing cached files files
    • Folder must exist

    • Yaml syntax:

      Cache: <path_to_desired_folder>

  • Logging Output

    • Settings for logging output.

    • Yaml syntax:

      Logging:
all: <path_to_file>
install: <path_to_file>
overwrite: <true/false>
    • These configuration options are slated for rework, but for now, they behave as described below:

    • Setting: all: x.log

      • pkgr install logs to x.log when install=y.log is not set.
      • pkgr clean --all logs to x.log
      • pkgr inspect logs to x.log
      • pkgr clean cache and pkgr clean pkgdbs do NOT log to x.log
      • pkgr plan does NOT log to x.log

    • Setting: install: y.log

      • pkgr install logs to y.log (and only to y.log)

    • Setting: overwrite: true

      • Logs are overwritten every time a new pkgr command is run.
      • If false, logs are appended to every time a new pkgr command is run.

  • Lockfile settings

    • Lockfile to look for, specified by its type. Pkgr supports Packrat and Renv lockfiles.

    • Yaml syntax:

      Lockfile:
Type: [packrat/renv]

The following items are configurable statically in the yml file or dynamically via the command-line.

  • Note: Command-line flags will always overwrite the configuration in the yaml file.

  • Library (directory) to install packages to

    • Yaml syntax

      Library: <path_to_directory>

  • Update settings (should pkgr attempt to update outdated packages?)

    • Yaml syntax

      Update: <true/false>

  • Logging level

    • Yaml syntax

      Loglevel: <info/debug/trace>

  • Installation of “Suggested” packages config

    • Yaml syntax

      Suggests: <true/false>

  • Number of threads to use

    • Yaml syntax

      Threads: <number_of_threads>

  • Strict mode enabled/disabled

    • Yaml syntax

      Strict: <true/false>

Default Settings

Below are the default settings for non-required pkgr configurations.

  • Debug mode: disabled
  • Preview mode: disabled
  • Strict mode: disabled
  • Loglevel: “info”
  • Rpath: “R”
  • Threads: Number of threads available on system
  • Cache: User cache directories
  • Install suggested packages: false
  • Update outdated packages: false
  • Src/binary configurations: System defaults (bin for Mac/Windows, src for Linux)

Strict Mode

When strict mode is enabled, pkgr will refuse to run if unless the following conditions are satisfied:

  • The library defined in pkgr.yml must exist.

Rollback Feature

If any packages fail to install during a pkgr install command, pkgr will attempt to rollback the user's specified Library to its previous state, removing any installed packages and reverting any updated packages.