baler

A package manager for {box} modules

Why baler (an overview)

{baler} is a package manager with thin-wrapper command line interface (CLI), and serves as a “tracker” for {box} modules, including the versions and the dependencies being used. This CLI tool is written in Rust. {box} package and {baler} are mutually exclusive: {box} is an R package that gives R a proper module (reusability and composability of R codes) system, but {baler} is built like a cargo for Rust that does the job to gives {box} modules a way to be packaged, versioned, and distributed. The interface and usage is also deliberately close to Python’s pip, as well.

To make {box} modules distributable, installable, and trackable through {baler}, one must carry one extra file at its root: baler.toml. It is a metadata file that plays the same role DESCRIPTION plays for an R package or pyproject.toml plays for a Python package (name, version, license, authors, and both R package and {box} module dependencies). You can also optionally lock the dependencies of the modules under {baler} through a lockfile in the name of baler.lock (see for more details). Read the following documentations first:

  1. Official docs

  2. Placing module system into R

To get the explanations on how {box} modules work.

There’s no actual formal name to call these packaged {box} modules, so let’s call it as box-bale modules for now (you can call it as just box or bale if you wanted to). To see how {baler} works as a starter, see the following guide under Get Started.

Commands

A following usage is baler <command> ... on the command line. Here are the following primary <command> you can use:

  • init (Optional): scaffold a new module project together with the most important file: baler.toml.
  • bundle: package a module in a .tar.gz archive.
  • install: install a bundled archive, a local module directory, or a module living in a repo (for instance, for GitHub repo: --git https://github.com/user/repo), and optionally resolve its R package dependencies (it looks up from CRAN by default). It also checks the installed R against the module’s declared r_version constraint before proceeding.
  • lock: resolve a module’s R package dependencies to exact versions and write baler.lock, so a later install reuses those pins instead of re-resolving against CRAN. Also checks r_version and records the resolving R version in the lock. The lockfile is NOT always required.
  • remove: uninstall a module. Use --force to skip the prompt and outright uninstall the module.

Disclaimer

Take note that {baler} is a CLI tool and it doesn’t replace ANYTHING, and that includes traditional R packages ({box} modules can still depend on CRAN-style packages, after all). In fact, it is built for a primary purpose, that is to add another option — to be a “tracker” and/or a “package manufacturer”, responsible for managing {box} module packages involving packaging/bundling and installations, so {baler} rather gives more opportunity for {box} modules. Once box-bale packages are installed, you can attach them through box::use(), as this function automatically resolves it the same way it resolves any other module (see details for the installation, as well as the patched {box} fork this currently requires).

Begin with Get Started for a full walkthrough as starters, or jump to the CLI reference if you already know what you’re doing.