Includes

There are two directives which can be used in Erlang source files to cause the compiler to temporarily read input from another source. They are typically used to provide macro definitions and record definitions from header files. It is recommended to use the file name extension ".hrl" for files which are meant to be included (the 'h' can be read as "header").

When locating header files a list of directory names, the compiler include path, is used. In short the list contains the current working directory of the file server, the base name of the compiled file, and the directories given by the include option, in that order. See erlc(1) and compile(3) for the details of the compiler include path.

The -include Directive

The first action taken by the -include directive is to check if the format of the first path component of the specified filename is $VAR, for some string VAR. If that is the case, the value of the environment variable VAR as returned by os:getenv(VAR) is substituted for the first path component. If os:getenv/1 returns false, the first path component is left as is. If the filename is absolute (possibly after variable substitution), the header file with that name is included. Otherwise, the specified header file is searched for in the directories in the compiler include path, starting with the first directory in the list. The first file found while traversing the list is included. Examples:


        -include("my_records.hrl").
        -include("incdir/more_records.hrl").
        -include("/home/users/proj/recs.hrl").
        -include("$PROJ_ROOT/app1/defs.hrl").

The -include_lib Directive

The -include_lib directive first tries to find the specified header file using the procedure employed for the -include directive. If no header file can be found by searching the compiler include path, the first path component of the specified filename (possibly after variable substitution) is regarded as the name of an application, and the directory of the current version of the application is searched. Example:


        -include_lib("mnesia/include/mnemosyne.hrl").

The compiler is instructed to look for the directory where the current version of the mnesia application is installed, that is code:lib_dir(mnesia), and then search the subdirectory include for the file mnemosyne.hrl.