1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>1999</year><year>2009</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>Includes</title>
<prepared>Arndt Jonasson</prepared>
<docno>1</docno>
<date>99-01-25</date>
<rev>PA1</rev>
<file>include.sgml</file>
</header>
<p>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 <c>".hrl"</c> for files which are meant to be
included (the 'h' can be read as "header").</p>
<p>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 <c>erlc(1)</c> and <c>compile(3)</c> for the details of the
compiler include path.</p>
<section>
<title>The -include Directive</title>
<p>The first action taken by the <c>-include</c> directive is to
check if the format of the first path component of the specified
filename is <c>$VAR</c>, for some string <c>VAR</c>. If that is the
case, the value of the environment variable <c>VAR</c> as returned by
<c>os:getenv(VAR)</c> is substituted for the first path component. If
<c>os:getenv/1</c> returns <c>false</c>, 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:</p>
<code type="none">
-include("my_records.hrl").
-include("incdir/more_records.hrl").
-include("/home/users/proj/recs.hrl").
-include("$PROJ_ROOT/app1/defs.hrl"). </code>
</section>
<section>
<title>The -include_lib Directive</title>
<p>The <c>-include_lib</c> directive first tries to find the
specified header file using the procedure employed for the
<c>-include</c> 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:</p>
<code type="none">
-include_lib("mnesia/include/mnemosyne.hrl"). </code>
<p>The compiler is instructed to look for the directory where the
current version of the <c>mnesia</c> application is installed, that is
<c>code:lib_dir(mnesia)</c>, and then search the subdirectory
<c>include</c> for the file <c>mnemosyne.hrl</c>.</p>
</section>
</chapter>
|
