*! version 1.3.1 19sep2023

Title

require -- Ensure that installed packages have a minimum or exact version.

(View PDF article)

Syntax

Require that a package is installed with a minimum or exact version:

require package [>= | ==] version
[,
install
from(location)
adopath(dirname)
dev_options]

Require that a package is installed without inspecting version:

require package
[,
install
from(location)
adopath(dirname)
dev_options]

Require multiple packages through a requirements file:

require using requirements.txt
[,
install
adopath(dirname)]

Create requirements file from currently installed packages:

require [using requirements.txt] ,
list [adopath(dirname)
create_options]

Main
install install package if not present or if version requirements are not met

from(location) location of the installable package; either a URL, a directory, or "SSC" (default)

adopath(dirname) use alternative directory when searching/installing packages. Also accepts keywords "PLUS" , "SITE", and "PERSONAL". Default is to search c(adopath) and install into what "net query" specifies.

Listing requirements or creating requirements file
* list list/create requirements instead of enforcing them

save alternative to using; saves requirements file with default filename (requirements.txt)

replace replace using file if it already exists

exact use exact requirements (==) instead of minimum (>=)

stata add a line requiring the currently-installed Stata version

Developer options
strict raise an error if the version string couldn't be parsed even when not checking versions

verbose show each regex attempt

debug(str) instead of parsing the file, treat the provided string as the starbang line

* list is required when creating requirement files.

Description

Use require to help the reproductibility of your research,
by ensuring that people that run your code are using compatible versions of the packages you use
(either minimum versions, of exact versions).

This is useful in these four settings:

1. To avoid problems if e.g. your coauthors have older versions of regression commands (rdrobust, reghdfe, ivreg2, etc.).
This is important because newer versions of these commands might change the results (either point estimates or standard errors).

2. To ensure journal data editors can reproduce your code.

3. To ensure other researchers can reproduce your code.

4. If you are writing programs, to ensure your dependencies are met.

require tries to convert user-created versions into semvers (semantic versions).
Thus, "version 1" becomes "version 1.0.0", indicating the major version, minor version, and patch version.

Options

Main

install Will install if package does not exist or version requirements are not met. By default installs from SSC.

from(location) Alternative installation path.

Examples

Ensure that the the last major versions of reghdfe and ftools are installed:

require reghdfe>=6.0

require ftools>=2.47

You can also use require with a text file.
This is very useful for projects with multiple do-files and dependencies.
First, you should create a text file such as:

requirements.txt

reghdfe>=6

ftools>=2.47

something>=1, from(someurl)

Then, at the beginning of every do-file:

require using requirements.txt, install

To facilitate using a requirements file, you can display the currently installed packages
with:

require, list

And can also save this list to a file with:

require using requirements.txt, list

Stored results

require stores the following in s():

Macros
s(package) name of package

s(version) version string "x.y.z" (equivalent to major.minor.patch in semantic versioning)

s(version_major) major version "x"

s(version_minor) sub version "y"

s(version_patch) patch version "z"

s(version_date) version date, if available, in the %td format (e.g. "31dec2022")

s(filename) filename used to determine version (typically an .ado file)

s(raw_line) starbang line used to determine version

Authors

Sergio Correia

Board of Governors of the Federal Reserve

Email: sergio.correia@gmail.com

Matthew P. Seay

Board of Governors of the Federal Reserve

Email: matt.seay@frb.gov

Support and updates

Links to online documentation & code:

- PDF article for more examples and in-depth explanations

- Github page for the code repository, to report issues, etc.

Acknowledgements

We thank Sebastian Kranz for helping us access the Stata code contained in the replication packages published by the American Economic Association journals,
the Review of Economic Studies, and the Review of Economics and Statistics.

We are also grateful to Paulo Guimarães, Miklós Koren, Julian Reif, Luis Eduardo San Martin, Lars Vilhuber, and seminar participants at the 2023 Stata Conference for their valuable suggestions.