---
title: "Install zot from source"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Install zot from source}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The product installer requires the development checkout containing `install/`.
The maintenance scripts described here are part of the package source under
`inst/` and run from the package root, the checkout's `lib/` directory.

The source repository is private. Obtain an authorized clone before running
these commands; the maintenance scripts do not clone repositories or configure
credentials. The R package source is the clone's `lib/` directory.

## Install a recorded package

The public entry is `install/install.sh` on macOS/Linux and
`install/install.ps1` on Windows. One operation installs the R package and the
`zot` command together; supply a selected tarball with its adjacent `.rds`
record to install that artifact instead of building `lib/`:

```sh
bash install/install.sh --library "/absolute/path/to/R/library" --prefix "/absolute/path/to/prefix" --tarball "/absolute/path/to/zot_<version>.tar.gz"
```

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File install/install.ps1 -Library "C:\path to\R library" -Prefix "C:\path to\prefix" -Tarball "C:\path to\zot_<version>.tar.gz"
```

These entries install the selected R package, its missing runtime dependencies
and the command. The prefix defaults to `/usr/local`, which is why the usual
invocation is `sudo bash install/install.sh`; choose a writable prefix to
install without privileges. There are no partial component modes. Keep the
selected library visible to subsequent R sessions. The operations below prepare
and check an artifact when starting from package source.

## Prepare and install from source

Install R and make `Rscript` available. Source builds may require compiler
tools and system libraries; building the manual requires LaTeX. These system
prerequisites are separate from R package dependencies.

Choose a writable R library and a new build directory outside `lib/`.
Replace every example path below with your chosen absolute path. Use the same
R library throughout: `R_LIBS_USER` makes it visible to each new R process.

In an R session started from `lib/` with the chosen library in `R_LIBS_USER`:

```r
source("inst/install.R")
installLibrary(path = ".", library = "/absolute/path/to/R/library",
               build = "/absolute/path/to/new-build-directory")
```

`installLibrary()` installs `pkgbuild`, `digest` and the package's `Depends`,
`Imports` and `LinkingTo` requirements into the selected library, builds the
package into the build directory and installs that tarball. The build writes
`zot_<version>.tar.gz` and an adjacent `.tar.gz.rds` record with its SHA-256;
keep the two together. To install an existing recorded tarball instead, pass
its path as `tarball` in place of `build`; its SHA-256 must match the record.

Installation verifies the installed version. It does not run release checks,
generate the website, or submit to CRAN.

After installation, R can load the package from any working directory. Keep
the chosen library in `R_LIBS_USER`, or add it in the R session:

```r
.libPaths(c("/absolute/path/to/R/library", .libPaths()))
library(zot)
```

## Documentation and checks are separate

For source maintenance, `inst/package.R` defines `installRequirements()`, which
prepares the tools and the package's development dependencies, including
Suggests, and `documentPackage()`, which regenerates the roxygen-owned package
documentation and checks spelling:

```r
source("inst/package.R")
installRequirements(path = ".", library = "/absolute/path/to/R/library",
                    packages = c("roxygen2", "spelling", "pkgbuild", "rcmdcheck", "digest"),
                    dependencies = TRUE)
documentPackage(path = ".", roxygen = TRUE)
```

Run `documentPackage()` before building when documentation changes are
intended, then review its source diff.

`Rscript inst/build.R OUTPUT_DIR`, from `lib/`, builds a recorded tarball
without installing it. `inst/cran-check.R` takes a recorded tarball, such as
the one `installLibrary()` built, and a new check directory. It runs the local
CRAN-style check and retains its logs and result in the artifact record. Run
it separately from installation:

```sh
cd "/absolute/path/to/zot/lib"
R_LIBS_USER="/absolute/path/to/R/library" Rscript inst/cran-check.R "/absolute/path/to/new-build-directory/zot_<version>.tar.gz" "/absolute/path/to/new-check-directory"
```

Errors and warnings fail the check; NOTEs require review. A successful local
check is neither a CRAN submission nor certification on other platforms.
`source("inst/cran-submit.R")`, from `lib/`, calls `devtools::submit_cran()`,
which builds its own tarball for the submission.

## Installed contents

`install/` contains the product installer; it is outside the package and is
not installed with `zot`. `lib/inst/` holds package runtime resources and the
maintenance scripts described above.
The installed R package does not depend on the sibling checkout directories.

The CLI is implemented. `install/install.sh` installs the `zot` command
under the prefix, alongside the R package: the command is a generated launcher
in `PREFIX/bin/` that resolves the system's current R and runs the payload in
`PREFIX/libexec/zot/`. The `zot` command line vignette documents its verbs.

The documentation website is built separately with pkgdown from `lib/`:
articles come from `lib/vignettes/` and the R reference from `lib/man/`. Installing the R
package does not publish GitHub Pages.