{"id":18733539,"url":"https://github.com/insightsengineering/scribe","last_synced_at":"2025-04-12T18:31:49.608Z","repository":{"id":207394993,"uuid":"561585712","full_name":"insightsengineering/scribe","owner":"insightsengineering","description":"System Compatibility Reports for Install \u0026 Build Evaluation","archived":false,"fork":false,"pushed_at":"2025-03-13T08:40:16.000Z","size":1251,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-26T12:51:14.848Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://insightsengineering.github.io/scribe/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/insightsengineering.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://pharmaverse.org"]}},"created_at":"2022-11-04T02:29:34.000Z","updated_at":"2025-03-13T08:34:56.000Z","dependencies_parsed_at":"2024-01-12T15:04:04.471Z","dependency_job_id":"8207a41c-33a5-4145-b9a4-95bac95fb971","html_url":"https://github.com/insightsengineering/scribe","commit_stats":null,"previous_names":["insightsengineering/scribe"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Fscribe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Fscribe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Fscribe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Fscribe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/insightsengineering","download_url":"https://codeload.github.com/insightsengineering/scribe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248613543,"owners_count":21133531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T15:10:20.491Z","updated_at":"2025-04-12T18:31:49.591Z","avatar_url":"https://github.com/insightsengineering.png","language":"Go","funding_links":["https://pharmaverse.org"],"categories":[],"sub_categories":[],"readme":"# scribe\n\n[![build](https://github.com/insightsengineering/scribe/actions/workflows/test.yml/badge.svg)](https://github.com/insightsengineering/scribe/actions/workflows/test.yml)\n\n`scribe` (acronym for `s`ystem `c`ompatibility `r`eport for `i`nstall \u0026 `b`uild `e`valuation) is a project that creates complete build, check and install reports for a collection of R projects that are defined in an [renv.lock](https://rstudio.github.io/renv/articles/lockfile.html) file.\n\n`renv.lock` file can be typically generated by the `renv` R package, but you may also want to take a look at [`locksmith`](https://github.com/insightsengineering/locksmith) which can generate such a file more efficiently.\n\n`scribe`, based on the input `renv.lock`:\n\n* downloads R packages from package repositories or GitHub/GitLab repositories,\n* determines the order in which the packages should be built and installed,\n* builds packages from `git` repositories, and installs all of the packages (by running `R CMD build` and `R CMD INSTALL` respectively),\n* checks the specified subset of packages by running `R CMD check`,\n* generates an HTML report with the statuses of the above processes.\n\n![Report example](./images/report.png)\n\nThe statuses in the report shown above, when clicked, show the logs from the execution of `R CMD build`, `R CMD INSTALL`, or `R CMD check`.\n\n## Installing\n\nSimply download the project for your distribution from the [releases](https://github.com/insightsengineering/scribe/releases) page. `scribe` is distributed as a single binary file and does not require any additional system requirements other than `R`, with which it integrates and interfaces externally.\n\nOr, if you have a Go environment, you can simply install the latest version of `scribe` by running:\n\n```sh\ngo install github.com/insightsengineering/scribe@latest\n```\n\n## Usage\n\n`scribe` is a command line utility, so after installing the binary in your `PATH`, simply run the following command to view its capabilities:\n\n```bash\nscribe --help\n```\n\nExample usage with multiple flags:\n\n* ```bash\n  scribe --config custom-config-file.yml --logLevel debug --maskedEnvVars 'password|key|regexForAnEnvVarThatShouldNotBeDisplayed' --renvLockFilename output-renv.lock --reportDir output-report-directory\n  ```\n* Specifying for which packages `R CMD check` should be run.\n    ```bash\n    scribe --checkPackage 'package*,*abc,a*b,someOtherPackage'\n    ```\n* Changing the default number of concurrent goroutines for downloading packages, running `R CMD check`, and running package building and installation.\n    ```bash\n    scribe --maxDownloadRoutines 40 --maxCheckRoutines 10 --numberOfWorkers 20\n    ```\n* Passing additional options to `R CMD build`, `R CMD INSTALL` and `R CMD check`.\n    ```bash\n    scribe --buildOptions '--no-manual --no-build-vignettes' --installOptions '--no-docs' --checkOptions '--ignore-vignettes'\n    ```\n\nTo download packages from `git` repositories, `scribe` uses Personal Access Tokens defined in environment variables:\n* for GitLab, it reads the token from `GITLAB_TOKEN` variable,\n* for GitHub, it reads the token from `GITHUB_TOKEN` variable.\n\n## Configuration file\n\nIf you'd like to set the above options in a configuration file, by default `scribe` tries to read `~/.scribe`, `~/.scribe.yaml` and `~/.scribe.yml` files.\nIf any of these files exist, `scribe` uses options defined there, unless they are overridden by command line flags.\n\nYou can also specify a custom path to configuration file with `--config \u003cyour-configuration-file\u003e.yml` command line flag.\nWhen using custom configuration file, if you specify command line flags, the latter will still take precedence.\n\nExample contents of configuration file:\n\n```yaml\nlogLevel: debug\nmaskedEnvVars: secret-variable-name|another_variable_name\ncheckPackage: teal*,tern\nrenvLockFilename: custom-renv.lock\noutputReport: output-report-directory\nmaxDownloadRoutines: 40\nmaxCheckRoutines: 10\nnumberOfWorkers: 20\nbuildOptions: --no-manual --no-build-vignettes\ninstallOptions: --no-docs\ncheckOptions: --ignore-vignettes\n```\n\n## Environment variables\n\n`scribe` reads environment variables with `SCRIBE_` prefix and tries to match them with CLI flags.\nFor example, setting the following variables will override the respective values from configuration file:\n`SCRIBE_LOGLEVEL`, `SCRIBE_CHECKPACKAGE`, `SCRIBE_RENVLOCKFILENAME`, `SCRIBE_OUTPUTREPORT` etc.\n\nThe order of precedence is:\n\nCLI flag → environment variable → configuration file → default value.\n\n## Package repositories\n\nIf `scribe` should use source packages, then the repository URLs in the `renv.lock` header should point\nto the location where the `/src/contrib` directory is located (without the trailing `/`), for example:\n\n```json\n\"R\": {\n  \"Repositories\": [\n    {\n      \"Name\": \"CRAN\",\n      \"URL\": \"https://packagemanager.posit.co/cran/latest\"\n    }\n  ]\n}\n```\n\nFor `scribe` to use binary packages, it expects the `renv.lock` to contain the repository definitions pointing to the binary repositories.\n\nExamples of expected format of binary repository URLs:\n\n* Linux:\n  * `https://packagemanager.posit.co/cran/__linux__/\u003cdistribution-name\u003e/latest`\n* Windows:\n  * `https://cloud.r-project.org/bin/windows/contrib/\u003cr-version\u003e`\n  * `https://www.bioconductor.org/packages/release/bioc/bin/windows/contrib/\u003cr-version\u003e`\n  * `https://packagemanager.posit.co/cran/latest/bin/windows/contrib/\u003cr-version\u003e`\n* macOS:\n  * `https://cloud.r-project.org/bin/macosx/contrib/\u003cr-version\u003e`\n  * `https://www.bioconductor.org/packages/release/bioc/bin/macosx/big-sur-arm64/contrib/\u003cr-version\u003e`\n  * `https://www.bioconductor.org/packages/release/bioc/bin/macosx/big-sur-x86_64/contrib/\u003cr-version\u003e`\n  * `https://packagemanager.posit.co/cran/latest/bin/macosx/big-sur-x86_64/contrib/\u003cr-version\u003e`\n  * `https://packagemanager.posit.co/cran/latest/bin/macosx/big-sur-arm64/contrib/\u003cr-version\u003e`\n\nwhere `\u003cr-version\u003e` is e.g. `4.2`, `4.3` etc.\n\nIn all cases the URL points to a directory where the `PACKAGES` file is located, without the trailing `/`.\n\nAdditionally, on Windows it might be required to tell `scribe` where the R executable is located by using flag: `--rExecutablePath 'C:\\Program Files\\R\\R-4.3.2\\bin\\R.exe'`.\n\n## Cache\n\n`scribe` uses cache stored in `/tmp/scribe` for various purposes.\n\nThe results of download, installation, build and check stages are stored in `/tmp/scribe/cache`.\nWhen `scribe` detects presence of files with such results, it skips respective stages.\n\nIn order to run the download, installation, build and check from scratch, the `/tmp/scribe/cache` directory should be removed manually.\nRemoving 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.\n\nThe cache can also be cleared with `--clearCache` flag.\n\n## Development\n\nThis project is built with the [Go programming language](https://go.dev/).\n\n### Development Environment\n\nIt is recommended to use Go 1.22+ for developing this project.\nThis project uses a pre-commit configuration and it is recommended to [install and use pre-commit](https://pre-commit.com/#install) when you are developing this project.\n\n### Common Commands\n\nRun `make help` to list all related targets that will aid local development.\n\n### Style\n\nThis project adopts the [Uber styleguide](https://github.com/uber-go/guide/blob/master/style.md).\n\n## License\n\n`scribe` is licensed under the Apache 2.0 license. See [LICENSE.md](LICENSE.md) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsightsengineering%2Fscribe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsightsengineering%2Fscribe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsightsengineering%2Fscribe/lists"}