Categorygithub.com/insightsengineering/scribe
modulepackage
0.2.13
Repository: https://github.com/insightsengineering/scribe.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
1
Dependents
0
Files
4 SLOC

# README

scribe

build

scribe (acronym for system compatibility report for install & build evaluation) is a project that creates complete build, check and install reports for a collection of R projects that are defined in an renv.lock file.

Installing

Simply download the project for your distribution from the releases page. scribe is distributed as a single binary file and does not require any additional system requirements other than git and R, both of which it integrates and interfaces with externally.

Usage

scribe is a command line utility, so after installing the binary in your PATH, simply run the following command to view its capabilities:

scribe --help

Example usage with multiple flags:

scribe --logLevel debug --maskedEnvVars 'password|key' --renvLockFilename renv2.lock --checkPackage 'tern*,teal*' --reportDir htmlreportdir --maxDownloadRoutines 100 --maxCheckRoutines 20 --numberOfWorkers 150 --clearCache

To download packages from git repositories, scribe retrieves PAT from environment variables:

  • for GitLab, it reads the token from GITLAB_TOKEN variable,
  • for GitHub, it reads the token from GITHUB_TOKEN variable.

Configuration file

If you'd like to set the above options in a configuration file, by default scribe checks ~/.scribe, ~/.scribe.yaml and ~/.scribe.yml files. If this file exists, scribe uses options defined there, unless they are overridden by command line flags.

You can also specify custom path to configuration file with --config <your-configuration-file>.yml command line flag. When using custom configuration file, if you specify command line flags, the latter will still take precedence.

Example contents of configuration file:

logLevel: trace
checkPackage: teal*
maskedEnvVars: secret-variable-name
renvLockFilename: custom-renv.lock
checkAllPackages: true
outputReport: someDirectoryName
maxDownloadRoutines: 30
maxCheckRoutines: 31
numberOfWorkers: 32
clearCache: true

Binary dependencies

For scribe to use binary packages, it expects the renv.lock to contain the repository definitions pointing to the binary repositories.

Examples of expected format of binary repository URLs:

  • Linux:
    • https://packagemanager.posit.co/cran/__linux__/<distribution-name>/latest
  • Windows:
    • https://cloud.r-project.org/bin/windows/contrib/<r-version>
    • https://www.bioconductor.org/packages/release/bioc/bin/windows/contrib/<r-version>
    • https://packagemanager.posit.co/cran/latest/bin/windows/contrib/<r-version>
  • macOS:
    • https://cloud.r-project.org/bin/macosx/contrib/<r-version>
    • https://www.bioconductor.org/packages/release/bioc/bin/macosx/big-sur-arm64/contrib/<r-version>
    • https://www.bioconductor.org/packages/release/bioc/bin/macosx/big-sur-x86_64/contrib/<r-version>
    • https://packagemanager.posit.co/cran/latest/bin/macosx/big-sur-x86_64/contrib/<r-version>
    • https://packagemanager.posit.co/cran/latest/bin/macosx/big-sur-arm64/contrib/<r-version>

where <r-version> is e.g. 4.2, 4.3 etc.

In all cases the URL points to a directory where the PACKAGES file is located.

Additionally, on Windows it might be required to point scribe to a local R installation, for example by using flag: --rExecutablePath 'C:\Program Files\R\R-4.3.2\bin\R.exe'.

Environment variables

Scribe reads environment variables with SCRIBE_ prefix and tries to match them with CLI flags. For example, setting the following variables will override the respective values from configuration file: SCRIBE_LOGLEVEL, SCRIBE_CHECKPACKAGE, SCRIBE_RENVLOCKFILENAME, SCRIBE_CHECKALLPACKAGES, SCRIBE_OUTPUTREPORT etc.

The order of precedence is:

CLI flag → environment variable → configuration file → default value.

Cache

scribe uses cache stored in /tmp/scribe for various purposes.

The results of download, installation, build and check stages are stored in /tmp/scribe/cache. When scribe detects presence of files with such results, it skips respective stages.

In order to run the download, installation, build and check from scratch, the /tmp/scribe/cache directory should be removed manually. Removing whole /tmp/scribe directory is also possible - in that case, the packages will have to be downloaded again because cached tar.gz packages and git repositories are stored in this directory.

Development

This project is built with the Go programming language.

Development Environment

It is recommended to use Go 1.20+ for developing this project. This project uses a pre-commit configuration and it is recommended to install and use pre-commit when you are developing this project.

Common Commands

Run make help to list all related targets that will aid local development.

Style

This project adopts the Uber styleguide.

License

scribe is licensed under the Apache 2.0 license. See LICENSE.md for details.

# Packages

Copyright 2023 F.