Title

whereis -- maintains a directory of external programs
and ancillary files and folders

Syntax

whereis [name [location]]

Description

This command may be called to get or set the location of an external program,
or an ancillary file or folder that may be used by a Stata command or program.

Arguments

name specifies the name of the resource.
This should be a single word conforming to Stata conventions for names.
For example pandoc.

location is used when registering a resource and should be a full path
specifying the location of the file or folder. This must conform to Stata
conventions for file or folder names, see filename.
In particular, the path should be enclosed in quotes if it contains spaces.
For example the location of pandoc may be
"c:\program files (x86)\pandoc\pandoc.exe".

Output

The whereis command displays the location as specified or retrieved and
stores it in a macro called r(name) using the name of the resource.
For example a call to whereis pandoc will return the location in the macro
r(pandoc).

If called with no arguments the command simply lists all the
resources registered with whereis.

Notes

The whereis command uses a text file to maintain a list of
resource names and locations. This file is called whereis.dir
and will be created in the ado path when first used.
(Type adopath to display the ado-file path in your system.)

Tips For Users

Users who install external programs that will then be registered with
whereis need to make a note of the location of the executable.
If you are not sure where the program was installed, the operating
system may help locate it.

On Unix and Mac systems open a terminal window and use
the shell command which.
For example to find where pandoc is installed type in the terminal
window which pandoc.
On a Mac this may print /usr/local/bin/pandoc, but of course the
location may be different in your system.
Another Unix command you could try is whereis, after which
this Stata command is named.

On Windows system you can open a command prompt window and use the
equivalent command where. By default this will search the
user's path, but the /R option will search recursively starting at
a given folder. To search the entire C drive for pandoc.exe type
in a command window where /R c:\ pandoc.exe. On a Windows
system this may print c:\program files (x86)\pandoc\pandoc.exe,
but again the location in your system may be different.

In both cases, once you have located the program or resource file
use the Stata whereis command to register the location permanently.

Notes For Programmers

Programmers using whereis to retrieve the location of a resource
should allow for the possibility that the path includes spaces.
For example to execute pandoc one could code

. whereis pandoc

. shell "`r(pandoc)'" arguments

Some programmers ask users to store resource locations using global
macros defined in the user's profile.do file.
The whereis command has the advantage of running on demand
and checking that the file or folder is in fact at the specified location,
both when storing and retrieving the resource location.

Acknowledgement

Diana Goldemberg suggested using whereis to store folders as well as files
and indicated how to modify the code to enable this extension.

Author

Germán Rodríguez <grodri@princeton.edu>
data.princeton.edu/stata/whereis.