1erlc(1)                          User Commands                         erlc(1)
2
3
4

NAME

6       erlc - Compiler
7

DESCRIPTION

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
15       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

EXPORTS

21       erlc flags file1.ext file2.ext...
22
23              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

GENERALLY USEFUL FLAGS

29       The following flags are supported:
30
31         -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
36           * ".", the current working directory of the file server
37
38           * The base name of the compiled file
39
40           * The  directories  specified using option -I; the directory speci‐
41             fied last is searched first
42
43         -o <Directory>:
44           The directory where the compiler is to place the output files.  De‐
45           faults to the current working directory.
46
47         -D<Name>:
48           Defines a macro.
49
50         -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
57         -WError:
58           Makes all warnings into errors.
59
60         -W<Number>:
61           Sets  warning level to Number. Defaults to 1. To turn off warnings,
62           use -W0.
63
64         -W:
65           Same as -W1. Default.
66
67         -v:
68           Enables verbose output.
69
70         -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
75         -no-server:
76           Do not use the compile server.
77
78         -server:
79           Use the compile server.
80
81         -enable-feature <Feature>:
82           Enables the feature feature during compilation. The special feature
83           all can be used to enable all features.
84
85         -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
89         -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
94         -describe-feature <feature>:
95           Show long description and history of feature feature.
96
97         -M:
98           Produces a Makefile rule to track header dependencies. The rule  is
99           sent to stdout. No object file is produced.
100
101         -MMD:
102           Generate  dependencies  as  a  side-effect. The object file will be
103           produced as normal. This option overrides the option -M.
104
105         -MF <Makefile>:
106           As option -M, except that the Makefile is written to  Makefile.  No
107           object file is produced.
108
109         -MD:
110           Same as -M -MF <File>.Pbeam.
111
112         -MT <Target>:
113           In  conjunction with option -M or -MF, changes the name of the rule
114           emitted to Target.
115
116         -MQ <Target>:
117           As option -MT, except that characters special to make/1 are quoted.
118
119         -MP:
120           In conjunction with option -M or -MF, adds a phony target for  each
121           dependency.
122
123         -MG:
124           In  conjunction with option -M or -MF, considers missing headers as
125           generated files and adds them to the dependencies.
126
127         --:
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
131         +<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
137         erlc +export_all file.erl
138
139           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

SPECIAL FLAGS

145       The  following flags are useful in special situations, such as rebuild‐
146       ing the OTP system:
147
148         -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
153         -pz <Directory>:
154           Appends Directory to the code path in the invoked Erlang emulator.
155

SUPPORTED COMPILERS

157       The following compilers are supported:
158
159         .erl:
160           Erlang source code. It generates a .beam file.
161
162           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
166           Supported options: -I, -o, -D, -v, -W, -b.
167
168         .S:
169           Erlang assembler source code. It generates a .beam file.
170
171           Supported options: same as for .erl.
172
173         .core:
174           Erlang core source code. It generates a .beam file.
175
176           Supported options: same as for .erl.
177
178         .yrl:
179           Yecc source code. It generates an .erl file.
180
181           Use option -I with the name of a file to use that file as a custom‐
182           ized prologue file (option includefile).
183
184           Supported options: -o, -v, -I, -W.
185
186         .mib:
187           MIB for SNMP. It generates a .bin file.
188
189           Supported options: -I, -o, -W.
190
191         .bin:
192           A compiled MIB for SNMP. It generates a .hrl file.
193
194           Supported options: -o, -v.
195
196         .rel:
197           Script file. It generates a boot file.
198
199           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
203           Supported option: -o.
204
205         .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
210           Supported options: -I, -o, -b, -W.
211
212         .idl:
213           IC file. It runs the IDL compiler.
214
215           Supported options: -I, -o.
216

COMPILE SERVER

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
223       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
227       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
232       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
237       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
241         * erlc wants to use a different version of Erlang  than  the  compile
242           server is using.
243
244         * 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
249         * 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

ENVIRONMENT VARIABLES

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
262         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
267         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

SEE ALSO

275       erl(1), compile(3), yecc(3), snmp(3)
276
277
278
279Ericsson AB                      erts 13.2.2.4                         erlc(1)
Impressum