1erlc(1) User Commands erlc(1)
2
6 erlc - Compiler
7
9 The erlc program provides a common way to run all compilers in the Er‐
10 lang system. Depending on the extension of each input file, erlc in‐
11 vokes the appropriate compiler. Regardless of which compiler is used,
12 the same flags are used to provide parameters, such as include paths
13 and output directory.
14 The current working directory, ".", is not included in the code path
16 when running the compiler. This is to avoid loading Beam files from the
17 current working directory that could potentially be in conflict with
18 the compiler or the Erlang/OTP system used by the compiler.
19
21 erlc flags file1.ext file2.ext...
22 Compiles one or more files. The files must include the exten‐
24 sion, for example, .erl for Erlang source code, or .yrl for Yecc
25 source code. Erlc uses the extension to invoke the correct com‐
26 piler.
27
29 The following flags are supported:
30 -I <Directory>:
32 Instructs the compiler to search for include files in the Direc‐
33 tory. When encountering an -include or -include_lib directive, the
34 compiler searches for header files in the following directories:
35 * ".", the current working directory of the file server
37 * The base name of the compiled file
39 * The directories specified using option -I; the directory speci‐
41 fied last is searched first
42 -o <Directory>:
44 The directory where the compiler is to place the output files. De‐
45 faults to the current working directory.
46 -D<Name>:
48 Defines a macro.
49 -D<Name>=<Value>:
51 Defines a macro with the specified value. The value can be any Er‐
52 lang term. Depending on the platform, the value may need to be
53 quoted if the shell itself interprets certain characters. On Unix,
54 terms containing tuples and lists must be quoted. Terms containing
55 spaces must be quoted on all platforms.
56 -WError:
58 Makes all warnings into errors.
59 -W<Number>:
61 Sets warning level to Number. Defaults to 1. To turn off warnings,
62 use -W0.
63 -W:
65 Same as -W1. Default.
66 -v:
68 Enables verbose output.
69 -b <Output_type>:
71 Specifies the type of output file. Output_type is the same as the
72 file extension of the output file, but without the period. This op‐
73 tion is ignored by compilers that have a single output format.
74 -no-server:
76 Do not use the compile server.
77 -server:
79 Use the compile server.
80 -enable-feature <Feature>:
82 Enables the feature feature during compilation. The special feature
83 all can be used to enable all features.
84 -disable-feature <feature>:
86 Disables the feature feature during compilation. The special fea‐
87 ture all can be used to disable all non permanent features.
88 -list-features:
90 List short descriptions of the current configurable features. Non
91 configurable features, i.e., those with a status of rejected or
92 permanent will not be shown.
93 -describe-feature <feature>:
95 Show long description and history of feature feature.
96 -M:
98 Produces a Makefile rule to track header dependencies. The rule is
99 sent to stdout. No object file is produced.
100 -MMD:
102 Generate dependencies as a side-effect. The object file will be
103 produced as normal. This option overrides the option -M.
104 -MF <Makefile>:
106 As option -M, except that the Makefile is written to Makefile. No
107 object file is produced.
108 -MD:
110 Same as -M -MF <File>.Pbeam.
111 -MT <Target>:
113 In conjunction with option -M or -MF, changes the name of the rule
114 emitted to Target.
115 -MQ <Target>:
117 As option -MT, except that characters special to make/1 are quoted.
118 -MP:
120 In conjunction with option -M or -MF, adds a phony target for each
121 dependency.
122 -MG:
124 In conjunction with option -M or -MF, considers missing headers as
125 generated files and adds them to the dependencies.
126 --:
128 Signals that no more options will follow. The rest of the arguments
129 is treated as filenames, even if they start with hyphens.
130 +<Term>:
132 A flag starting with a plus (+) rather than a hyphen is converted
133 to an Erlang term and passed unchanged to the compiler. For exam‐
134 ple, option export_all for the Erlang compiler can be specified as
135 follows:
136 erlc +export_all file.erl
138 Depending on the platform, the value may need to be quoted if the
140 shell itself interprets certain characters. On Unix, terms contain‐
141 ing tuples and lists must be quoted. Terms containing spaces must
142 be quoted on all platforms.
143
145 The following flags are useful in special situations, such as rebuild‐
146 ing the OTP system:
147 -pa <Directory>:
149 Appends Directory to the front of the code path in the invoked Er‐
150 lang emulator. This can be used to invoke another compiler than the
151 default one.
152 -pz <Directory>:
154 Appends Directory to the code path in the invoked Erlang emulator.
155
157 The following compilers are supported:
158 .erl:
160 Erlang source code. It generates a .beam file.
161 Options -P, -E, and -S are equivalent to +'P', +'E', and +'S', ex‐
163 cept that it is not necessary to include the single quotes to pro‐
164 tect them from the shell.
165 Supported options: -I, -o, -D, -v, -W, -b.
167 .S:
169 Erlang assembler source code. It generates a .beam file.
170 Supported options: same as for .erl.
172 .core:
174 Erlang core source code. It generates a .beam file.
175 Supported options: same as for .erl.
177 .yrl:
179 Yecc source code. It generates an .erl file.
180 Use option -I with the name of a file to use that file as a custom‐
182 ized prologue file (option includefile).
183 Supported options: -o, -v, -I, -W.
185 .mib:
187 MIB for SNMP. It generates a .bin file.
188 Supported options: -I, -o, -W.
190 .bin:
192 A compiled MIB for SNMP. It generates a .hrl file.
193 Supported options: -o, -v.
195 .rel:
197 Script file. It generates a boot file.
198 Use option -I to name directories to be searched for application
200 files (equivalent to the path in the option list for sys‐
201 tools:make_script/2).
202 Supported option: -o.
204 .asn1:
206 ASN1 file. It creates an .erl, .hrl, and .asn1db file from an .asn1
207 file. Also compiles the .erl using the Erlang compiler unless op‐
208 tion +noobj is specified.
209 Supported options: -I, -o, -b, -W.
211 .idl:
213 IC file. It runs the IDL compiler.
214 Supported options: -I, -o.
216
218 The compile server can be used to potentially speed up the build of
219 multi-file projects by avoiding to start an Erlang system for each file
220 to compile. Whether it will speed up the build depends on the nature of
221 the project and the build machine.
222 By default, the compile server is not used. It can be enabled by giving
224 erlc the option -server or by setting the environment variable
225 ERLC_USE_SERVER to yes or true.
226 When the compile server is enabled, erlc will automatically use the
228 server if it is started and start the server if has not already
229 started. The server will terminate itself when it has been idle for
230 some number of seconds.
231 erlc and the compile server communicate using the Erlang distribution.
233 The compile server is started as a hidden node, with a name that in‐
234 cludes the current user. Thus, each user on a computer has their own
235 compile server.
236 Using the compile server does not always speed up the build, as the
238 compile server sometimes must be restarted to ensure correctness. Here
239 are some examples of situations that force a restart:
240 * erlc wants to use a different version of Erlang than the compile
242 server is using.
243 * erlc wants to use different options for erl than the compile server
245 was started with. (A change to code path using the option -pa could
246 cause different parse transforms to be loaded. To be safe, the com‐
247 pile server will be restarted when any erl option is changed.)
248 * If the current working directory for erlc is different from the
250 working directory active when the compile server was started, and
251 if the compile server has active jobs, it will be restarted as soon
252 as those jobs have finished. (Build systems that build files ran‐
253 domly across multiple directories in parallel will probably not
254 benefit from the compile server.)
255
257 ERLC_EMULATOR:
258 The command for starting the emulator. Defaults to erl in the same
259 directory as the erlc program itself, or, if it does not exist, erl
260 in any of the directories specified in environment variable PATH.
261 ERLC_USE_SERVER:
263 Allowed values are yes or true to use the compile server, and no or
264 false to not use the compile server. If other values are given,
265 erlc will print a warning message and continue.
266 ERLC_SERVER_ID:
268 Tells erlc to identify the compile server by the given name, allow‐
269 ing a single user to run multiple unrelated builds in parallel
270 without them affecting each other, which can be useful for shared
271 build machines and the like. The name must be alphanumeric, and it
272 defaults to being empty.
273
275 erl(1), compile(3), yecc(3), snmp(3)
276Ericsson AB erts 13.2.2.4 erlc(1)