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 {compile_info, [{atom(), term()}]}:
77 Allows compilers built on top of compile to attach extra
78 compilation metadata to the compile_info chunk in the gener‐
79 ated beam file.
80 It is advised for compilers to remove all non-deterministic
82 information if the deterministic option is supported and it
83 was supplied by the user.
84 compressed:
86 The compiler will compress the generated object code, which
87 can be useful for embedded systems.
88 debug_info:
90 Includes debug information in the form of Erlang Abstract
93 Format in the debug_info chunk of the compiled beam module.
94 Tools such as Debugger, Xref, and Cover require the debug
95 information to be included.
96 Warning: Source code can be reconstructed from the debug
98 information. Use encrypted debug information
99 (encrypt_debug_info) to prevent this.
100 For details, see beam_lib(3).
102 {debug_info, {Backend, Data}}:
104 Includes custom debug information in the form of a Backend
107 module with custom Data in the compiled beam module. The
108 given module must implement a debug_info/4 function and is
109 responsible for generating different code representations,
110 as described in the debug_info under beam_lib(3).
111 Warning: Source code can be reconstructed from the debug
113 information. Use encrypted debug information
114 (encrypt_debug_info) to prevent this.
115 {debug_info_key,KeyString}:
117 {debug_info_key,{Mode,KeyString}}:
120 Includes debug information, but encrypts it so that it can‐
123 not be accessed without supplying the key. (To give option
124 debug_info as well is allowed, but not necessary.) Using
125 this option is a good way to always have the debug informa‐
126 tion available during testing, yet protecting the source
127 code.
128 Mode is the type of crypto algorithm to be used for encrypt‐
130 ing the debug information. The default (and currently the
131 only) type is des3_cbc.
132 For details, see beam_lib(3).
134 encrypt_debug_info:
136 Similar to the debug_info_key option, but the key is read
139 from an .erlang.crypt file.
140 For details, see beam_lib(3).
142 deterministic:
144 Omit the options and source tuples in the list returned by
145 Module:module_info(compile), and reduce the paths in stack
146 traces to the module name alone. This option will make it
147 easier to achieve reproducible builds.
148 makedep:
150 Produces a Makefile rule to track headers dependencies. No
151 object file is produced.
152 By default, this rule is written to <File>.Pbeam. However,
154 if option binary is set, nothing is written and the rule is
155 returned in Binary.
156 For example, if you have the following module:
158 -module(module).
160 -include_lib("eunit/include/eunit.hrl").
162 -include("header.hrl").
163 The Makefile rule generated by this option looks as follows:
165 module.beam: module.erl \
167 /usr/local/lib/erlang/lib/eunit/include/eunit.hrl \
168 header.hrl
169 makedep_side_effect:
171 The dependecies are created as a side effect to the normal
172 compilation process. This means that the object file will
173 also be produced. This option override the makedep option.
174 {makedep_output, Output}:
176 Writes generated rules to Output instead of the default
177 <File>.Pbeam. Output can be a filename or an io_device(). To
178 write to stdout, use standard_io. However, if binary is set,
179 nothing is written to Output and the result is returned to
180 the caller with {ok, ModuleName, Binary}.
181 {makedep_target, Target}:
183 Changes the name of the rule emitted to Target.
184 makedep_quote_target:
186 Characters in Target special to make(1) are quoted.
187 makedep_add_missing:
189 Considers missing headers as generated files and adds them
190 to the dependencies.
191 makedep_phony:
193 Adds a phony target for each dependency.
194 'P':
196 Produces a listing of the parsed code, after preprocessing
197 and parse transforms, in the file <File>.P. No object file
198 is produced.
199 'E':
201 Produces a listing of the code, after all source code trans‐
202 formations have been performed, in the file <File>.E. No
203 object file is produced.
204 'S':
206 Produces a listing of the assembler code in the file
207 <File>.S. No object file is produced.
208 report_errors/report_warnings:
210 Causes errors/warnings to be printed as they occur.
211 report:
213 A short form for both report_errors and report_warnings.
214 return_errors:
216 If this flag is set, {error,ErrorList,WarningList} is
217 returned when there are errors.
218 return_warnings:
220 If this flag is set, an extra field, containing WarningList,
221 is added to the tuples returned on success.
222 warnings_as_errors:
224 Causes warnings to be treated as errors. This option is sup‐
225 ported since R13B04.
226 return:
228 A short form for both return_errors and return_warnings.
229 verbose:
231 Causes more verbose information from the compiler, describ‐
232 ing what it is doing.
233 {source,FileName}:
235 Overrides the source file name as presented in mod‐
236 ule_info(compile) and stack traces.
237 {outdir,Dir}:
239 Sets a new directory for the object code. The current direc‐
240 tory is used for output, except when a directory has been
241 specified with this option.
242 export_all:
244 Causes all functions in the module to be exported.
245 {i,Dir}:
247 Adds Dir to the list of directories to be searched when
248 including a file. When encountering an -include or
249 -include_lib directive, the compiler searches for header
250 files in the following directories:
251 * ".", the current working directory of the file server
253 * The base name of the compiled file
255 * The directories specified using option i; the directory
257 specified last is searched first
258 {d,Macro}:
260 {d,Macro,Value}:
263 Defines a macro Macro to have the value Value. Macro is of
264 type atom, and Value can be any term. The default Value is
265 true.
266 {parse_transform,Module}:
268 Causes the parse transformation function Module:parse_trans‐
269 form/2 to be applied to the parsed code before the code is
270 checked for errors.
271 from_asm:
273 The input file is expected to be assembler code (default
274 file suffix ".S"). Notice that the format of assembler files
275 is not documented, and can change between releases.
276 from_core:
278 The input file is expected to be core code (default file
279 suffix ".core"). Notice that the format of core files is not
280 documented, and can change between releases.
281 no_spawn_compiler_process:
283 By default, all code is compiled in a separate process which
284 is terminated at the end of compilation. However, some
285 tools, like Dialyzer or compilers for other BEAM languages,
286 may already manage their own worker processes and spawning
287 an extra process may slow the compilation down. In such sce‐
288 narios, you can pass this option to stop the compiler from
289 spawning an additional process.
290 no_strict_record_tests:
292 This option is not recommended.
293 By default, the generated code for operation
295 Record#record_tag.field verifies that the tuple Record has
296 the correct size for the record, and that the first element
297 is the tag record_tag. Use this option to omit the verifica‐
298 tion code.
299 no_error_module_mismatch:
301 Normally the compiler verifies that the module name given in
302 the source code is the same as the base name of the output
303 file and refuses to generate an output file if there is a
304 mismatch. If you have a good reason (or other reason) for
305 having a module name unrelated to the name of the output
306 file, this option disables that verification (there will not
307 even be a warning if there is a mismatch).
308 {no_auto_import,[{F,A}, ...]}:
310 Makes the function F/A no longer being auto-imported from
311 the erlang module, which resolves BIF name clashes. This
312 option must be used to resolve name clashes with BIFs auto-
313 imported before R14A, if it is needed to call the local
314 function with the same name as an auto-imported BIF without
315 module prefix.
316 Note:
318 As from R14A and forward, the compiler resolves calls without
319 module prefix to local or imported functions before trying
320 with auto-imported BIFs. If the BIF is to be called, use the
321 erlang module prefix in the call, not {no_auto_import,[{F,A},
322 ...]}.
323 If this option is written in the source code, as a -compile
326 directive, the syntax F/A can be used instead of {F,A}, for
327 example:
328 -compile({no_auto_import,[error/1]}).
330 no_auto_import:
332 Do not auto-import any functions from erlang module.
333 no_line_info:
335 Omits line number information to produce a slightly smaller
336 output file.
337 {extra_chunks, [{binary(), binary()}]}:
339 Pass extra chunks to be stored in the .beam file. The extra
340 chunks must be a list of tuples with a four byte binary as
341 chunk name followed by a binary with the chunk contents. See
342 beam_lib for more information.
343 If warnings are turned on (option report_warnings described ear‐
345 lier), the following options control what type of warnings that
346 are generated. Except from {warn_format,Verbosity}, the follow‐
347 ing options have two forms:
348 * A warn_xxx form, to turn on the warning.
350 * A nowarn_xxx form, to turn off the warning.
352 In the descriptions that follow, the form that is used to change
354 the default value are listed.
355 {warn_format, Verbosity}:
357 Causes warnings to be emitted for malformed format strings
358 as arguments to io:format and similar functions.
359 Verbosity selects the number of warnings:
361 * 0 = No warnings
363 * 1 = Warnings for invalid format strings and incorrect num‐
365 ber of arguments
366 * 2 = Warnings also when the validity cannot be checked, for
368 example, when the format string argument is a variable.
369 The default verbosity is 1. Verbosity 0 can also be selected
371 by option nowarn_format.
372 nowarn_bif_clash:
374 This option is removed, it generates a fatal error if used.
375 Warning:
377 As from beginning with R14A, the compiler no longer calls the
378 auto-imported BIF if the name clashes with a local or explic‐
379 itly imported function, and a call without explicit module
380 name is issued. Instead, the local or imported function is
381 called. Still accepting nowarn_bif_clash would make a module
382 calling functions clashing with auto-imported BIFs compile
383 with both the old and new compilers, but with completely dif‐
384 ferent semantics. This is why the option is removed.
385 The use of this option has always been discouraged. As from
387 R14A, it is an error to use it.
388 To resolve BIF clashes, use explicit module names or the
390 {no_auto_import,[F/A]} compiler directive.
391 {nowarn_bif_clash, FAs}:
394 This option is removed, it generates a fatal error if used.
395 Warning:
397 The use of this option has always been discouraged. As from
398 R14A, it is an error to use it.
399 To resolve BIF clashes, use explicit module names or the
401 {no_auto_import,[F/A]} compiler directive.
402 nowarn_export_all:
405 Turns off warnings for uses of the export_all option.
406 Default is to emit a warning if option export_all is also
407 given.
408 warn_export_vars:
410 Emits warnings for all implicitly exported variables
411 referred to after the primitives where they were first
412 defined. By default, the compiler only emits warnings for
413 exported variables referred to in a pattern.
414 nowarn_shadow_vars:
416 Turns off warnings for "fresh" variables in functional
417 objects or list comprehensions with the same name as some
418 already defined variable. Default is to emit warnings for
419 such variables.
420 nowarn_unused_function:
422 Turns off warnings for unused local functions. Default is to
423 emit warnings for all local functions that are not called
424 directly or indirectly by an exported function. The compiler
425 does not include unused local functions in the generated
426 beam file, but the warning is still useful to keep the
427 source code cleaner.
428 {nowarn_unused_function, FAs}:
430 Turns off warnings for unused local functions like
431 nowarn_unused_function does, but only for the mentioned
432 local functions. FAs is a tuple {Name,Arity} or a list of
433 such tuples.
434 nowarn_deprecated_function:
436 Turns off warnings for calls to deprecated functions.
437 Default is to emit warnings for every call to a function
438 known by the compiler to be deprecated. Notice that the com‐
439 piler does not know about attribute -deprecated(), but uses
440 an assembled list of deprecated functions in Erlang/OTP. To
441 do a more general check, the Xref tool can be used. See also
442 xref(3) and the function xref:m/1, also accessible through
443 the function c:xm/1.
444 {nowarn_deprecated_function, MFAs}:
446 Turns off warnings for calls to deprecated functions like
447 nowarn_deprecated_function does, but only for the mentioned
448 functions. MFAs is a tuple {Module,Name,Arity} or a list of
449 such tuples.
450 nowarn_deprecated_type:
452 Turns off warnings for use of deprecated types. Default is
453 to emit warnings for every use of a type known by the com‐
454 piler to be deprecated.
455 nowarn_removed:
457 Turns off warnings for calls to functions that have been
458 removed. Default is to emit warnings for every call to a
459 function known by the compiler to have been recently removed
460 from Erlang/OTP.
461 {nowarn_removed, ModulesOrMFAs}:
463 Turns off warnings for calls to modules or functions that
464 have been removed. Default is to emit warnings for every
465 call to a function known by the compiler to have been
466 recently removed from Erlang/OTP.
467 nowarn_obsolete_guard:
469 Turns off warnings for calls to old type testing BIFs, such
470 as pid/1 and list/1. See the Erlang Reference Manual for a
471 complete list of type testing BIFs and their old equiva‐
472 lents. Default is to emit warnings for calls to old type
473 testing BIFs.
474 warn_unused_import:
476 Emits warnings for unused imported functions. Default is to
477 emit no warnings for unused imported functions.
478 nowarn_unused_vars:
480 By default, warnings are emitted for unused variables,
481 except for variables beginning with an underscore ("Prolog
482 style warnings"). Use this option to turn off this kind of
483 warnings.
484 nowarn_unused_record:
486 Turns off warnings for unused record types. Default is to
487 emit warnings for unused locally defined record types.
488 Another class of warnings is generated by the compiler during
490 optimization and code generation. They warn about patterns that
491 will never match (such as a=b), guards that always evaluate to
492 false, and expressions that always fail (such as atom+42).
493 Those warnings cannot be disabled (except by disabling all warn‐
495 ings).
496 Note:
498 The compiler does not warn for expressions that it does not
499 attempt to optimize. For example, the compiler tries to evaluate
500 1/0, detects that it will cause an exception, and emits a warn‐
501 ing. However, the compiler is silent about the similar expres‐
502 sion, X/0, because of the variable in it. Thus, the compiler
503 does not even try to evaluate and therefore it emits no warn‐
504 ings.
505 Warning:
508 The absence of warnings does not mean that there are no remain‐
509 ing errors in the code.
510 Note:
513 All options, except the include path ({i,Dir}), can also be
514 given in the file with attribute -compile([Option,...]).
515 Attribute -compile() is allowed after the function definitions.
516 Note:
519 Before OTP 22, the option {nowarn_deprecated_function, MFAs} was
520 only recognized when given in the file with attribute -com‐
521 pile(). (The option {nowarn_unused_function,FAs} was incorrectly
522 documented to only work in a file, but it also worked when given
523 in the option list.) Starting from OTP 22, all options that can
524 be given in the file can also be given in the option list.
525 For debugging of the compiler, or for pure curiosity, the inter‐
528 mediate code generated by each compiler pass can be inspected.
529 To print a complete list of the options to produce list files,
530 type compile:options() at the Erlang shell prompt. The options
531 are printed in the order that the passes are executed. If more
532 than one listing option is used, the one representing the earli‐
533 est pass takes effect.
534 Unrecognized options are ignored.
536 Both WarningList and ErrorList have the following format:
538 [{FileName,[ErrorInfo]}].
540 ErrorInfo is described later in this section. The filename is
542 included here, as the compiler uses the Erlang pre-processor
543 epp, which allows the code to be included in other files. It is
544 therefore important to know to which file the line number of an
545 error or a warning refers.
546 forms(Forms)
548 Is the same as forms(Forms, [verbose,report_errors,report_warn‐
550 ings]).
551 forms(Forms, Options) -> CompRet
553 Types:
555 Forms = [Form]
557 CompRet = BinRet | ErrRet
558 BinRet = {ok,ModuleName,BinaryOrCode} | {ok,ModuleName,Bina‐
559 ryOrCode,Warnings}
560 BinaryOrCode = binary() | term()
561 ErrRet = error | {error,Errors,Warnings}
562 Analogous to file/1, but takes a list of forms (in the Erlang
564 abstract format representation) as first argument. Option binary
565 is implicit, that is, no object code file is produced. For
566 options that normally produce a listing file, such as 'E', the
567 internal format for that compiler pass (an Erlang term, usually
568 not a binary) is returned instead of a binary.
569 format_error(ErrorDescriptor) -> chars()
571 Types:
573 ErrorDescriptor = errordesc()
575 Uses an ErrorDescriptor and returns a deep list of characters
577 that describes the error. This function is usually called
578 implicitly when an ErrorInfo structure (described in section
579 Error Information) is processed.
580 output_generated(Options) -> true | false
582 Types:
584 Options = [term()]
586 Determines whether the compiler generates a beam file with the
588 given options. true means that a beam file is generated. false
589 means that the compiler generates some listing file, returns a
590 binary, or merely checks the syntax of the source code.
591 noenv_file(File, Options) -> CompRet
593 Works like file/2, except that the environment variable ERL_COM‐
595 PILER_OPTIONS is not consulted.
596 noenv_forms(Forms, Options) -> CompRet
598 Works like forms/2, except that the environment variable
600 ERL_COMPILER_OPTIONS is not consulted.
601 noenv_output_generated(Options) -> true | false
603 Types:
605 Options = [term()]
607 Works like output_generated/1, except that the environment vari‐
609 able ERL_COMPILER_OPTIONS is not consulted.
610
612 The (host operating system) environment variable ERL_COMPILER_OPTIONS
613 can be used to give default compiler options. Its value must be a valid
614 Erlang term. If the value is a list, it is used as is. If it is not a
615 list, it is put into a list.
616 The list is appended to any options given to file/2, forms/2, and out‐
618 put_generated/2. Use the alternative functions noenv_file/2,
619 noenv_forms/2, or noenv_output_generated/2 if you do not want the envi‐
620 ronment variable to be consulted, for example, if you are calling the
621 compiler recursively from inside a parse transform.
622 The list can be retrieved with env_compiler_options/0.
624
626 The compiler can do function inlining within an Erlang module. Inlining
627 means that a call to a function is replaced with the function body with
628 the arguments replaced with the actual values. The semantics are pre‐
629 served, except if exceptions are generated in the inlined code. Excep‐
630 tions are reported as occurring in the function the body was inlined
631 into. Also, function_clause exceptions are converted to similar
632 case_clause exceptions.
633 When a function is inlined, the original function is kept if it is
635 exported (either by an explicit export or if the option export_all was
636 given) or if not all calls to the function are inlined.
637 Inlining does not necessarily improve running time. For example, inlin‐
639 ing can increase Beam stack use, which probably is detrimental to per‐
640 formance for recursive functions.
641 Inlining is never default. It must be explicitly enabled with a com‐
643 piler option or a -compile() attribute in the source module.
644 To enable inlining, either use the option inline to let the compiler
646 decide which functions to inline, or {inline,[{Name,Arity},...]} to
647 have the compiler inline all calls to the given functions. If the
648 option is given inside a compile directive in an Erlang module,
649 {Name,Arity} can be written as Name/Arity.
650 Example of explicit inlining:
652 -compile({inline,[pi/0]}).
654 pi() -> 3.1416.
656 Example of implicit inlining:
659 -compile(inline).
661 The option {inline_size,Size} controls how large functions that are
663 allowed to be inlined. Default is 24, which keeps the size of the
664 inlined code roughly the same as the un-inlined version (only rela‐
665 tively small functions are inlined).
666 Example:
668 %% Aggressive inlining - will increase code size.
670 -compile(inline).
671 -compile({inline_size,100}).
672
674 The compiler can also inline various list manipulation functions from
675 the module list in STDLIB.
676 This feature must be explicitly enabled with a compiler option or a
678 -compile() attribute in the source module.
679 To enable inlining of list functions, use option inline_list_funcs.
681 The following functions are inlined:
683 * lists:all/2
685 * lists:any/2
687 * lists:foreach/2
689 * lists:map/2
691 * lists:flatmap/2
693 * lists:filter/2
695 * lists:foldl/3
697 * lists:foldr/3
699 * lists:mapfoldl/3
701 * lists:mapfoldr/3
703
705 Parse transformations are used when a programmer wants to use Erlang
706 syntax but with different semantics. The original Erlang code is then
707 transformed into other Erlang code.
708
710 The ErrorInfo mentioned earlier is the standard ErrorInfo structure,
711 which is returned from all I/O modules. It has the following format:
712 {ErrorLine, Module, ErrorDescriptor}
714 ErrorLine is the atom none if the error does not correspond to a spe‐
716 cific line, for example, if the source file does not exist.
717 A string describing the error is obtained with the following call:
719 Module:format_error(ErrorDescriptor)
721
723 epp(3), erl_id_trans(3), erl_lint(3), beam_lib(3)
724Ericsson AB compiler 7.5.4 compile(3)