1compile(3) Erlang Module Definition compile(3)
2
6 compile - Erlang Compiler
7
9 This module provides an interface to the standard Erlang compiler. It
10 can generate either a new file, which contains the object code, or
11 return a binary, which can be loaded directly.
12
14 env_compiler_options()
15 Return compiler options given via the environment variable
17 ERL_COMPILER_OPTIONS. If the value is a list, it is returned as
18 is. If it is not a list, it is put into a list.
19 file(File)
21 Is the same as file(File, [verbose,report_errors,report_warn‐
23 ings]).
24 file(File, Options) -> CompRet
26 Types:
28 CompRet = ModRet | BinRet | ErrRet
30 ModRet = {ok,ModuleName} | {ok,ModuleName,Warnings}
31 BinRet = {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warn‐
32 ings}
33 ErrRet = error | {error,Errors,Warnings}
34 Compiles the code in the file File, which is an Erlang source
36 code file without the .erl extension. Options determine the
37 behavior of the compiler.
38 Returns {ok,ModuleName} if successful, or error if there are
40 errors. An object code file is created if the compilation suc‐
41 ceeds without errors. It is considered to be an error if the
42 module name in the source code is not the same as the basename
43 of the output file.
44 Available options:
46 basic_validation:
48 This option is a fast way to test whether a module will com‐
49 pile successfully. This is useful for code generators that
50 want to verify the code that they emit. No code is gener‐
51 ated. If warnings are enabled, warnings generated by the
52 erl_lint module (such as warnings for unused variables and
53 functions) are also returned.
54 Use option strong_validation to generate all warnings that
56 the compiler would generate.
57 strong_validation:
59 Similar to option basic_validation. No code is generated,
60 but more compiler passes are run to ensure that warnings
61 generated by the optimization passes are generated (such as
62 clauses that will not match, or expressions that are guaran‐
63 teed to fail with an exception at runtime).
64 binary:
66 The compiler returns the object code in a binary instead of
67 creating an object file. If successful, the compiler returns
68 {ok,ModuleName,Binary}.
69 bin_opt_info:
71 The compiler will emit informational warnings about binary
72 matching optimizations (both successful and unsuccessful).
73 For more information, see the section about bin_opt_info in
74 the Efficiency Guide.
75 compressed:
77 The compiler will compress the generated object code, which
78 can be useful for embedded systems.
79 debug_info:
81 Includes debug information in the form of Erlang Abstract
84 Format in the debug_info chunk of the compiled beam module.
85 Tools such as Debugger, Xref, and Cover require the debug
86 information to be included.
87 Warning: Source code can be reconstructed from the debug
89 information. Use encrypted debug information
90 (encrypt_debug_info) to prevent this.
91 For details, see beam_lib(3).
93 {debug_info, {Backend, Data}}:
95 Includes custom debug information in the form of a Backend
98 module with custom Data in the compiled beam module. The
99 given module must implement a debug_info/4 function and is
100 responsible for generating different code representations,
101 as described in the debug_info under beam_lib(3).
102 Warning: Source code can be reconstructed from the debug
104 information. Use encrypted debug information
105 (encrypt_debug_info) to prevent this.
106 {debug_info_key,KeyString}:
108 {debug_info_key,{Mode,KeyString}}:
111 Includes debug information, but encrypts it so that it can‐
114 not be accessed without supplying the key. (To give option
115 debug_info as well is allowed, but not necessary.) Using
116 this option is a good way to always have the debug informa‐
117 tion available during testing, yet protecting the source
118 code.
119 Mode is the type of crypto algorithm to be used for encrypt‐
121 ing the debug information. The default (and currently the
122 only) type is des3_cbc.
123 For details, see beam_lib(3).
125 encrypt_debug_info:
127 Similar to the debug_info_key option, but the key is read
130 from an .erlang.crypt file.
131 For details, see beam_lib(3).
133 deterministic:
135 Omit the options and source tuples in the list returned by
136 Module:module_info(compile). This option will make it easier
137 to achieve reproducible builds.
138 makedep:
140 Produces a Makefile rule to track headers dependencies. No
141 object file is produced.
142 By default, this rule is written to <File>.Pbeam. However,
144 if option binary is set, nothing is written and the rule is
145 returned in Binary.
146 For example, if you have the following module:
148 -module(module).
150 -include_lib("eunit/include/eunit.hrl").
152 -include("header.hrl").
153 The Makefile rule generated by this option looks as follows:
155 module.beam: module.erl \
157 /usr/local/lib/erlang/lib/eunit/include/eunit.hrl \
158 header.hrl
159 {makedep_output, Output}:
161 Writes generated rules to Output instead of the default
162 <File>.Pbeam. Output can be a filename or an io_device(). To
163 write to stdout, use standard_io. However, if binary is set,
164 nothing is written to Output and the result is returned to
165 the caller with {ok, ModuleName, Binary}.
166 {makedep_target, Target}:
168 Changes the name of the rule emitted to Target.
169 makedep_quote_target:
171 Characters in Target special to make(1) are quoted.
172 makedep_add_missing:
174 Considers missing headers as generated files and adds them
175 to the dependencies.
176 makedep_phony:
178 Adds a phony target for each dependency.
179 'P':
181 Produces a listing of the parsed code, after preprocessing
182 and parse transforms, in the file <File>.P. No object file
183 is produced.
184 'E':
186 Produces a listing of the code, after all source code trans‐
187 formations have been performed, in the file <File>.E. No
188 object file is produced.
189 'S':
191 Produces a listing of the assembler code in the file
192 <File>.S. No object file is produced.
193 report_errors/report_warnings:
195 Causes errors/warnings to be printed as they occur.
196 report:
198 A short form for both report_errors and report_warnings.
199 return_errors:
201 If this flag is set, {error,ErrorList,WarningList} is
202 returned when there are errors.
203 return_warnings:
205 If this flag is set, an extra field, containing WarningList,
206 is added to the tuples returned on success.
207 warnings_as_errors:
209 Causes warnings to be treated as errors. This option is sup‐
210 ported since R13B04.
211 return:
213 A short form for both return_errors and return_warnings.
214 verbose:
216 Causes more verbose information from the compiler, describ‐
217 ing what it is doing.
218 {source,FileName}:
220 Sets the value of the source, as returned by mod‐
221 ule_info(compile).
222 {outdir,Dir}:
224 Sets a new directory for the object code. The current direc‐
225 tory is used for output, except when a directory has been
226 specified with this option.
227 export_all:
229 Causes all functions in the module to be exported.
230 {i,Dir}:
232 Adds Dir to the list of directories to be searched when
233 including a file. When encountering an -include or
234 -include_lib directive, the compiler searches for header
235 files in the following directories:
236 * ".", the current working directory of the file server
238 * The base name of the compiled file
240 * The directories specified using option i; the directory
242 specified last is searched first
243 {d,Macro}:
245 {d,Macro,Value}:
248 Defines a macro Macro to have the value Value. Macro is of
249 type atom, and Value can be any term. The default Value is
250 true.
251 {parse_transform,Module}:
253 Causes the parse transformation function Module:parse_trans‐
254 form/2 to be applied to the parsed code before the code is
255 checked for errors.
256 from_asm:
258 The input file is expected to be assembler code (default
259 file suffix ".S"). Notice that the format of assembler files
260 is not documented, and can change between releases.
261 from_core:
263 The input file is expected to be core code (default file
264 suffix ".core"). Notice that the format of core files is not
265 documented, and can change between releases.
266 no_strict_record_tests:
268 This option is not recommended.
269 By default, the generated code for operation
271 Record#record_tag.field verifies that the tuple Record has
272 the correct size for the record, and that the first element
273 is the tag record_tag. Use this option to omit the verifica‐
274 tion code.
275 no_error_module_mismatch:
277 Normally the compiler verifies that the module name given in
278 the source code is the same as the base name of the output
279 file and refuses to generate an output file if there is a
280 mismatch. If you have a good reason (or other reason) for
281 having a module name unrelated to the name of the output
282 file, this option disables that verification (there will not
283 even be a warning if there is a mismatch).
284 {no_auto_import,[{F,A}, ...]}:
286 Makes the function F/A no longer being auto-imported from
287 the erlang module, which resolves BIF name clashes. This
288 option must be used to resolve name clashes with BIFs auto-
289 imported before R14A, if it is needed to call the local
290 function with the same name as an auto-imported BIF without
291 module prefix.
292 Note:
294 As from R14A and forward, the compiler resolves calls without
295 module prefix to local or imported functions before trying
296 with auto-imported BIFs. If the BIF is to be called, use the
297 erlang module prefix in the call, not {no_auto_import,[{F,A},
298 ...]}.
299 If this option is written in the source code, as a -compile
302 directive, the syntax F/A can be used instead of {F,A}, for
303 example:
304 -compile({no_auto_import,[error/1]}).
306 no_auto_import:
308 Do not auto-import any functions from erlang module.
309 no_line_info:
311 Omits line number information to produce a slightly smaller
312 output file.
313 {extra_chunks, [{binary(), binary()}]}:
315 Pass extra chunks to be stored in the .beam file. The extra
316 chunks must be a list of tuples with a four byte binary as
317 chunk name followed by a binary with the chunk contents. See
318 beam_lib for more information.
319 If warnings are turned on (option report_warnings described ear‐
321 lier), the following options control what type of warnings that
322 are generated. Except from {warn_format,Verbosity}, the follow‐
323 ing options have two forms:
324 * A warn_xxx form, to turn on the warning.
326 * A nowarn_xxx form, to turn off the warning.
328 In the descriptions that follow, the form that is used to change
330 the default value are listed.
331 {warn_format, Verbosity}:
333 Causes warnings to be emitted for malformed format strings
334 as arguments to io:format and similar functions.
335 Verbosity selects the number of warnings:
337 * 0 = No warnings
339 * 1 = Warnings for invalid format strings and incorrect num‐
341 ber of arguments
342 * 2 = Warnings also when the validity cannot be checked, for
344 example, when the format string argument is a variable.
345 The default verbosity is 1. Verbosity 0 can also be selected
347 by option nowarn_format.
348 nowarn_bif_clash:
350 This option is removed, it generates a fatal error if used.
351 Warning:
353 As from beginning with R14A, the compiler no longer calls the
354 auto-imported BIF if the name clashes with a local or explic‐
355 itly imported function, and a call without explicit module
356 name is issued. Instead, the local or imported function is
357 called. Still accepting nowarn_bif_clash would make a module
358 calling functions clashing with auto-imported BIFs compile
359 with both the old and new compilers, but with completely dif‐
360 ferent semantics. This is why the option is removed.
361 The use of this option has always been discouraged. As from
363 R14A, it is an error to use it.
364 To resolve BIF clashes, use explicit module names or the
366 {no_auto_import,[F/A]} compiler directive.
367 {nowarn_bif_clash, FAs}:
370 This option is removed, it generates a fatal error if used.
371 Warning:
373 The use of this option has always been discouraged. As from
374 R14A, it is an error to use it.
375 To resolve BIF clashes, use explicit module names or the
377 {no_auto_import,[F/A]} compiler directive.
378 nowarn_export_all:
381 Turns off warnings for uses of the export_all option.
382 Default is to emit a warning if option export_all is also
383 given.
384 warn_export_vars:
386 Emits warnings for all implicitly exported variables
387 referred to after the primitives where they were first
388 defined. By default, the compiler only emits warnings for
389 exported variables referred to in a pattern.
390 nowarn_shadow_vars:
392 Turns off warnings for "fresh" variables in functional
393 objects or list comprehensions with the same name as some
394 already defined variable. Default is to emit warnings for
395 such variables.
396 nowarn_unused_function:
398 Turns off warnings for unused local functions. Default is to
399 emit warnings for all local functions that are not called
400 directly or indirectly by an exported function. The compiler
401 does not include unused local functions in the generated
402 beam file, but the warning is still useful to keep the
403 source code cleaner.
404 {nowarn_unused_function, FAs}:
406 Turns off warnings for unused local functions like
407 nowarn_unused_function does, but only for the mentioned
408 local functions. FAs is a tuple {Name,Arity} or a list of
409 such tuples.
410 nowarn_deprecated_function:
412 Turns off warnings for calls to deprecated functions.
413 Default is to emit warnings for every call to a function
414 known by the compiler to be deprecated. Notice that the com‐
415 piler does not know about attribute -deprecated(), but uses
416 an assembled list of deprecated functions in Erlang/OTP. To
417 do a more general check, the Xref tool can be used. See also
418 xref(3) and the function xref:m/1, also accessible through
419 the function c:xm/1.
420 {nowarn_deprecated_function, MFAs}:
422 Turns off warnings for calls to deprecated functions like
423 nowarn_deprecated_function does, but only for the mentioned
424 functions. MFAs is a tuple {Module,Name,Arity} or a list of
425 such tuples.
426 nowarn_deprecated_type:
428 Turns off warnings for use of deprecated types. Default is
429 to emit warnings for every use of a type known by the com‐
430 piler to be deprecated.
431 nowarn_obsolete_guard:
433 Turns off warnings for calls to old type testing BIFs, such
434 as pid/1 and list/1. See the Erlang Reference Manual for a
435 complete list of type testing BIFs and their old equiva‐
436 lents. Default is to emit warnings for calls to old type
437 testing BIFs.
438 warn_unused_import:
440 Emits warnings for unused imported functions. Default is to
441 emit no warnings for unused imported functions.
442 nowarn_unused_vars:
444 By default, warnings are emitted for unused variables,
445 except for variables beginning with an underscore ("Prolog
446 style warnings"). Use this option to turn off this kind of
447 warnings.
448 nowarn_unused_record:
450 Turns off warnings for unused record types. Default is to
451 emit warnings for unused locally defined record types.
452 nowarn_get_stacktrace:
454 Turns off warnings for using get_stacktrace/0 in a context
455 where it will probably not work in a future release. For
456 example, by default there will be a warning if get_stack‐
457 trace/0 is used following a catch expression.
458 Another class of warnings is generated by the compiler during
460 optimization and code generation. They warn about patterns that
461 will never match (such as a=b), guards that always evaluate to
462 false, and expressions that always fail (such as atom+42).
463 Those warnings cannot be disabled (except by disabling all warn‐
465 ings).
466 Note:
468 The compiler does not warn for expressions that it does not
469 attempt to optimize. For example, the compiler tries to evaluate
470 1/0, detects that it will cause an exception, and emits a warn‐
471 ing. However, the compiler is silent about the similar expres‐
472 sion, X/0, because of the variable in it. Thus, the compiler
473 does not even try to evaluate and therefore it emits no warn‐
474 ings.
475 Warning:
478 The absence of warnings does not mean that there are no remain‐
479 ing errors in the code.
480 Note:
483 All options, except the include path ({i,Dir}), can also be
484 given in the file with attribute -compile([Option,...]).
485 Attribute -compile() is allowed after the function definitions.
486 Note:
489 The options {nowarn_unused_function, FAs}, {nowarn_bif_clash,
490 FAs}, and {nowarn_deprecated_function, MFAs} are only recognized
491 when given in files. They are not affected by options
492 warn_unused_function, warn_bif_clash, or warn_deprecated_func‐
493 tion.
494 For debugging of the compiler, or for pure curiosity, the inter‐
497 mediate code generated by each compiler pass can be inspected.
498 To print a complete list of the options to produce list files,
499 type compile:options() at the Erlang shell prompt. The options
500 are printed in the order that the passes are executed. If more
501 than one listing option is used, the one representing the earli‐
502 est pass takes effect.
503 Unrecognized options are ignored.
505 Both WarningList and ErrorList have the following format:
507 [{FileName,[ErrorInfo]}].
509 ErrorInfo is described later in this section. The filename is
511 included here, as the compiler uses the Erlang pre-processor
512 epp, which allows the code to be included in other files. It is
513 therefore important to know to which file the line number of an
514 error or a warning refers.
515 forms(Forms)
517 Is the same as forms(Forms, [verbose,report_errors,report_warn‐
519 ings]).
520 forms(Forms, Options) -> CompRet
522 Types:
524 Forms = [Form]
526 CompRet = BinRet | ErrRet
527 BinRet = {ok,ModuleName,BinaryOrCode} | {ok,ModuleName,Bina‐
528 ryOrCode,Warnings}
529 BinaryOrCode = binary() | term()
530 ErrRet = error | {error,Errors,Warnings}
531 Analogous to file/1, but takes a list of forms (in the Erlang
533 abstract format representation) as first argument. Option binary
534 is implicit, that is, no object code file is produced. For
535 options that normally produce a listing file, such as 'E', the
536 internal format for that compiler pass (an Erlang term, usually
537 not a binary) is returned instead of a binary.
538 format_error(ErrorDescriptor) -> chars()
540 Types:
542 ErrorDescriptor = errordesc()
544 Uses an ErrorDescriptor and returns a deep list of characters
546 that describes the error. This function is usually called
547 implicitly when an ErrorInfo structure (described in section
548 Error Information) is processed.
549 output_generated(Options) -> true | false
551 Types:
553 Options = [term()]
555 Determines whether the compiler generates a beam file with the
557 given options. true means that a beam file is generated. false
558 means that the compiler generates some listing file, returns a
559 binary, or merely checks the syntax of the source code.
560 noenv_file(File, Options) -> CompRet
562 Works like file/2, except that the environment variable ERL_COM‐
564 PILER_OPTIONS is not consulted.
565 noenv_forms(Forms, Options) -> CompRet
567 Works like forms/2, except that the environment variable
569 ERL_COMPILER_OPTIONS is not consulted.
570 noenv_output_generated(Options) -> true | false
572 Types:
574 Options = [term()]
576 Works like output_generated/1, except that the environment vari‐
578 able ERL_COMPILER_OPTIONS is not consulted.
579
581 The (host operating system) environment variable ERL_COMPILER_OPTIONS
582 can be used to give default compiler options. Its value must be a valid
583 Erlang term. If the value is a list, it is used as is. If it is not a
584 list, it is put into a list.
585 The list is appended to any options given to file/2, forms/2, and out‐
587 put_generated/2. Use the alternative functions noenv_file/2,
588 noenv_forms/2, or noenv_output_generated/2 if you do not want the envi‐
589 ronment variable to be consulted, for example, if you are calling the
590 compiler recursively from inside a parse transform.
591 The list can be retrieved with env_compiler_options/0.
593
595 The compiler can do function inlining within an Erlang module. Inlining
596 means that a call to a function is replaced with the function body with
597 the arguments replaced with the actual values. The semantics are pre‐
598 served, except if exceptions are generated in the inlined code. Excep‐
599 tions are reported as occurring in the function the body was inlined
600 into. Also, function_clause exceptions are converted to similar
601 case_clause exceptions.
602 When a function is inlined, the original function is kept if it is
604 exported (either by an explicit export or if the option export_all was
605 given) or if not all calls to the function are inlined.
606 Inlining does not necessarily improve running time. For example, inlin‐
608 ing can increase Beam stack use, which probably is detrimental to per‐
609 formance for recursive functions.
610 Inlining is never default. It must be explicitly enabled with a com‐
612 piler option or a -compile() attribute in the source module.
613 To enable inlining, either use the option inline to let the compiler
615 decide which functions to inline, or {inline,[{Name,Arity},...]} to
616 have the compiler inline all calls to the given functions. If the
617 option is given inside a compile directive in an Erlang module,
618 {Name,Arity} can be written as Name/Arity.
619 Example of explicit inlining:
621 -compile({inline,[pi/0]}).
623 pi() -> 3.1416.
625 Example of implicit inlining:
628 -compile(inline).
630 The option {inline_size,Size} controls how large functions that are
632 allowed to be inlined. Default is 24, which keeps the size of the
633 inlined code roughly the same as the un-inlined version (only rela‐
634 tively small functions are inlined).
635 Example:
637 %% Aggressive inlining - will increase code size.
639 -compile(inline).
640 -compile({inline_size,100}).
641
643 The compiler can also inline various list manipulation functions from
644 the module list in STDLIB.
645 This feature must be explicitly enabled with a compiler option or a
647 -compile() attribute in the source module.
648 To enable inlining of list functions, use option inline_list_funcs.
650 The following functions are inlined:
652 * lists:all/2
654 * lists:any/2
656 * lists:foreach/2
658 * lists:map/2
660 * lists:flatmap/2
662 * lists:filter/2
664 * lists:foldl/3
666 * lists:foldr/3
668 * lists:mapfoldl/3
670 * lists:mapfoldr/3
672
674 Parse transformations are used when a programmer wants to use Erlang
675 syntax but with different semantics. The original Erlang code is then
676 transformed into other Erlang code.
677
679 The ErrorInfo mentioned earlier is the standard ErrorInfo structure,
680 which is returned from all I/O modules. It has the following format:
681 {ErrorLine, Module, ErrorDescriptor}
683 ErrorLine is the atom none if the error does not correspond to a spe‐
685 cific line, for example, if the source file does not exist.
686 A string describing the error is obtained with the following call:
688 Module:format_error(ErrorDescriptor)
690
692 epp(3), erl_id_trans(3), erl_lint(3), beam_lib(3)
693Ericsson AB compiler 7.1.5.2 compile(3)