Build a local meta-package — create

Creates the full structure and files of a meta-package that installs, manages and loads a set of locally stored R packages, resolving the dependencies between them with a graph-based (topologically ordered) approach.

Usage

create_metapackage(
  name,
  packages,
  pkg_dir = NULL,
  ext = ".tar.gz",
  version = "0.1.0",
  dest_dir,
  reexport = FALSE,
  document = TRUE,
  verbose = getOption("bigbang.verbose", interactive()),
  authors =
    "person('First', 'Last', email = 'first.last@example.com', role = c('aut', 'cre'))",
  description = "Local Package Metapackage",
  license = "MIT + file LICENSE",
  additional_deps = NULL,
  ignore_deps = NULL,
  import_deps = c("data.table", "dplyr", "ggplot2", "readr", "tibble", "tidyr", "xts",
    "zoo"),
  force_deps = NULL,
  debug = FALSE,
  workflow = NULL,
  include_archives = TRUE,
  tolerate = character(),
  dry_run = FALSE,
  on_component_error = c("abort", "skip"),
  update = FALSE,
  install_upgrade = c("newer", "always", "never"),
  reexport_prefer = character(),
  reexport_exclude = character(),
  recover = FALSE
)

Arguments

name: Character. Name of the meta-package to create (must not contain underscores _).
packages: Character vector. Archive paths or stems of the local packages to include. An existing file is always used as a path; otherwise the element is resolved as a stem in pkg_dir, e.g. "myPackage_1.0.0". A bare package name such as "myPackage" resolves when exactly one archive in those directories declares that Package identity. Zero matches use the usual unresolved-archive error; multiple matches are an ambiguity error. Supported archives that cannot be read during this identity search are excluded with a warning that names the archive. Existing paths may come from different directories. A single existing text file without a recognized archive extension is treated as a manifest, with one component per line; relative paths in that file are resolved relative to the manifest directory, absolute paths and ~ paths are used as written, and bare archive filenames may also be found in pkg_dir.
pkg_dir: Character. Optional directory or directories containing local archives used to resolve stems and bare package names. It is not needed when every packages element is an existing archive path.
ext: Character. Fallback archive extension for stems. Defaults to ".tar.gz"; each existing archive path keeps its own extension.
version: Character. Version of the meta-package. Defaults to "0.1.0".
dest_dir: Character. Required destination directory. The function writes the generated meta-package exclusively inside this directory; there is no default path. Use tempdir() for disposable output.
reexport: Logical flag retained in its original position for positional-call compatibility. The default FALSE attaches installed components as usual. With TRUE, explicit exports read from each component's NAMESPACE are exposed through read-only active bindings. Components are never added to Imports or Depends, so the generated package still installs offline without them. Evaluating a binding never throws: if a component is absent, cannot be loaded, or is an older installation that no longer exports the symbol, it returns a callable placeholder. Calling it reports the component, installed version, missing export, and the <name>_install() call that repairs the installation. Namespace inspection is safe for the same reason. For non-function exports, access therefore returns the placeholder instead of the object until the component is installed. The same binding then works without reloading the metapackage. Only explicit export() directives become bindings. S4 classes and methods remain available by loading their component package. Non-syntactic explicit export names are quoted in the generated NAMESPACE. An object restored with readRDS() does not load a component by itself, so base R cannot dispatch that component's S3 method until it is loaded.
document: Logical. If TRUE, runs devtools::document() automatically. Defaults to TRUE. The planned man/<name>_*.Rd and internal-helper Rd filenames are reserved for generated documentation; custom Rd files should use different names. A successful documentation run may adopt a reserved filename into the generation manifest, after which a later update with document = FALSE removes it as generated output.
verbose: Logical. If TRUE, shows verbose messages. The default follows getOption("bigbang.verbose", interactive()).
authors: Character. Content for the Authors@R field of DESCRIPTION.
description: Character. Description of the meta-package.
license: Character. License of the meta-package.
additional_deps: Character vector. Extra dependencies to add on top of the ones declared by components. Source-code guesses are diagnostic by default; use this argument when a guessed dependency should bind in the generated package.
ignore_deps: Character vector. Dependencies to ignore even if detected.
import_deps: Character vector. Packages that should go in the Imports field of DESCRIPTION rather than Depends. Imports are not attached when the user calls library() on the meta-package, but remain available via :: (e.g. dplyr::filter()), reducing name clashes in the user's workspace.
force_deps: Character vector. Exact package names to use as dependencies, bypassing automatic detection. If supplied, only these are used as the meta-package's implicit dependencies.
debug: Logical. If TRUE, emits detailed debugging messages. Defaults to FALSE.
workflow: Optional named character vector mapping ordered stage labels to component package names. When supplied, every component must appear once and a pipeline vignette skeleton is generated.
include_archives: Logical. If TRUE, the default, the component archives are copied into inst/archives/ of the generated meta-package, so that the meta-package is the only artifact that has to be distributed and <meta>_install() works with no arguments, without any path being agreed on beforehand. Components still install only where they can: a Windows binary archive is refused on other platforms. Shipping the archives also means redistributing them, so their licenses have to allow it, and it makes the generated tarball as large as its components: CRAN prefers source tarballs under 10 MB and does not accept binary executables in them, which matters only if a generated meta-package is ever submitted there. Set it to FALSE when the archives stay in a shared location that recipients can reach; then <meta>_install() requires an explicit pkg_dir.
tolerate: Character vector of explicitly named validation relaxations. Use "filename_mismatch" to silence filename-versus-DESCRIPTION mismatch warnings, or "unincluded_local_dep" to turn an available-but-unincluded local dependency error into a warning. With the latter relaxation, the generated metapackage does not ship that dependency: the recipient must provide it through pkg_dir or a repository with cran_deps = "install". Unknown names are errors. Each applied relaxation is recorded in the returned tolerated table.
dry_run: Logical. If TRUE, resolves and validates components and returns the planned generation without creating dest_dir or writing a project. For an update, sibling journal reconciliation is also planned and reported with its paths and actions without changing those folders.
on_component_error: Character policy for component-level failures: "abort" (default) stops generation, while "skip" omits the failed component and transitively omits components that depend on it. When a failed archive still exposes its DESCRIPTION, propagation uses its declared Package; otherwise the filename-derived name is used and the limitation is reported. If that fallback name differs from Package, a dependent may fail on the recipient. During an update, omitted inputs never authorize deletion of a previously shipped archive. When the old component cannot be identified unambiguously, archive reconciliation is deferred until a clean update rather than risking the only surviving copy.
update: Logical. If TRUE, update a previously generated project only when its bigbang manifest is present and all generated files are unchanged. A planned file absent from both the manifest and the project is a new generated file and is added. A planned file already present outside the manifest is treated as user content and makes the update fail without touching it. Files outside that manifest are never touched. Updates are refused when the generated project root, a manifest file, or any path component inside the project is a symbolic link, so writes cannot escape the project tree. Generated files no longer in the plan are reported in removed_files. Removing a component also removes its shipped archive, which may be the last available copy. Before changing the project, an update backs up every generated file and its manifest. A failed update restores that state so the same update can be retried. Updates take an exclusive project lock across preparation, reconciliation, generation, rollback, and journal publication. A second session preserves a live preparation and reports recover = TRUE as the next action until the owner is proven to have finished. Documentation files requested by document = TRUE follow the same rule: absent planned files are added, while existing untracked files are refused. See document for the reserved generated-documentation filenames.
install_upgrade: Character default upgrade policy emitted in the generated installer function: "newer", "always", or "never". This controls whether a generated installer keeps newer installed versions, reinstalls every component, or skips archive inspection.
reexport_prefer: Named character vector mapping symbols to the one component that should provide them when reexport = TRUE, for example c(filter = "componentb"). Names and values must be non-empty and each named component must be included and export the mapped symbol.
reexport_exclude: Character vector of symbols that must not be re-exported. Symbols are validated against the explicit exports of the included components and cannot also appear in reexport_prefer.
recover: Logical. With update = TRUE, request recovery after the durable journal owner has been confirmed finished, or when a file has user content that is neither the original nor an intended update value. Unknown content is copied byte for byte to a new preserved directory beside the project before recovery; that directory is reported and is never removed automatically. A proven-live owner still blocks mutation; an uncertain owner can be reclaimed only with recover = TRUE. Defaults to FALSE.

Value

Invisibly, a bigbang_result containing the generated path, component archives, dependency classification, applied tolerations, files removed by the call, documentation status, the reexports table, reexport_excluded symbols, and whether an interrupted update was recovered. Recovery details include any directory used to preserve unknown user content and the sibling-journal reconciliation plan.

Details

The function performs the following steps:

Creates the basic R package structure (R, man, vignettes, etc.).
Detects dependencies between packages, both explicit (from DESCRIPTION) and possible implicit uses (found by scanning executable source tokens). The latter are reported for diagnosis and are not hard dependencies unless explicitly supplied through additional_deps or force_deps.
Generates DESCRIPTION and NAMESPACE with the appropriate dependencies.
Creates a basic vignette documenting the meta-package.
Generates R files with functions to install and load the component packages:
- <name>_install(): installs the component packages from the local archives.
- <name>_attach(): attaches the components that are already installed.
- <name>_detach(): detaches all the meta-package's components.
- <name>_packages(): lists the included packages.

Installation is explicit: calling library(<meta>) attaches the components that are already installed and reports which ones are missing, but does not install anything or delete any files. To install the components from the local archives, the user calls <meta>_install(). Installation resolves dependencies with a graph-based topological ordering that also detects circular dependencies.

Generation validates every supplied component and its dependency graph eagerly before writing the metapackage. This hard validation protects an artifact that will be distributed to another machine. The installer is more tolerant: when an already installed component does not need to be changed, it can retain that installation without reading an archive that will not be used.

Validation strictness

During generation, validations that protect the recipient cannot be disabled: malformed or unsafe archives, invalid component metadata, duplicate components, cycles, and unsatisfied local version constraints remain hard errors. Checks about project tidiness can be relaxed individually through tolerate; there is no switch that disables validation as a whole. bigbang does not run R CMD check on component packages, so component warnings and notes do not prevent generation. Component source directories are built in a temporary directory with the optional pkgbuild package; passing an already built archive avoids that optional dependency.

Component installation

The generated meta-package installs component packages only when the user explicitly calls <meta>_install(). Loading it with library() never installs packages. By default, the generated installer does not access a repository.

With include_archives = TRUE, the default, the component archives travel inside the generated meta-package and pkg_dir defaults to system.file("archives", package = "<meta>"). That default is resolved when the installer is called, so it points at the library of whoever installed the meta-package: recipients need nothing beyond the meta-package itself, and no path has to be agreed on between machines. Network access is needed only when a component depends on a package that must come from a repository, which happens exclusively under cran_deps = "install".

Loading the generated meta-package attaches installed components, so their exported functions can be called directly or through component::function(). With reexport = TRUE, explicit component exports are instead exposed through read-only active bindings in the meta-package namespace. This does not add components to Imports or Depends: loading remains possible without them, and a binding resolves the component on every access. Evaluating a binding never throws: if a component is absent, cannot be loaded, or is an older installation that no longer exports the symbol, it returns a callable placeholder. Calling it reports the component, installed version, missing export, and the <name>_install() call that repairs the installation. This also keeps namespace inspection safe. Only explicit export() directives are rebound; S4 classes and methods are used through the loaded component namespace. An object restored with readRDS() cannot load a component by itself, so base R cannot dispatch that component's S3 method until the component has been loaded.

Re-export collisions

When more than one component exports a symbol, reexport_prefer chooses its provider explicitly and reexport_exclude removes it from the generated namespace. Every collision requires one of those options because static source analysis cannot prove that two exported objects are the same at runtime. The analysis remains as a diagnostic with probable_same_object, distinct_definitions, or undetermined, including ordered file, line, import, and parse reasons. For a preferred probable_same_object, <name>_install() verifies the installed owners in a clean R subprocess whose destination library is first in .libPaths(). If that subprocess cannot run, the result is explicitly unverified and never reports a false identity. A namespace already loaded from another library is reported before the clean verification starts. Missing owners remain unverified and the verification is retained in the returned result. The diagnostic is a help, not the guarantee: the guarantee is the explicit reexport_prefer or reexport_exclude decision plus that verification. Calling library(<meta>) alone does not verify installed owners. The scanner is deliberately conservative and can count a never-forced delayedAssign, an if (FALSE) branch, or a reg.finalizer() body; this overcount does not weaken the explicit decision and installation-verification guarantee. <name>_conflicts() repeats that check on request. Its masking-conflict names remain ordinary symbols; use <name>_reexport_verification(conflicts) to access the verification attribute without a name collision. If on_component_error = "skip" omits a component required by a preferred binding or an import source, generation errors with an actionable skipped condition instead of creating a binding to a component that will not travel with the metapackage. With reexport = TRUE, <name>_conflicts() retains the masking-conflict list from earlier releases and stores its installed-owner table as an attribute. The accessor keeps the same <name>_reexport_verification class when it has zero rows.

Interrupted updates

Before an in-place update mutates the project, bigbang assembles a durable journal beside it in a private .<name>.bigbang-update.armando-* folder. The marker is written before the backup, and the complete folder is renamed to .<name>.bigbang-update only after every hash has been verified. Every later file write or removal records its intention first. Generated files, shipped component archives, catalogs, .Rbuildignore, and the final manifest are replaced atomically. On Windows the guarantee is that a file is old, new, or temporarily absent with a journal backup. Roxygen runs in a staging copy and only its known outputs are promoted atomically to the project.

Updates also publish .<name>.bigbang-update.lock atomically from a sibling temporary folder that already contains a complete owner.rds. A published lock therefore always has an owner. Reclaiming an orphan first atomically renames it to a unique discarded name; only the process that wins that rename may publish a replacement, and it rechecks the owner before doing so. Lock disposition is owner-first. For the published lock, a proven live owner blocks every caller; an uncertain owner blocks without recover = TRUE and is reclaimable only with recover = TRUE; a proven dead owner is reclaimable. For a discarded lock, a proven live owner.rds is restored when the lock name is free or blocks on its PID when it is occupied. It is never deleted. An uncertain discarded owner follows the uncertain-lock rule. Only after the discarded owner is proven dead does the claimant decide the outcome: a live claimant blocks, an uncertain claimant needs recover = TRUE, and a dead claimant may be discarded. owner.rds and claim.rds are removed only when their bytes still have the digest observed for that decision; mismatches are preserved by setting the entry aside. No claim is written before the owner has been re-read immediately before publication. The update also revalidates its published owner before creating the journal, recording each intent, and completing an irreversible step. If the owner changed, it aborts before the next mutation. A discarded entry can therefore contain a claimant record, but that record is never allowed to override a live owner. For a .lock.armando-* entry, a live owner stays in place and blocks; an uncertain owner stays in place without recover = TRUE and is set aside with recover = TRUE; a dead or missing owner is set aside. A symbolic link at the published lock name is reported as a link without an update-running claim; with recover = TRUE the link itself is renamed aside and its target is not followed. A regular file or other user entry at the lock name is atomically set aside as .<name>.bigbang-apartado-*. Lock preparations left by an interruption are recognized on the next call and set aside without deleting their bytes. These names are reserved bigbang siblings: .<name>.bigbang-update, .<name>.bigbang-update.armando-*, .<name>.bigbang-update.lock, .<name>.bigbang-update.lock.armando-*, .<name>.bigbang-update.lock.descartado-*, .<name>.bigbang-update.descartado-*, and .<name>.bigbang-apartado-*.

If a process dies while preparing the journal, an empty unmarked armando-* folder is removed; any non-empty unmarked folder is atomically set aside as .<name>.bigbang-apartado-* without copying or deleting bytes. The initial marker records the owner PID, host, process start token, and start time before the first backup copy. On Linux, liveness reads /proc/<pid> and treats a missing process as dead, Z or X in /proc/<pid>/stat as dead, and any other readable state as existing; the process-start token still decides identity. Without /proc, kill(pid, 0) proves existence only when it succeeds; if that probe is unavailable, LC_ALL=C ps -p <pid> establishes whether the PID is present or absent, and ps -o lstart= -p <pid> supplies the portable start token. The token source is stored (proc or ps) and mismatched sources never compare equal. A failure is dead only when ps -p also proves that the PID is absent; permission errors, an unavailable ps, and an unreadable token are uncertain. The exact policy is: dead means the process does not exist or is Z/X; alive means it exists, is not terminal, and its start token matches; live-token-conflict means it exists but the token differs; uncertain means existence or identity cannot be proved. recover = TRUE may claim or set aside uncertain entries, but never overrides a proven live owner. A process of another user is therefore never inferred dead from EPERM. Journal disposal first writes an atomic tombstone with the exact relative-path and MD5 inventory of the entries bigbang wrote, then renames the folder to .<name>.bigbang-update.descartado-*; cleanup can therefore resume after another interruption. Cleanup checks every file recursively and removes it only when its relative path and MD5 match the inventory; it removes an inventory directory only after it is empty. Before destructive cleanup the journal is renamed to an unpredictable private sibling after verifying it is not a link, and each deletion revalidates its ancestors and MD5 immediately before unlink(). Any file, directory, or symbolic link that cannot be proved to be in the inventory causes the whole discarded folder to be set aside atomically and reported, so the update continues without deleting user bytes. The tombstone has a digest recorded beside it before the rename; a missing or changed digest is set aside rather than trusted. A discarded folder without a valid tombstone is set aside when non-empty; an empty one is removed as an interrupted cleanup shell. A matching name and manifest are required before a discarded folder is cleaned. A stale generation or another project is therefore set aside beside the current project and never blocks a later update. A file with the same path and MD5 as the inventory is an unavoidable limit: its bytes are identical, so deleting it loses no content, but the journal cannot prove who created it. The tombstone and its digest are local journal state, not a cryptographic signature; treat the journal as bigbang's private territory. A process of the same user with write permission can forge owner.rds, marker.rds, or state.rds; that is outside this integrity model. R has no unlinkat()/O_NOFOLLOW, so a same-user process that actively replaces journal directories during discard remains an integrity boundary; the remaining race is the interval between the last revalidation and unlink(). As a cheap consistency check, an armed journal is recoverable only when the owner fields in state.rds match those in marker.rds; otherwise the journal is set aside and is never used for rollback.

The journal is designed to survive process interruptions such as SIGKILL, an R error, or Ctrl-C. It does not promise fsync durability against an OS or power shutdown. The next create_metapackage(update = TRUE) call examines it before validating the generation manifest. The marker identifies the metapackage and old-manifest hash rather than an absolute path, so moving the project together with its journal remains recoverable. Renaming a project is not supported: generated file names contain the metapackage name. Rename the project and its journal back to <name> before updating. A byte-for-byte copy placed at the same path and name as the moved original is indistinguishable from that original; the journal consequently treats it as the project. If the original project still exists beside a copied journal, the journal is not adopted or changed. A partial tombstone temporary is set aside after the owner is confirmed dead, and recovery continues. An already completed update is recognized by its new manifest; otherwise a dead owner's changes are rolled back and the requested update continues. On POSIX systems liveness uses the PID and, where Linux /proc exposes it, the process start time. Windows is never probed with the process-termination helper because that operation terminates a process. A dry run evaluates and reports the lock as free, live, orphaned, or uncertain without acquiring, reclaiming, renaming, or deleting any lock entry.

Automatic recovery proceeds only when every affected path contains its original bytes, intended bytes, or an expected absence. Other content raises bigbang_error_interrupted_update; recover = TRUE preserves it outside the project before rollback. Recovery is idempotent, so another interruption can be recovered by a later call. dry_run = TRUE reports the pending action and leaves the project and every sibling journal folder untouched. A handled error uses this same journal for immediate rollback and retains it if verification cannot finish. Documentation generation failures in the staging copy are warnings; a failure while promoting any documentation output aborts the update and rolls the complete project back through the journal.

Requirements

Each component must be an existing archive path or a stem resolvable in one of the optional pkg_dir directories; ext is only a fallback for stems.
Files in the supplied archive directories that cannot be read are excluded from the inventory with a warning. A requested component still fails validation, while an unreadable file matching a declared dependency is reported as an unavailable local archive.
Automatic documentation (document = TRUE) requires the devtools package.

Examples

archives <- system.file("extdata", package = "bigbang")
destination <- tempfile("bigbang-example-")
dir.create(destination)

result <- create_metapackage(
  name = "toyverse",
  packages = "toycomponent_0.1.0",
  pkg_dir = archives,
  dest_dir = destination,
  document = FALSE,
  verbose = FALSE,
  import_deps = character(),
  force_deps = character()
)
list.files(result$path)
#>  [1] "DESCRIPTION"    "LICENSE"        "NAMESPACE"      "R"             
#>  [5] "README.md"      "inst"           "man"            "po"            
#>  [9] "tests"          "toyverse.Rproj" "vignettes"     

unlink(destination, recursive = TRUE)