Erlang: what is the difference between "include_lib" and "include"?

Question

What is the difference between "include_lib" and "include" ?

E.g.

-include_lib("eunit/include/eunit.hrl")

Answer 1

The way the documentation describes the difference between include and include_lib is:

include_lib is similar to include, but should not point out an absolute file. Instead, the first path component (possibly after variable substitution) is assumed to be the name of an application.

Example:

-include_lib("kernel/include/file.hrl").

The code server uses code:lib_dir(kernel) to find the directory of the current (latest) version of Kernel, and then the subdirectory include is searched for the file file.hrl.

So in your example, you dont need to point out the version of eunit that you include, you are including the latest eunit.hrl of the eunit:s that exists in your library path.

Answer 2

One difference which is not obvious at first is that -include and -include_lib use a different set of paths when looking for header files. -include_lib in fact uses the code path, not the header file path.

Hence, the flag erlc expects to add a path to the -include search path is -I; the flag for -include_lib is -pa/-pz.

Already mentioned is the fact that using -include_lib saves us from specifying (and therefore tying) the module to a specific library version.

Furthermore, there's a convention that internal headers are stored inside the src/ subdirectory of a project and included using -include. External headers (intended to be used by other libraries/projects) files are stored in include/ and included using -include_lib.