Get Started

This guide covers the basics of builder: packages, directives, and macros.

Package

Builder reads R files from the srcr directory (default) and writes to the R directory (default).

./builder -input srcr -output R

This allows organising your R package source in nested directories:

srcr
├── main.R
└── utils
    └── helpers.R

Produces:

R
├── main.R
└── utils-helpers.R

Subdirectory paths are flattened with hyphens.

Directives

Builder supports C-like preprocessor directives.

Note: Lines starting with #> are treated as directives and removed from output. R comments (# comment) are preserved.

Define Constants

#> define VERSION 2

cat("Version:", VERSION)

Conditional Compilation

#> ifdef DEBUG
cat("Debug mode\n")
#> endif

Which you can build with builder -DDEBUG

Command Line Definitions

Pass definitions at build time:

./builder -input srcr -output R -DDEBUG -DVERSION 3

Command-line definitions override file-based #> define directives.

Macros

Macros are function-like directives with parameters.

#> macro
LOG <- function(level, msg) {
  cat("[", .level, "] ", .msg, "\n", sep = "")
}
#> endmacro

LOG("INFO", "Started")

Expands to:

cat("[", "INFO", "] ", "Started", "\n", sep = "")

Syntax

• Start with #> macro alone on a line (or #> macro local for local scope)
• Use standard R function syntax: NAME <- function(arg1, arg2, ...) { ... }
• Use .arg to substitute argument values
• End with #> endmacro

Usage

You can configure builder in two ways:

Config File

Create a builder.ini file in your project root:

input: srcr/
output: R/

Then simply run:

builder

See Configuration File for all options.

Build Scripts

Alternatively, place your builder call in a Makefile, build.R or build.sh script:

#!/usr/bin/env Rscript

system2("builder", c("-input", "srcr", "-output", "R"))
devtools::document()
devtools::check()

See the full documentation for more features.