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 re‐
11 turn a binary, which can be loaded directly.
12
14 option() = term()
15 See file/2 for detailed description
17
19 env_compiler_options()
20 Return compiler options given via the environment variable
22 ERL_COMPILER_OPTIONS. If the value is a list, it is returned as
23 is. If it is not a list, it is put into a list.
24 file(File)
26 Is the same as file(File, [verbose,report_errors,report_warn‐
28 ings]).
29 file(File, Options) -> CompRet
31 Types:
33 CompRet = ModRet | BinRet | ErrRet
35 ModRet = {ok,ModuleName} | {ok,ModuleName,Warnings}
36 BinRet = {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warn‐
37 ings}
38 ErrRet = error | {error,Errors,Warnings}
39 Compiles the code in the file File, which is an Erlang source
41 code file without the .erl extension. Options determine the be‐
42 havior of the compiler.
43 Returns {ok,ModuleName} if successful, or error if there are er‐
45 rors. An object code file is created if the compilation succeeds
46 without errors. It is considered to be an error if the module
47 name in the source code is not the same as the basename of the
48 output file.
49 Available options:
51 basic_validation:
53 This option is a fast way to test whether a module will com‐
54 pile successfully. This is useful for code generators that
55 want to verify the code that they emit. No code is gener‐
56 ated. If warnings are enabled, warnings generated by the
57 erl_lint module (such as warnings for unused variables and
58 functions) are also returned.
59 Use option strong_validation to generate all warnings that
61 the compiler would generate.
62 strong_validation:
64 Similar to option basic_validation. No code is generated,
65 but more compiler passes are run to ensure that warnings
66 generated by the optimization passes are generated (such as
67 clauses that will not match, or expressions that are guaran‐
68 teed to fail with an exception at runtime).
69 binary:
71 The compiler returns the object code in a binary instead of
72 creating an object file. If successful, the compiler returns
73 {ok,ModuleName,Binary}.
74 bin_opt_info:
76 The compiler will emit informational warnings about binary
77 matching optimizations (both successful and unsuccessful).
78 For more information, see the section about bin_opt_info in
79 the Efficiency Guide.
80 {compile_info, [{atom(), term()}]}:
82 Allows compilers built on top of compile to attach extra
83 compilation metadata to the compile_info chunk in the gener‐
84 ated beam file.
85 It is advised for compilers to remove all non-deterministic
87 information if the deterministic option is supported and it
88 was supplied by the user.
89 compressed:
91 The compiler will compress the generated object code, which
92 can be useful for embedded systems.
93 debug_info:
95 Includes debug information in the form of Erlang Abstract
98 Format in the debug_info chunk of the compiled beam module.
99 Tools such as Debugger, Xref, and Cover require the debug
100 information to be included.
101 Warning: Source code can be reconstructed from the debug in‐
103 formation. Use encrypted debug information (encrypt_de‐
104 bug_info) to prevent this.
105 For details, see beam_lib(3).
107 {debug_info, {Backend, Data}}:
109 Includes custom debug information in the form of a Backend
112 module with custom Data in the compiled beam module. The
113 given module must implement a debug_info/4 function and is
114 responsible for generating different code representations,
115 as described in the debug_info under beam_lib(3).
116 Warning: Source code can be reconstructed from the debug in‐
118 formation. Use encrypted debug information (encrypt_de‐
119 bug_info) to prevent this.
120 {debug_info_key,KeyString}:
122 {debug_info_key,{Mode,KeyString}}:
125 Includes debug information, but encrypts it so that it can‐
128 not be accessed without supplying the key. (To give option
129 debug_info as well is allowed, but not necessary.) Using
130 this option is a good way to always have the debug informa‐
131 tion available during testing, yet protecting the source
132 code.
133 Mode is the type of crypto algorithm to be used for encrypt‐
135 ing the debug information. The default (and currently the
136 only) type is des3_cbc.
137 For details, see beam_lib(3).
139 encrypt_debug_info:
141 Similar to the debug_info_key option, but the key is read
144 from an .erlang.crypt file.
145 For details, see beam_lib(3).
147 deterministic:
149 Omit the options and source tuples in the list returned by
150 Module:module_info(compile), and reduce the paths in stack
151 traces to the module name alone. This option will make it
152 easier to achieve reproducible builds.
153 makedep:
155 Produces a Makefile rule to track headers dependencies. No
156 object file is produced.
157 By default, this rule is written to <File>.Pbeam. However,
159 if option binary is set, nothing is written and the rule is
160 returned in Binary.
161 For example, if you have the following module:
163 -module(module).
165 -include_lib("eunit/include/eunit.hrl").
167 -include("header.hrl").
168 The Makefile rule generated by this option looks as follows:
170 module.beam: module.erl \
172 /usr/local/lib/erlang/lib/eunit/include/eunit.hrl \
173 header.hrl
174 makedep_side_effect:
176 The dependecies are created as a side effect to the normal
177 compilation process. This means that the object file will
178 also be produced. This option override the makedep option.
179 {makedep_output, Output}:
181 Writes generated rules to Output instead of the default
182 <File>.Pbeam. Output can be a filename or an io_device(). To
183 write to stdout, use standard_io. However, if binary is set,
184 nothing is written to Output and the result is returned to
185 the caller with {ok, ModuleName, Binary}.
186 {makedep_target, Target}:
188 Changes the name of the rule emitted to Target.
189 makedep_quote_target:
191 Characters in Target special to make(1) are quoted.
192 makedep_add_missing:
194 Considers missing headers as generated files and adds them
195 to the dependencies.
196 makedep_phony:
198 Adds a phony target for each dependency.
199 'P':
201 Produces a listing of the parsed code, after preprocessing
202 and parse transforms, in the file <File>.P. No object file
203 is produced.
204 'E':
206 Produces a listing of the code, after all source code trans‐
207 formations have been performed, in the file <File>.E. No ob‐
208 ject file is produced.
209 'S':
211 Produces a listing of the assembler code in the file
212 <File>.S. No object file is produced.
213 report_errors/report_warnings:
215 Causes errors/warnings to be printed as they occur.
216 report:
218 A short form for both report_errors and report_warnings.
219 return_errors:
221 If this flag is set, {error,ErrorList,WarningList} is re‐
222 turned when there are errors.
223 return_warnings:
225 If this flag is set, an extra field, containing WarningList,
226 is added to the tuples returned on success.
227 warnings_as_errors:
229 Causes warnings to be treated as errors. This option is sup‐
230 ported since R13B04.
231 return:
233 A short form for both return_errors and return_warnings.
234 verbose:
236 Causes more verbose information from the compiler, describ‐
237 ing what it is doing.
238 {source,FileName}:
240 Overrides the source file name as presented in mod‐
241 ule_info(compile) and stack traces.
242 {outdir,Dir}:
244 Sets a new directory for the object code. The current direc‐
245 tory is used for output, except when a directory has been
246 specified with this option.
247 export_all:
249 Causes all functions in the module to be exported.
250 {i,Dir}:
252 Adds Dir to the list of directories to be searched when in‐
253 cluding a file. When encountering an -include or -in‐
254 clude_lib directive, the compiler searches for header files
255 in the following directories:
256 * ".", the current working directory of the file server
258 * The base name of the compiled file
260 * The directories specified using option i; the directory
262 specified last is searched first
263 {d,Macro}:
265 {d,Macro,Value}:
268 Defines a macro Macro to have the value Value. Macro is of
269 type atom, and Value can be any term. The default Value is
270 true.
271 {parse_transform,Module}:
273 Causes the parse transformation function Module:parse_trans‐
274 form/2 to be applied to the parsed code before the code is
275 checked for errors.
276 from_asm:
278 The input file is expected to be assembler code (default
279 file suffix ".S"). Notice that the format of assembler files
280 is not documented, and can change between releases.
281 from_core:
283 The input file is expected to be core code (default file
284 suffix ".core"). Notice that the format of core files is not
285 documented, and can change between releases.
286 no_spawn_compiler_process:
288 By default, all code is compiled in a separate process which
289 is terminated at the end of compilation. However, some
290 tools, like Dialyzer or compilers for other BEAM languages,
291 may already manage their own worker processes and spawning
292 an extra process may slow the compilation down. In such sce‐
293 narios, you can pass this option to stop the compiler from
294 spawning an additional process.
295 no_strict_record_tests:
297 This option is not recommended.
298 By default, the generated code for operation
300 Record#record_tag.field verifies that the tuple Record has
301 the correct size for the record, and that the first element
302 is the tag record_tag. Use this option to omit the verifica‐
303 tion code.
304 no_error_module_mismatch:
306 Normally the compiler verifies that the module name given in
307 the source code is the same as the base name of the output
308 file and refuses to generate an output file if there is a
309 mismatch. If you have a good reason (or other reason) for
310 having a module name unrelated to the name of the output
311 file, this option disables that verification (there will not
312 even be a warning if there is a mismatch).
313 {no_auto_import,[{F,A}, ...]}:
315 Makes the function F/A no longer being auto-imported from
316 the erlang module, which resolves BIF name clashes. This op‐
317 tion must be used to resolve name clashes with BIFs auto-im‐
318 ported before R14A, if it is needed to call the local func‐
319 tion with the same name as an auto-imported BIF without mod‐
320 ule prefix.
321 Note:
323 As from R14A and forward, the compiler resolves calls without
324 module prefix to local or imported functions before trying
325 with auto-imported BIFs. If the BIF is to be called, use the
326 erlang module prefix in the call, not {no_auto_import,[{F,A},
327 ...]}.
328 If this option is written in the source code, as a -compile
331 directive, the syntax F/A can be used instead of {F,A}, for
332 example:
333 -compile({no_auto_import,[error/1]}).
335 no_auto_import:
337 Do not auto-import any functions from erlang module.
338 no_line_info:
340 Omits line number information to produce a slightly smaller
341 output file.
342 {extra_chunks, [{binary(), binary()}]}:
344 Pass extra chunks to be stored in the .beam file. The extra
345 chunks must be a list of tuples with a four byte binary as
346 chunk name followed by a binary with the chunk contents. See
347 beam_lib for more information.
348 If warnings are turned on (option report_warnings described ear‐
350 lier), the following options control what type of warnings that
351 are generated. Except from {warn_format,Verbosity}, the follow‐
352 ing options have two forms:
353 * A warn_xxx form, to turn on the warning.
355 * A nowarn_xxx form, to turn off the warning.
357 In the descriptions that follow, the form that is used to change
359 the default value are listed.
360 {warn_format, Verbosity}:
362 Causes warnings to be emitted for malformed format strings
363 as arguments to io:format and similar functions.
364 Verbosity selects the number of warnings:
366 * 0 = No warnings
368 * 1 = Warnings for invalid format strings and incorrect num‐
370 ber of arguments
371 * 2 = Warnings also when the validity cannot be checked, for
373 example, when the format string argument is a variable.
374 The default verbosity is 1. Verbosity 0 can also be selected
376 by option nowarn_format.
377 nowarn_bif_clash:
379 This option is removed, it generates a fatal error if used.
380 Warning:
382 As from beginning with R14A, the compiler no longer calls the
383 auto-imported BIF if the name clashes with a local or explic‐
384 itly imported function, and a call without explicit module
385 name is issued. Instead, the local or imported function is
386 called. Still accepting nowarn_bif_clash would make a module
387 calling functions clashing with auto-imported BIFs compile
388 with both the old and new compilers, but with completely dif‐
389 ferent semantics. This is why the option is removed.
390 The use of this option has always been discouraged. As from
392 R14A, it is an error to use it.
393 To resolve BIF clashes, use explicit module names or the
395 {no_auto_import,[F/A]} compiler directive.
396 {nowarn_bif_clash, FAs}:
399 This option is removed, it generates a fatal error if used.
400 Warning:
402 The use of this option has always been discouraged. As from
403 R14A, it is an error to use it.
404 To resolve BIF clashes, use explicit module names or the
406 {no_auto_import,[F/A]} compiler directive.
407 nowarn_export_all:
410 Turns off warnings for uses of the export_all option. De‐
411 fault is to emit a warning if option export_all is also
412 given.
413 warn_export_vars:
415 Emits warnings for all implicitly exported variables re‐
416 ferred to after the primitives where they were first de‐
417 fined. By default, the compiler only emits warnings for ex‐
418 ported variables referred to in a pattern.
419 nowarn_shadow_vars:
421 Turns off warnings for "fresh" variables in functional ob‐
422 jects or list comprehensions with the same name as some al‐
423 ready defined variable. Default is to emit warnings for such
424 variables.
425 nowarn_unused_function:
427 Turns off warnings for unused local functions. Default is to
428 emit warnings for all local functions that are not called
429 directly or indirectly by an exported function. The compiler
430 does not include unused local functions in the generated
431 beam file, but the warning is still useful to keep the
432 source code cleaner.
433 {nowarn_unused_function, FAs}:
435 Turns off warnings for unused local functions like
436 nowarn_unused_function does, but only for the mentioned lo‐
437 cal functions. FAs is a tuple {Name,Arity} or a list of such
438 tuples.
439 nowarn_deprecated_function:
441 Turns off warnings for calls to deprecated functions. De‐
442 fault is to emit warnings for every call to a function known
443 by the compiler to be deprecated. Notice that the compiler
444 does not know about attribute -deprecated(), but uses an as‐
445 sembled list of deprecated functions in Erlang/OTP. To do a
446 more general check, the Xref tool can be used. See also
447 xref(3) and the function xref:m/1, also accessible through
448 the function c:xm/1.
449 {nowarn_deprecated_function, MFAs}:
451 Turns off warnings for calls to deprecated functions like
452 nowarn_deprecated_function does, but only for the mentioned
453 functions. MFAs is a tuple {Module,Name,Arity} or a list of
454 such tuples.
455 nowarn_deprecated_type:
457 Turns off warnings for use of deprecated types. Default is
458 to emit warnings for every use of a type known by the com‐
459 piler to be deprecated.
460 nowarn_removed:
462 Turns off warnings for calls to functions that have been re‐
463 moved. Default is to emit warnings for every call to a func‐
464 tion known by the compiler to have been recently removed
465 from Erlang/OTP.
466 {nowarn_removed, ModulesOrMFAs}:
468 Turns off warnings for calls to modules or functions that
469 have been removed. Default is to emit warnings for every
470 call to a function known by the compiler to have been re‐
471 cently removed from Erlang/OTP.
472 nowarn_obsolete_guard:
474 Turns off warnings for calls to old type testing BIFs, such
475 as pid/1 and list/1. See the Erlang Reference Manual for a
476 complete list of type testing BIFs and their old equiva‐
477 lents. Default is to emit warnings for calls to old type
478 testing BIFs.
479 warn_unused_import:
481 Emits warnings for unused imported functions. Default is to
482 emit no warnings for unused imported functions.
483 nowarn_unused_vars:
485 By default, warnings are emitted for unused variables, ex‐
486 cept for variables beginning with an underscore ("Prolog
487 style warnings"). Use this option to turn off this kind of
488 warnings.
489 nowarn_unused_record:
491 Turns off warnings for unused record types. Default is to
492 emit warnings for unused locally defined record types.
493 nowarn_nif_inline:
495 By default, warnings are emitted when inlining is enabled in
496 a module that may load NIFs, as the compiler may inline NIF
497 fallbacks by accident. Use this option to turn off this kind
498 of warnings.
499 Another class of warnings is generated by the compiler during
501 optimization and code generation. They warn about patterns that
502 will never match (such as a=b), guards that always evaluate to
503 false, and expressions that always fail (such as atom+42).
504 Those warnings cannot be disabled (except by disabling all warn‐
506 ings).
507 Note:
509 The compiler does not warn for expressions that it does not at‐
510 tempt to optimize. For example, the compiler tries to evaluate
511 1/0, detects that it will cause an exception, and emits a warn‐
512 ing. However, the compiler is silent about the similar expres‐
513 sion, X/0, because of the variable in it. Thus, the compiler
514 does not even try to evaluate and therefore it emits no warn‐
515 ings.
516 Warning:
519 The absence of warnings does not mean that there are no remain‐
520 ing errors in the code.
521 Note:
524 All options, except the include path ({i,Dir}), can also be
525 given in the file with attribute -compile([Option,...]). Attri‐
526 bute -compile() is allowed after the function definitions.
527 Note:
530 Before OTP 22, the option {nowarn_deprecated_function, MFAs} was
531 only recognized when given in the file with attribute -com‐
532 pile(). (The option {nowarn_unused_function,FAs} was incorrectly
533 documented to only work in a file, but it also worked when given
534 in the option list.) Starting from OTP 22, all options that can
535 be given in the file can also be given in the option list.
536 For debugging of the compiler, or for pure curiosity, the inter‐
539 mediate code generated by each compiler pass can be inspected.
540 To print a complete list of the options to produce list files,
541 type compile:options() at the Erlang shell prompt. The options
542 are printed in the order that the passes are executed. If more
543 than one listing option is used, the one representing the earli‐
544 est pass takes effect.
545 Unrecognized options are ignored.
547 Both WarningList and ErrorList have the following format:
549 [{FileName,[ErrorInfo]}].
551 ErrorInfo is described later in this section. The filename is
553 included here, as the compiler uses the Erlang pre-processor
554 epp, which allows the code to be included in other files. It is
555 therefore important to know to which file the line number of an
556 error or a warning refers.
557 forms(Forms)
559 Is the same as forms(Forms, [verbose,report_errors,report_warn‐
561 ings]).
562 forms(Forms, Options) -> CompRet
564 Types:
566 Forms = [Form]
568 CompRet = BinRet | ErrRet
569 BinRet = {ok,ModuleName,BinaryOrCode} | {ok,ModuleName,Bina‐
570 ryOrCode,Warnings}
571 BinaryOrCode = binary() | term()
572 ErrRet = error | {error,Errors,Warnings}
573 Analogous to file/1, but takes a list of forms (in the Erlang
575 abstract format representation) as first argument. Option binary
576 is implicit, that is, no object code file is produced. For op‐
577 tions that normally produce a listing file, such as 'E', the in‐
578 ternal format for that compiler pass (an Erlang term, usually
579 not a binary) is returned instead of a binary.
580 format_error(ErrorDescriptor) -> chars()
582 Types:
584 ErrorDescriptor = errordesc()
586 Uses an ErrorDescriptor and returns a deep list of characters
588 that describes the error. This function is usually called im‐
589 plicitly when an ErrorInfo structure (described in section Error
590 Information) is processed.
591 output_generated(Options) -> true | false
593 Types:
595 Options = [term()]
597 Determines whether the compiler generates a beam file with the
599 given options. true means that a beam file is generated. false
600 means that the compiler generates some listing file, returns a
601 binary, or merely checks the syntax of the source code.
602 noenv_file(File, Options) -> CompRet
604 Works like file/2, except that the environment variable ERL_COM‐
606 PILER_OPTIONS is not consulted.
607 noenv_forms(Forms, Options) -> CompRet
609 Works like forms/2, except that the environment variable
611 ERL_COMPILER_OPTIONS is not consulted.
612 noenv_output_generated(Options) -> true | false
614 Types:
616 Options = [term()]
618 Works like output_generated/1, except that the environment vari‐
620 able ERL_COMPILER_OPTIONS is not consulted.
621
623 The (host operating system) environment variable ERL_COMPILER_OPTIONS
624 can be used to give default compiler options. Its value must be a valid
625 Erlang term. If the value is a list, it is used as is. If it is not a
626 list, it is put into a list.
627 The list is appended to any options given to file/2, forms/2, and out‐
629 put_generated/2. Use the alternative functions noenv_file/2,
630 noenv_forms/2, or noenv_output_generated/2 if you do not want the envi‐
631 ronment variable to be consulted, for example, if you are calling the
632 compiler recursively from inside a parse transform.
633 The list can be retrieved with env_compiler_options/0.
635
637 The compiler can do function inlining within an Erlang module. Inlining
638 means that a call to a function is replaced with the function body with
639 the arguments replaced with the actual values. The semantics are pre‐
640 served, except if exceptions are generated in the inlined code. Excep‐
641 tions are reported as occurring in the function the body was inlined
642 into. Also, function_clause exceptions are converted to similar
643 case_clause exceptions.
644 When a function is inlined, the original function is kept if it is ex‐
646 ported (either by an explicit export or if the option export_all was
647 given) or if not all calls to the function are inlined.
648 Inlining does not necessarily improve running time. For example, inlin‐
650 ing can increase Beam stack use, which probably is detrimental to per‐
651 formance for recursive functions.
652 Inlining is never default. It must be explicitly enabled with a com‐
654 piler option or a -compile() attribute in the source module.
655 To enable inlining, either use the option inline to let the compiler
657 decide which functions to inline, or {inline,[{Name,Arity},...]} to
658 have the compiler inline all calls to the given functions. If the op‐
659 tion is given inside a compile directive in an Erlang module, {Name,Ar‐
660 ity} can be written as Name/Arity.
661 Example of explicit inlining:
663 -compile({inline,[pi/0]}).
665 pi() -> 3.1416.
667 Example of implicit inlining:
670 -compile(inline).
672 The option {inline_size,Size} controls how large functions that are al‐
674 lowed to be inlined. Default is 24, which keeps the size of the inlined
675 code roughly the same as the un-inlined version (only relatively small
676 functions are inlined).
677 Example:
679 %% Aggressive inlining - will increase code size.
681 -compile(inline).
682 -compile({inline_size,100}).
683
685 The compiler can also inline various list manipulation functions from
686 the module list in STDLIB.
687 This feature must be explicitly enabled with a compiler option or a
689 -compile() attribute in the source module.
690 To enable inlining of list functions, use option inline_list_funcs.
692 The following functions are inlined:
694 * lists:all/2
696 * lists:any/2
698 * lists:foreach/2
700 * lists:map/2
702 * lists:flatmap/2
704 * lists:filter/2
706 * lists:foldl/3
708 * lists:foldr/3
710 * lists:mapfoldl/3
712 * lists:mapfoldr/3
714
716 Parse transformations are used when a programmer wants to use Erlang
717 syntax but with different semantics. The original Erlang code is then
718 transformed into other Erlang code.
719
721 The ErrorInfo mentioned earlier is the standard ErrorInfo structure,
722 which is returned from all I/O modules. It has the following format:
723 {ErrorLine, Module, ErrorDescriptor}
725 ErrorLine is the atom none if the error does not correspond to a spe‐
727 cific line, for example, if the source file does not exist.
728 A string describing the error is obtained with the following call:
730 Module:format_error(ErrorDescriptor)
732
734 epp(3), erl_id_trans(3), erl_lint(3), beam_lib(3)
735Ericsson AB compiler 7.6.9.1 compile(3)