Package Structure — Understand package structure conceptually (intro)

The story of R packages is inseparable from the evolution of R itself as a language designed for statistical computing and data analysis. In the early days of S (R's predecessor at Bell Labs), statistical routines were shared informally — researchers passed around scripts, functions lived in personal libraries, and reproducibility depended on social convention rather than tooling. As the community grew, this ad-hoc approach became untenable: version conflicts emerged, dependencies were undocumented, and distributing code to collaborators required painstaking manual effort. The package system was the R Core Team's answer to this growing chaos, providing a standardized structure for bundling functions, documentation, data, and metadata into a single distributable unit.

The central question that package structure addresses is deceptively simple: how do you transform a collection of R functions, datasets, and documentation into something that another person (or your future self) can install, load, and rely upon with a single command? The answer is a well-defined directory layout and a set of metadata files that R's tooling can parse, validate, and build automatically. Understanding this structure conceptually — before writing a single line of package code — provides the mental model you need to navigate the ecosystem effectively.

An R package is not merely a folder of .R files. It is a formally structured unit of software governed by conventions that the R build system enforces. Several foundational principles undergird the design decisions behind this structure, and grasping them will make every subsequent detail click into place.

The canonical structure of an R package can be visualized as a directory tree. Every package contains a small set of mandatory components and a larger set of optional directories that provide additional capabilities. The following diagram illustrates the standard layout, color-coded by component type. Blue elements are mandatory for any valid R package; other colors represent optional but common components.

Notice the hierarchy in the diagram. At the top level sits the package root directory, whose name typically matches the package name declared in DESCRIPTION. Within this root, the three mandatory elements — DESCRIPTION, NAMESPACE, and R/ — form the minimal viable package. You could technically build and install a package with just these three, though any CRAN submission would also require documentation in man/. The optional directories each extend the package's capabilities: data/ bundles datasets that users can load with data(), tests/ holds automated test suites (commonly using the testthat framework), vignettes/ provides long-form tutorials in R Markdown, and src/ houses compiled source code for performance-critical routines written in C, C++, or Fortran.

Understanding the directory layout is only half the picture. Equally important is grasping how R's build system traverses this structure when you run commands like R CMD build, R CMD check, or R CMD INSTALL. The build pipeline is deterministic: it reads files in a specific order, validates them against expected formats, and produces either a source tarball or an installed package in your local library. If we think of the directory structure as a blueprint, the build system is the construction crew that follows it.

The Build Pipeline in Three Phases

During Phase 1 (Build), the system reads DESCRIPTION first to determine the package name, version, and which R files to include. It then parses NAMESPACE to understand export/import declarations, collates all .R files in the R/ directory (respecting the optional Collate field in DESCRIPTION if source-order dependencies exist), builds any vignettes, and compresses everything into a .tar.gz source tarball. Phase 2 (Check) is the quality gate: R CMD check unpacks the tarball and runs over 20 categories of validation — from verifying that every exported function has documentation to executing all code examples and test suites. CRAN requires zero errors and zero warnings before accepting a submission. Phase 3 (Install) byte-compiles the R source, compiles any C/C++/Fortran code in src/, and installs the finished package into a local library path, after which library(mypackage) makes it available in your R session.

Now that we have the high-level map, let us zoom into each component of the package structure and understand its role, format, and the conventions that govern it. The following table provides a comprehensive reference for every standard file and directory in an R package.

The DESCRIPTION File — A Closer Look

The DESCRIPTION file deserves special attention because it is the single most important metadata file in any package. Written in Debian Control File (DCF) format — a simple key-value syntax — it declares everything the build system and repository need to know about your package. The Imports field lists packages that your code uses and that must be installed; Suggests lists packages used only in tests, vignettes, or examples; and Depends (rarely used in modern packages) attaches packages to the user's search path. Understanding this tripartite dependency declaration is crucial because it directly affects how install.packages() resolves the dependency graph.

Let us walk through creating a minimal but valid R package from scratch. Our package, tempconv, will provide two functions for converting temperatures between Celsius and Fahrenheit. This example illustrates how each component of the package structure comes together.

R's package system is remarkably mature and well-integrated into the language, but it is not without tradeoffs. Understanding its strengths and limitations in context helps you make informed decisions about when to package your code versus when simpler alternatives (like sourced scripts or R projects) might suffice.

The conceptual understanding of package structure you have built in this lesson is the foundation upon which several advanced topics rest. As you progress, you will encounter more sophisticated uses of the package machinery — from compiled code integration to object-oriented systems and beyond. The table below maps each component of the basic structure to its advanced extensions.

It is worth emphasizing that the conceptual model does not change as you move into these advanced topics. The directory layout remains the same; you are simply populating it with more sophisticated contents. An Rcpp-based package still has DESCRIPTION, NAMESPACE, and R/ — it just also has src/ with C++ files and a LinkingTo: Rcpp declaration in DESCRIPTION. This is the power of a well-designed convention: it scales from a two-function utility package to a thousand-function computational library without structural changes.