.libpaths2

Description

A version of .libPaths which allows for excluding the site library

Usage

.libPaths2(fulllp, exclude.site = TRUE)

Arguments

Details

Behaves exactly as the .libPaths function does, with the exception of optionally excluding the site library

Value

a vector of library paths currently in use, optionally excluding the site library.

BiocDevel

Description

An object representing the current Bioc devel version. Can be passed to switchTo.

Usage

BiocDevel

Format

An object of class RepoSubset of length 1.

BiocRelease

Description

An object representing the current Bioc release. Can be passed to switchTo.

Usage

BiocRelease

Format

An object of class RepoSubset of length 1.

DEPCRECATED - Create a manifest of Bioc SVN locations

Description

DEPCRECATED - Create a manifest of Bioc SVN locations

Usage

BiocSVNManifest(bioc_vers = "devel", software_only = TRUE)

Arguments

Details

In combination with the lazyRepo function, this manifest can be used to work from a local, working checkout of a set of inter-dependent Bioconductor packages.

Value

A PkgManifest which contains SVN locations for all packages found in the specified bioc repositories, as well as those listed in not_in_repo

See Also

lazyRepo

BiocVers

Description

A constructor for creating a RepoSubset object for a specified release of Bioconductor, which includes only the BiocInstaller package.

Usage

BiocVers(
  version = getBiocReleaseVr(),
  name = paste("BioC", version, sep = "_"),
  repos = biocReposForVers(version)
)

Arguments

Value

A RepoSubset object for the specified release of Bioconductor, which contains only the BiocInstaller or BiocManager package, as appropriate for that version.

GithubManifest

Description

Create a package manifest containing only github packages

Usage

GithubManifest(..., pkgrepos)

Arguments

Details

Any names of the pkgrepos vector are assumed to be pkg names for the manifest. For unnamed elements, the pkg name is assumed to be the repository name.

Value

A GithubManifest object representing the specified github repos.

Note

This is a convenience wrapper for makeManifest. It uses the username/repo[/subdir][@ref] shorthand for specifying package locations in github repositories introduced by Wickham's devtools. Unlike devtools, username is not optional, and only branch names are currently supported in the @ref

Examples

ghman = GithubManifest("gmbecker/switchr", "hadley/devtools")
ghman

ManifestRow

Description

Create one or more rows of a manifest data.frame

Usage

ManifestRow(
  name,
  url = NA_character_,
  type = NA_character_,
  branch = NA_character_,
  subdir = ".",
  extra = NA_character_
)

Arguments

Details

If name is missing, an empty (0 row) manifest data.frame is returned. All other fields default to values indicating no information- NA_character in most cases, and "." for subdir

Value

A valid Package manifest data.frame

PkgManifest

Description

Construct a PkgManifest, which can be installed from using install_packages

Usage

PkgManifest(
  manifest = ManifestRow(...),
  dep_repos = defaultRepos(),
  ...,
  dl_method
)

Arguments

Details

If a package is found in both the manifest dataf.frame and the dependency repositories, the version in the manifest will always take precidence within the switchr framework.

Value

a PkgManifest object.

PkgSource

Description

An object representing the source location of a package. This is a virtual used exlusively through its subclasses, which are used to differentiate the different types of package source locations.

RepoSubset

Description

An object that represents a subset of packages available in a repo. When switched to, switchr will default to only installing the specified packages, rather than all packages in the repository.

Usage

RepoSubset(repos, pkgs, default_name)

Arguments

Value

a RepoSubset object.

SessionManifest

Description

A manifest which includes both a PkgManifest containing package source information, and a data.frame defining a filter with exact versions of some or all packages

Usage

SessionManifest(manifest, versions = character())

Arguments

Value

A SessionManifest object

SwitchrCtx

Description

A constructor for class SwitchrCtx, represenging a switchr installed-package library.

Usage

SwitchrCtx(name, libpaths, exclude.site = TRUE, seed = NULL)

Arguments

Value

a SwitchrCtx object.

References

Becker G, Barr C, Gentleman R, Lawrence M; Enhancing Reproducibility and Collaboration via Management of R Package Cohorts. Journal of Statistical Software, 81(1). 2017. doi: 10.18637/jss.v082.i01

SwitchrParam

Description

A contstructor for a SwitchrParam object representing a number of common parameters understood by the switchr framework

Usage

SwitchrParam(
  logfun = function(...) NULL,
  shell_init = character(),
  archive_timing = 2,
  archive_retries = 2,
  dl_method,
  shell_timing = 1
)

Arguments

Value

A SwitchrParam object.

Author(s)

Gabriel Becker

addPkg

Description

Add a package to an object associated with a manifest

Usage

addPkg(
  x,
  ...,
  rows = makeManifest(...),
  versions = data.frame(name = manifest_df(rows)$name, version = NA_character_,
    stringsAsFactors = FALSE),
  replace = FALSE
)

## S4 method for signature 'PkgManifest'
addPkg(
  x,
  ...,
  rows = makeManifest(...),
  versions = data.frame(name = manifest_df(rows)$name, version = NA_character_,
    stringsAsFactors = FALSE),
  replace = FALSE
)

## S4 method for signature 'SessionManifest'
addPkg(
  x,
  ...,
  rows = makeManifest(...),
  versions = data.frame(name = manifest_df(rows)$name, version = NA_character_,
    stringsAsFactors = FALSE),
  replace = FALSE
)

Arguments

Value

x, with the relevant package(s) added to it (in the case of a manifest) or its associated manifest.

archive_retries

Description

Get or set the number of times to retry downloading a file from the CRAN archive

This is intended to stop intermittent install failures due to failing to retrieve files that *are* in the archive but are not downloading properly when a larger number of packages is being retrieved.

Usage

archive_retries(x)

## S4 method for signature 'SwitchrParam'
archive_retries(x)

archive_retries(x) <- value

## S4 replacement method for signature 'SwitchrParam'
archive_retries(x) <- value

Arguments

Value

When getting, the number of seconds to wait, when setting, a new, updated SwitchrParam object.

archive_timing

Description

Get or set the number of seconds to wait after trying to retrieve a file from the CRAN Archive.

This is intended to stop intermittent install failures due to failing to retrieve files that *are* in the archive but are not downloading properly when a larger number of packages is being retrieved.

Usage

archive_timing(x)

## S4 method for signature 'SwitchrParam'
archive_timing(x)

archive_timing(x) <- value

## S4 replacement method for signature 'SwitchrParam'
archive_timing(x) <- value

Arguments

Value

When getting, the number of seconds to wait, when setting, a new, updated SwitchrParam object.

biocReposForVers

Description

Generate the URLs of the repositories associated with a specific Bioconductor release

Usage

biocReposForVers(version)

Arguments

Value

the repositories associated with the specified Bioconductor version.

Note

This function will only work if some version of Bioconductor (>2.9) was installed when switchr was installed. It will return NULL otherwise.

branch

Description

Get or set the branch associated with a Package Source

Usage

branch(x)

## S4 method for signature 'PkgSource'
branch(x)

branch(x) <- value

## S4 replacement method for signature 'PkgSource'
branch(x) <- value

Arguments

Value

for the getter, the branch associated with the source object, for the setter, the object updated to use the specified branch.

cmethods

Description

Combine 2 or more manifests of the same type (PkgManifest or SessionManifest)

Usage

## S4 method for signature 'SessionManifest'
c(x, ..., recursive = FALSE)

## S4 method for signature 'PkgManifest'
c(x, ..., recursive = FALSE)

Arguments

Value

An object of the same class as x containing the combined contents of x and all elements of ....

Check if a directory contains package sources

Description

Check if a directory contains package sources

Usage

checkIsPkgDir(dir)

Arguments

Details

Any directory containing a DESCRIPTION file as a direct child is considered a package source directory, while any that do not are not.

Value

Logical scalar indicating if the directory contains the source code for a package.

cranPkgVersManifest

Description

Create a Pkg manifest which points to tarballs representing a particular version of a CRAN package and versions of its (recursive) dependencies that were contemporary on the first or last day the specified package version resided on CRAN

Usage

cranPkgVersManifest(
  pkg,
  vers,
  earliest = TRUE,
  cur_avail = available.packages(),
  verbose = FALSE,
  suggests = c("direct", "none"),
  delay = 1,
  erronfail = TRUE
)

Arguments

Value

A SessionManifest object

Note

Some packages retain the same version on CRAN for long periods of time. The cohort in the manifest represents a gross proxy for the cohort used in conjunction within an analysis which used a the vers version of the specified package. In general it will *not* perfectly recreate the set of package versions originally used.

Author(s)

Gabriel Becker

References

"Gabor Csardi" (2014). crandb: Query the unofficial CRAN metadata database. R package version 1.0.0. https://github.com/metacran/crandb

Becker G, Barr C, Gentleman R, Lawrence M; Enhancing Reproducibility and Collaboration via Management of R Package Cohorts. Journal of Statistical Software, 81(1). 2017. doi: 10.18637/jss.v082.i01

Examples

## Not run: 
man = cranPkgVersManifest("devtools", "1.6")

## End(Not run)

currentCompEnv

Description

Display the computing environment currently in use. If switchTo has not been called, a new SwitchrCtx object describing the current environment is created.

Usage

currentCompEnv()

Value

A SwitchrCtx object representing the current computing environment.

defaultRepos

Description

Get default repositories for use as dependency repos and within install_packages

Usage

defaultRepos()

Value

A character vector of package repository urls

dep_repos

Description

Get or set repositories to be used to fullfill dependencies beyond packages within the manifest

Usage

dep_repos(x)

## S4 method for signature 'PkgManifest'
dep_repos(x)

## S4 method for signature 'SessionManifest'
dep_repos(x)

dep_repos(x) <- value

## S4 replacement method for signature 'PkgManifest'
dep_repos(x) <- value

## S4 replacement method for signature 'SessionManifest'
dep_repos(x) <- value

Arguments

Value

Character vector with existing repository urls

dl_method

Description

Get or set the download method for retreiving files.

Usage

dl_method(x)

## S4 method for signature 'SwitchrParam'
dl_method(x)

dl_method(x) <- value

## S4 replacement method for signature 'SwitchrParam'
dl_method(x) <- value

Arguments

Value

for the getter, the download method specified in the SwitchrParam object, for the setter, the object updated with the new download method.

Identify error states from R or external programs

Description

Identify error states from R or external programs

Usage

errorOrNonZero(out)

Arguments

Value

TRUE if out is an error object, or has an attribute called "status" which is > 0

Get path from file URL

Description

Get path from file URL

Usage

fileFromFileURL(fileurl)

Arguments

Value

The system directory path that fileurl points to

Find newest packages in a package info data.frame

Description

Find newest packages in a package info data.frame

Usage

findNewestPkgInds(df, pkgcol = "package", verscol = "version")

findNewestPkgRows(
  df,
  pkgcol = "package",
  verscol = "version",
  newcol = "new",
  verbose = FALSE,
  logfun = message
)

Arguments

Value

a data.frame with the same columns as df which contains only the most recent row for each unique package name, as determined by the contents of df[[verscol]]

for findNewestPkgInds, the indices of the rows representing the newest version of each package within df. For findNewestPkgRows, the rows themselves from df representing the newest version of each package.

Find a package directory within an SCM checkout

Description

Find a package directory within an SCM checkout

Usage

findPkgDir(rootdir, branch, subdir, param)

Arguments

Value

A path to the Package sources

findPkgVersionInRepo

Description

findPkgVersionInRepo

Usage

findPkgVersionInRepo(repo, name, version, param, dir)

## S4 method for signature 'character'
findPkgVersionInRepo(repo, name, version, param, dir)

## S4 method for signature ''NULL''
findPkgVersionInRepo(repo, name, version, param, dir)

Arguments

Value

A path to the downloaded tarball, or NULL

flushSession

Description

Unload currently loaded packages from the current R session

Usage

flushSession(dontunload = switchrDontUnload())

Arguments

Details

Attached packages are detached (and unloaded) first. After this is done, loaded packages, such as those imported by (previously) attached packages, are unloaded.

Finally, after all packages have been unloaded, native libraries loaded by those packages are unloaded (on systems where this is supported).

Value

NULL, called for its side-effect of unloading packages

Note

Failing to include switchr, any of its dependencies, or any base packages (available as a vector in the switchDeps object) in dontunload will result in undefined, likely erroneous behavior.

full_libpaths

Description

Accessor for the full library path associate with a SwitchrCtx, including the R library and (if not excluded) the site library

Usage

full_libpaths(seed)

## S4 method for signature 'SwitchrCtx'
full_libpaths(seed)

Arguments

Value

For the getter, the full set of library paths associated with the SwitchrCtx object, for the setter, the object, updated with the new set of full lib paths.

Construct pockage directory path

Description

Construct pockage directory path

Usage

getPkgDir(basepath, name, subdir, scm_type, branch)

Arguments

Value

A path

Note

Unlike findPkgDir this does not look for existing package source directories. It only constructs the path.

gotoVersCommit

Description

This is a low-level function not intended for direct use by the end user.

Usage

gotoVersCommit(dir, src, version, param = SwitchrParam())

## S4 method for signature 'character,SVNSource'
gotoVersCommit(dir, src, version, param = SwitchrParam())

## S4 method for signature 'character,CRANSource'
gotoVersCommit(dir, src, version, param = SwitchrParam())

## S4 method for signature 'character,BiocSource'
gotoVersCommit(dir, src, version, param = SwitchrParam())

## S4 method for signature 'character,GitSource'
gotoVersCommit(dir, src, version, param = SwitchrParam())

Arguments

Value

dir, after the side-effect of checking out the commit associated with the specified version is complete.

Internal internet harness

Description

This function should never be called by code outside of tests/vignettes in this package or packages that depend on it.

Usage

graceful_inet(val, silent)

warning2(...)

Arguments

Value

varies, these are internal functions not intended for end users.

Head and tail operations on manifests

Description

Head and tail operations on manifests

Usage

head(x, ...)

## S4 method for signature 'SessionManifest'
head(x, n = 5, ...)

## S4 method for signature 'PkgManifest'
head(x, n = 5, ...)

tail(x, ...)

## S4 method for signature 'SessionManifest'
tail(x, n = 5, ...)

## S4 method for signature 'PkgManifest'
tail(x, n = 5, ...)

Arguments

Details

In the case of a PkgManifest, the first or last n packages are retained in the manifest, while all others are removed.

In the case of a SessionManifest, n specified versions are retained, while the underlying PkgManifest is unchanged.

Value

An object of the same type as x containing n packages

install_packages

Description

Install packages from a set of traditional repositories, or a Just-in-time repository constructed using a PkgManifest or SessionManifest

Usage

install_packages(pkgs, repos, versions = NULL, verbose = FALSE, ...)

## S4 method for signature 'character,character'
install_packages(pkgs, repos, versions = NULL, verbose = FALSE, ...)

## S4 method for signature 'character,missing'
install_packages(pkgs, repos, versions = NULL, verbose = FALSE, ...)

## S4 method for signature 'SessionManifest,ANY'
install_packages(pkgs, repos, versions = NULL, verbose = FALSE, ...)

## S4 method for signature 'character,SessionManifest'
install_packages(pkgs, repos, versions = NULL, verbose = FALSE, ...)

## S4 method for signature 'character,PkgManifest'
install_packages(pkgs, repos, versions = NULL, verbose = FALSE, ...)

Arguments

Details

In addition to installing the specified packages, this function annotates the installed DESCRIPTION files with provenance information about where the packages were installed from. This retains the information necessary to generate a manifest of installed packages for publication or reinstallation.

When repos is a vector of traditional repositories, this function - with the exception of the provenance mentioned above - behaves identically to install.packages. Otherwise, a Just-in-Time package repository is constructed using the information in the manifest(s) passed to repos, which is then used in conjuction with link{install.packages} to do the actual installation.

Value

a vector of names of the packages installed.

Author(s)

Gabriel Becker

References

Becker G, Barr C, Gentleman R, Lawrence M; Enhancing Reproducibility and Collaboration via Management of R Package Cohorts. Journal of Statistical Software, 81(1). 2017. doi: 10.18637/jss.v082.i01

Examples

## Not run: 
## equivalent to install.packages, except it stores
## package provenance and knows about bioconductor repos
install_packages("nlme")

## install from a manifest
man = GithubManifest("gmbecker/fastdigest")
install_packages("fastdigest", man)

## install a full seeding manifest
man2 = makeSeedMan("myotherlib")
install_packages(man2)

## End(Not run)

lazyRepo

Description

Create a lazy repository for installing directly from a package manifest. Most users will want to call Install directly, which will call this as needed behind the scenes.

Usage

lazyRepo(
  pkgs,
  pkg_manifest,
  versions = rep(NA, times = length(pkgs)),
  dir = tempdir(),
  rep_path = file.path(dir, "repo"),
  get_suggests = FALSE,
  verbose = FALSE,
  scm_auths = list(bioconductor = c("readonly", "readonly")),
  param = SwitchrParam(),
  force_refresh = FALSE
)

## S4 method for signature 'SessionManifest,ANY'
lazyRepo(
  pkgs,
  pkg_manifest,
  versions = rep(NA, times = length(pkgs)),
  dir = tempdir(),
  rep_path = file.path(dir, "repo"),
  get_suggests = FALSE,
  verbose = FALSE,
  scm_auths = list(bioconductor = c("readonly", "readonly")),
  param = SwitchrParam(),
  force_refresh = FALSE
)

## S4 method for signature 'PkgManifest,ANY'
lazyRepo(
  pkgs,
  pkg_manifest,
  versions = rep(NA, times = length(pkgs)),
  dir = tempdir(),
  rep_path = file.path(dir, "repo"),
  get_suggests = FALSE,
  verbose = FALSE,
  scm_auths = list(bioconductor = c("readonly", "readonly")),
  param = SwitchrParam(),
  force_refresh = FALSE
)

## S4 method for signature 'character,SessionManifest'
lazyRepo(
  pkgs,
  pkg_manifest,
  versions = rep(NA, times = length(pkgs)),
  dir = tempdir(),
  rep_path = file.path(dir, "repo"),
  get_suggests = FALSE,
  verbose = FALSE,
  scm_auths = list(bioconductor = c("readonly", "readonly")),
  param = SwitchrParam(),
  force_refresh = FALSE
)

## S4 method for signature 'character,PkgManifest'
lazyRepo(
  pkgs,
  pkg_manifest,
  versions = rep(NA, times = length(pkgs)),
  dir = tempdir(),
  rep_path = file.path(dir, "repo"),
  get_suggests = FALSE,
  verbose = FALSE,
  scm_auths = list(bioconductor = c("readonly", "readonly")),
  param = SwitchrParam(),
  force_refresh = FALSE
)

Arguments

Details

When checking building from SVN or git checkouts, this function will first look for existing checkouts for the relevant packages in dir. If found, these will be updated (in the case of conflicts, the behavior is undefined and will likely fail if they are not resolvable). This allows the user to have an existing, checkout directory where he or she works on development versions of multiple, interrelated packages, as local changes WILL be reflected in the packages built into the lazy repository.

Value

A path to the populated lazy repository, suitable for 'coercing' to a url and installing from.

Author(s)

Gabriel Becker

References

Becker G, Barr C, Gentleman R, Lawrence M; Enhancing Reproducibility and Collaboration via Management of R Package Cohorts. Journal of Statistical Software, 81(1). 2017. doi: 10.18637/jss.v082.i01

libManifest

Description

Create a Session- or PkgManifest for the contents of a switchr library.

Usage

libManifest(
  lib = currentCompEnv(),
  record_versions = TRUE,
  known_manifest = makeManifest(dep_repos = repos),
  repos = defaultRepos(),
  ...
)

## S4 method for signature 'missing'
libManifest(
  lib = currentCompEnv(),
  record_versions = TRUE,
  known_manifest = makeManifest(dep_repos = repos),
  repos = defaultRepos(),
  ...
)

## S4 method for signature 'character'
libManifest(
  lib = currentCompEnv(),
  record_versions = TRUE,
  known_manifest = makeManifest(dep_repos = repos),
  repos = defaultRepos(),
  ...
)

## S4 method for signature 'SwitchrCtx'
libManifest(
  lib = currentCompEnv(),
  record_versions = TRUE,
  known_manifest = makeManifest(dep_repos = repos),
  repos = defaultRepos(),
  ...
)

Arguments

Value

a SessionManifest object containing version-specified entries for all packages installed in the specified library path(s).

Note

The manifest generated by this function will not include base packages, as they are part of R and not installable in the traditional sense.

Examples

if(interactive()) {
  man = libManifest()
  man
}

## Not run: 
man2 = libManifest("myotherlib")
man2

## End(Not run)

library_paths

Description

Accessor for which directories an SwitchrCtx is associated with.

Usage

library_paths(seed)

## S4 method for signature 'SwitchrCtx'
library_paths(seed)

Arguments

Value

for the getter, the set of library paths associated with the SwitchrCtx object, for the setter, said context udpated with the new full set of library paths.

Load a GRAN repo package

Description

Load a GRAN repo package

Usage

loadGRAN(nm = "current")

Arguments

Details

This function is a convenience to load the package GRAN<nm>, which will provide the contained GRAN repository as default repository within the switchr framework.

Value

NULL. Called for the side-effect of loading the specified package

loadManifest

Description

Load a package or session manifest from a file (local or URL)

Usage

loadManifest(fil)

Arguments

Value

A PkgManifest or SessionManifest object

locatePkgVersion

Description

Locate and download/build the exact version of a single package.

Usage

locatePkgVersion(
  name,
  version,
  pkg_manifest,
  param = SwitchrParam(),
  dir = notrack(repo),
  repo = NULL
)

Arguments

Value

The full path to the downloaded file , or NULL if unable to locate the package

Note

Locating and attempting to install a non-current version of a single will not work in general, due to dependency issues. In most cases a Just-in-Time repository should be created and used instead, e.g. via install_packages

This function is called internally during the construction of Just-in-Time repositories and during the installation of specific package versions.

Author(s)

Gabriel Becker

location

Description

Retreive the directory associated with an object

Usage

location(repo)

## S4 method for signature 'PkgSource'
location(repo)

Arguments

Value

a character containing the associated path

Author(s)

Gabriel Becker

logfun

Description

Get or set the logging function in an object associated with a SwitchrParam

Usage

logfun(x)

## S4 method for signature 'SwitchrParam'
logfun(x)

logfun(x) <- value

## S4 replacement method for signature 'SwitchrParam'
logfun(x) <- value

Arguments

Make a Bioconductor SVN url for a package

Description

Make SVN url for a Bioconductor package given the name, bioc version, and type of package.

Usage

makeBiocSVNURL(name, biocVers = getBiocvrFromRvr(), pkgtype = "software")

Arguments

Value

A vector of urls for the specified packages within the Bioconductor SVN repository

make file url

Description

make file url

Usage

makeFileURL(path)

Arguments

Value

A valid file URL

makeLibraryCtx

Description

Locate or create a specified switchr library

Usage

makeLibraryCtx(
  name,
  seed = NULL,
  pkgs = NULL,
  exclude.site = TRUE,
  contains,
  rvers = NULL,
  verbose = FALSE
)

Arguments

Details

This function is not intended to be called directly in most cases; switchTo calls it automatically.

Manifest constructor

Description

Create a package manifest

Usage

makeManifest(..., dep_repos = defaultRepos())

Arguments

Create a checkout of a package and all it's dependencies from a manifest

Description

Create a checkout of a package and all it's dependencies from a manifest

Usage

makePkgCheckout(
  pkgs,
  pkg_manifest,
  dir,
  get_suggests = c("none", "first", "all"),
  param = SwitchrParam(),
  scm_auths = list(bioconductor = c("readonly", "readonly")),
  repos = defaultRepos()
)

Arguments

Value

a character vector of all packages (incl. recursive dependnecies) checked out into dir

makePkgDir

Description

This is an internal function not intended to be called directly by end users

Usage

makePkgDir(
  name,
  source,
  path,
  latest_only,
  param = SwitchrParam(),
  forceRefresh = FALSE
)

## S4 method for signature 'ANY,SVNSource'
makePkgDir(
  name,
  source,
  path,
  latest_only = FALSE,
  param = SwitchrParam(),
  forceRefresh = FALSE
)

## S4 method for signature 'ANY,GithubSource'
makePkgDir(
  name,
  source,
  path,
  latest_only = FALSE,
  param = SwitchrParam(),
  forceRefresh = FALSE
)

## S4 method for signature 'ANY,GitSource'
makePkgDir(
  name,
  source,
  path,
  latest_only = FALSE,
  param = SwitchrParam(),
  forceRefresh = FALSE
)

## S4 method for signature 'ANY,ANY'
makePkgDir(
  name,
  source,
  path,
  latest_only,
  param = SwitchrParam(),
  forceRefresh = FALSE
)

## S4 method for signature 'ANY,CRANSource'
makePkgDir(
  name,
  source,
  path,
  latest_only,
  param = SwitchrParam(),
  forceRefresh = FALSE
)

## S4 method for signature 'ANY,BiocSource'
makePkgDir(
  name,
  source,
  path,
  latest_only,
  param = SwitchrParam(),
  forceRefresh = FALSE
)

## S4 method for signature 'ANY,TarballSource'
makePkgDir(
  name,
  source,
  path,
  latest_only,
  param = SwitchrParam(),
  forceRefresh = FALSE
)

## S4 method for signature 'ANY,LocalSource'
makePkgDir(
  name,
  source,
  path,
  latest_only,
  param = SwitchrParam(),
  forceRefresh = FALSE
)

Arguments

Details

Create a directory and populate it with package source code from the specified source

Value

logical scalar indicating success (TRUE) or failure of the operation.

makeSeedMan

Description

makeSeedMan

Usage

makeSeedMan(x, known_manifest = PkgManifest(), ...)

## S4 method for signature 'missing'
makeSeedMan(x, known_manifest = PkgManifest(), ...)

## S4 method for signature 'sessionInfo'
makeSeedMan(x, known_manifest = PkgManifest(), ...)

## S4 method for signature 'parsedSessionInfo'
makeSeedMan(x, known_manifest = PkgManifest(), ...)

## S4 method for signature 'data.frame'
makeSeedMan(x, known_manifest = PkgManifest(), ...)

Arguments

Value

a SessionManifest specifying a set of packages and their specific versions.

Examples

man = makeSeedMan()

Create a PkgSource object for a package

Description

Create a PkgSource object for a package

Usage

makeSource(
  url,
  type,
  user,
  password,
  scm_auth = list(),
  prefer_svn = FALSE,
  ...
)

Arguments

Value

an object inheriting from PkgSource for the specified location of a package's source code.

Get or set the manifest associated with an object

Description

Get or set manifest associated with an object

Usage

manifest(x)

manifest(x) <- value

## S4 method for signature 'SessionManifest'
manifest(x)

## S4 replacement method for signature 'SessionManifest'
manifest(x) <- value

Arguments

Value

A PkgManifest or SessionManifest object

Create Manifest from 'checkedout' directory containing many pkg dirs

Description

This function is useful when a developer has a 'checkout' directory where the sources for multiple packages live. Particularly, it allows one to work on multiple interlocking packages at the same time and have a manifest which will install them all together automatically when time for testing.

Usage

manifestFromCheckoutDir(pdir, recursive = FALSE, excl_pat = NULL)

Arguments

Value

A Package manifest with 'local' type entries for each package found within pdir.

Examples

## Not run: 
manifestFromCheckoutDir(".")

## End(Not run)

manifest_df

Description

Get or set the package location manifest (data.frame) associated with an object

Usage

manifest_df(x, ...)

## S4 method for signature 'SessionManifest'
manifest_df(x, session_only = TRUE, ...)

## S4 method for signature 'PkgManifest'
manifest_df(x)

manifest_df(x) <- value

## S4 replacement method for signature 'SessionManifest'
manifest_df(x) <- value

## S4 replacement method for signature 'PkgManifest'
manifest_df(x) <- value

Arguments

Value

for the getter, the manifest data.frame corresponding to the manifest, for the setter, a manifest updated with the new manifest data.frame.

normalizePath2

Description

Attempt to normalize a relative path to an absolute one. Optionally without resolving symlinks on non-Windows systems

Usage

normalizePath2(path, follow.symlinks = FALSE, winslash = "\\", mustWork = NA)

Arguments

Value

The normalized path.

Notrack directory

Description

This function is not intended to be called directly by the user.

Usage

notrack(repo)

## S4 method for signature ''NULL''
notrack(repo)

Arguments

Value

the path where retrieved package versions should be. If repo is NULL, a notrack directory is constructed within a temp directory.

Number of rows

Description

Number of rows

Usage

nrow(x)

## S4 method for signature 'PkgManifest'
nrow(x)

## S4 method for signature 'SessionManifest'
nrow(x)

Arguments

Value

The number of rows in the structure

packages

Description

List the packages installed in a switchr context (library)

Usage

packages(seed)

## S4 method for signature 'SwitchrCtx'
packages(seed)

Arguments

Value

a vector of package names installed in the specified switchr context.

Parse text output from printing SessionInfo objects

Description

Parse text output from printing SessionInfo objects

Usage

parseSessionInfoString(string)

Arguments

Value

a parsedSessionInfo object encoding the information string (ie print output of a sessionInfo call).

Parsed sessionInfo output

Description

An object representing the information in printed sessionInfo() output

pkgname

Description

Get or set the package name associated with a Package Source

Usage

pkgname(x)

## S4 method for signature 'PkgSource'
pkgname(x)

pkgname(x) <- value

## S4 replacement method for signature 'PkgSource'
pkgname(x) <- value

Arguments

Value

for the getter, the package name as a string, for the setter, an updated PkgSource (or subclass) object with the new package name.

publishManifest

Description

Publish a package or session manifest to file.

Usage

publishManifest(manifest, dest = "./pkg_manifest.rman", ...)

## S4 method for signature 'PkgManifest,character'
publishManifest(manifest, dest = "./pkg_manifest.rman", ...)

## S4 method for signature 'SessionManifest,character'
publishManifest(manifest, dest = "./pkg_manifest.rman", ...)

## S4 method for signature 'missing,ANY'
publishManifest(manifest, dest = "./pkg_manifest.rman", ...)

## S4 method for signature 'SwitchrCtx,ANY'
publishManifest(manifest, dest = "./pkg_manifest.rman", ...)

Arguments

Value

The name of the file written

rVersionManifest

Description

Create a Pkg manifest which points to tarballs representing the cohort of packages associated with a particular release of R

Usage

rVersionManifest(vers, curr_avail = available.packages())

Arguments

Value

A SessionManifest object

Author(s)

Gabriel Becker

References

"Gabor Csardi" (2014). crandb: Query the unofficial CRAN metadata database. R package version 1.0.0. https://github.com/metacran/crandb

Becker G, Barr C, Gentleman R, Lawrence M; Enhancing Reproducibility and Collaboration via Management of R Package Cohorts. Journal of Statistical Software, 81(1). 2017. doi: 10.18637/jss.v082.i01

Examples

## Not run: 
man = rVersionManifest("3.1.1")
man

## End(Not run)

removeLib

Description

Remove a switchr library and update the manifest of existing libraries

Usage

removeLib(name = NULL, repos = NULL, compEnv = NULL, fromStack = FALSE)

Arguments

Value

NULL, called for its side-effect of removing/destroying a switchr library

Note

Only one of name, repos and compEnv should be specified. An error will be thrown otherwise.

Examples

## Not run: 
removeLib("mylibrary")

## End(Not run)

shell init

Description

Set or Retrieve the shell initialization script for an object

Usage

sh_init_script(x)

## S4 method for signature 'SwitchrParam'
sh_init_script(x)

sh_init_script(x) <- value

## S4 replacement method for signature 'SwitchrParam'
sh_init_script(x) <- value

Arguments

Value

For the getter, the shell initialization script/commands, for the setter, an updated SwitchrParam object with the new shell initialization set.

Get or set the number of seconds to wait between successive shell commands

Description

This is intended to stop intermittent install failures due to network drive latency interacting with git commands

Usage

shell_timing(x)

## S4 method for signature 'SwitchrParam'
shell_timing(x)

shell_timing(x) <- value

## S4 replacement method for signature 'SwitchrParam'
shell_timing(x) <- value

Arguments

Value

When getting, the number of seconds to wait, when setting, a new, updated SwitchrParam object.

subdir

Description

accessor for subdirectory.

Usage

subdir(x)

## S4 method for signature 'PkgSource'
subdir(x)

subdir(x) <- value

## S4 replacement method for signature 'PkgSource'
subdir(x) <- value

Arguments

Value

For the getter, the subdirectory within the overall source to find the actual package source code, for the setter, an updated PkgSource object with the new subdirectory set.

switchBack

Description

A convenience function to switch back to the previously used computing environment.

Usage

switchBack()

Value

silently, the name of the switchr context now active.

switchrDeps

Description

The base packages, as well as switchr and its dependencies.

Usage

switchDeps

Format

An object of class character of length 20.

Value

the base packages, plus the set of packages switchr itself has dependencies on

switchTo

Description

Switch to a different computing environment (set of installed R packages and library location paths for new pkg installs)

Usage

switchTo(
  name,
  seed = NULL,
  reverting = FALSE,
  ignoreRVersion = FALSE,
  exclude.site = TRUE,
  ...
)

## S4 method for signature 'character,character'
switchTo(
  name,
  seed = NULL,
  reverting = FALSE,
  ignoreRVersion = FALSE,
  exclude.site = TRUE,
  ...
)

## S4 method for signature 'character,SwitchrCtx'
switchTo(
  name,
  seed = NULL,
  reverting = FALSE,
  ignoreRVersion = FALSE,
  exclude.site = TRUE,
  ...
)

## S4 method for signature 'character,missing'
switchTo(
  name,
  seed = NULL,
  reverting = FALSE,
  ignoreRVersion = FALSE,
  exclude.site = TRUE,
  ...
)

## S4 method for signature 'SwitchrCtx,ANY'
switchTo(
  name,
  seed = NULL,
  reverting = FALSE,
  ignoreRVersion = FALSE,
  exclude.site = TRUE,
  ...
)

## S4 method for signature 'character,RepoSubset'
switchTo(
  name,
  seed = NULL,
  reverting = FALSE,
  ignoreRVersion = FALSE,
  exclude.site = TRUE,
  ...
)

## S4 method for signature 'character,PkgManifest'
switchTo(
  name,
  seed = NULL,
  reverting = FALSE,
  ignoreRVersion = FALSE,
  exclude.site = TRUE,
  ...
)

## S4 method for signature 'character,SessionManifest'
switchTo(
  name,
  seed = NULL,
  reverting = FALSE,
  ignoreRVersion = FALSE,
  exclude.site = TRUE,
  ...
)

Arguments

Details

If switchr does not now about the specified computing environment, a new one will be created via installCompEnv. This includes creating a directory under the switchr base directory and installing packages into it. See installCompEnv for more details.

This function has the side effect of unloading all loaded packages (other than base packages, GRAN or GRANBAse, switchr itself, and switchr's dependencies) and the associated DLLs. It also changes the library location R will use to search for packages, e.g. when you call library.

This means you will have to reinstall packages after switching, which is important and intended (e.g. when switching to using Bioc devel from Bioc release).

Value

Invisibly returns the SwitchrCtx object representing the new computing environment

Note

By default, this process involves a call to flushSession which will attempt to unload all loaded packages. While some support of configuring what is unloaded is provided via switchrDontUnload, it is recommended that you turn this feature entirely off via switchrNoUnload(TRUE) when using switchr within dyanmic documents (.Rnw/.Rmd files, etc), particularly when using the knitr package.

References

Becker G, Barr C, Gentleman R, Lawrence M; Enhancing Reproducibility and Collaboration via Management of R Package Cohorts. Journal of Statistical Software, 81(1). 2017. doi: 10.18637/jss.v082.i01

See Also

makeLibraryCtx

Examples

## Not run: 
switchTo("mynewlibrary")
switchBack()

fdman = GithubManifest("gmbecker/fastdigest")
switchTo("fastdigestlib", seed = fdman)

## End(Not run)

Get or set the base directory for switchr libraries

Description

Get or set the base directory for switchr libraries

Usage

switchrBaseDir(value)

Arguments

Details

If value is missing, the current base directory is returned. Otherwise the value is set as the default directory and returned.

Value

The current base directory for switchr to create context-specific library paths under (after setting it if value is not missing).

Get or set packages to not unload when flushing the system

Description

Get or set packages which should NOT be unloaded when flushing the system, e.g., when switching between libraries.

Usage

switchrDontUnload(value, add = TRUE)

Arguments

Value

the set of packages switchr will not attempt to unload which changing contexts (after setting it, if value is missing)

Note

By default switchr will not attempt to unload any base packages, itself, or any of its dependencies. Attempting to unload any of these packages (e.g. add=FALSE) will result in undefined behavior and is not recommended.

switchrManifest

Description

Generate a manifest of all currently available (existing) swtichr libraries.

Usage

switchrManifest()

Value

A data.frame with information about the located switchr libraries

Note

This function reads cached metadata from the current switchr base directory (~/.switchr by default). This cache is updated whenever the switchr framework is used to create or destroy a switchr library, but will not be updated if one is added or removed manually. In such cases updateManifest must be called first

Skip unloading of packages in session

Description

Set whether or not ANY packages are unloaded when switching libraries.

Usage

switchrNoUnload(value)

Arguments

Details

This should be set to TRUE when using switchr in the context of dynamic documents such as .Rnw and .Rmd files.

Value

A logical indicating whether or not calling flushSession will skipped during the library switching process.

system_w_init

Description

Run a system command with an optional intialization script (e.g. a .bashrc sourced first).

Usage

system_w_init(
  cmd,
  dir,
  init = character(),
  args = NULL,
  env = NULL,
  ...,
  param = SwitchrParam()
)

Arguments

Value

Depends, see system for details.

updateManifest

Description

Update the cached information regarding available switchr libraries.

Usage

updateManifest()

Value

NULL, used for it's side-effect of updating the switchr library metadata cache.

update existing package repository

Description

Update an existing repository by reading the PACKAGES file and only processing built package tarballs which do not match existing entries.

update_PACKAGES can be much faster than write_PACKAGES for small-moderate changes to large repository indexes.

Usage

update_PACKAGES(
  dir = ".",
  fields = NULL,
  type = c("source", "mac.binary", "win.binary"),
  verbose = dryrun,
  unpacked = FALSE,
  subdirs = FALSE,
  latestOnly = TRUE,
  addFiles = FALSE,
  strict = TRUE,
  dryrun = FALSE,
  logfun = message,
  ...
)

Arguments

Details

Throughout this section, package tarball is taken to mean a tarball file in dir whose name can be interpreted as <package>_<version>.<ext> (or that is pointed to by the File field of an existing PACKAGES entry). Novel package tarballs are those which do not match an existing PACKAGES file entry.

update_PACKAGES avoids (re)processing package tarballs in cases where a PACKAGES file entry already exists and appears to remain valid. The logic for detecting still-valid entries is as follows:

Currently update_PACKAGES calls directly down to write_PACKAGES (and thus no speedup should be expected) if any of the following conditions hold:

• No PACKAGES file exists under dir

• unpacked is TRUE

• subdirs is anything other than FALSE

• fields is not NULL and one or more specified fields are not present in the existing PACKAGES file

All package tarballs whose last modify times are later than that of the existing PACKAGES file are considered novel and no attempt is made to identify or retain any corresponding PACKAGES entries. Similarly, all PACKAGES entries which have no corresponding package tarball are definitionally invalid.

When strict = TRUE, PACKAGES entries which appear to match a package tarball are confirmed via MD5 checksum; those that pass are retained as valid. All novel package tarballs are fully proccessed by the standard write_PACKAGES machinery, and the resulting entries are added. Finally, if latestOnly = TRUE, package-version pruning is performed across the entries.

When strict = FALSE, package tarballs are assumed to encode correct metadata in their filenames. PACKAGES entries which appear to match a package tarball are retained as valid (No MD5sum checking occurs). If latestOnly = TRUE, package-version pruning across the full set of retained entries and novel package tarballs before the processing of the novel tarballs, at significant computational and time savings in some situations. After the optional pruning, any relevant novel package tarballs are processed via write_PACKAGES and added to the set of retained entries.

After the above process concludes, the final database of PACKAGES entries is written to all three PACKAGES files, overwriting the existing files.

Value

Called for its side-effect of updating a package repository index PACKAGES file and siblings.

Note

While both strict and nonstrict modes offer speedups when updating small percentages of large repositories, non-strict mode is much faster and is recommended in situations where the assumptions it makes are safe.

For versions of R 3.6.0 and later, use tools::update_PACKAGES, which was adapted from this fuction, instead.

Author(s)

Gabriel Becker

See Also

write_PACKAGES

versions_df

Description

Get or set the the versions information in a SessionManifest

Usage

versions_df(x)

## S4 method for signature 'SessionManifest'
versions_df(x)

versions_df(x) <- value

## S4 replacement method for signature 'SessionManifest'
versions_df(x) <- value

Arguments

Value

For the getter, a data.frame indicating the versions-specific cohort of packages defined by x, for the setter, the SessionManifest object updated with the new versions data.frame.