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_strict_record_tests:
283 This option is not recommended.
284 By default, the generated code for operation
286 Record#record_tag.field verifies that the tuple Record has
287 the correct size for the record, and that the first element
288 is the tag record_tag. Use this option to omit the verifica‐
289 tion code.
290 no_error_module_mismatch:
292 Normally the compiler verifies that the module name given in
293 the source code is the same as the base name of the output
294 file and refuses to generate an output file if there is a
295 mismatch. If you have a good reason (or other reason) for
296 having a module name unrelated to the name of the output
297 file, this option disables that verification (there will not
298 even be a warning if there is a mismatch).
299 {no_auto_import,[{F,A}, ...]}:
301 Makes the function F/A no longer being auto-imported from
302 the erlang module, which resolves BIF name clashes. This
303 option must be used to resolve name clashes with BIFs auto-
304 imported before R14A, if it is needed to call the local
305 function with the same name as an auto-imported BIF without
306 module prefix.
307 Note:
309 As from R14A and forward, the compiler resolves calls without
310 module prefix to local or imported functions before trying
311 with auto-imported BIFs. If the BIF is to be called, use the
312 erlang module prefix in the call, not {no_auto_import,[{F,A},
313 ...]}.
314 If this option is written in the source code, as a -compile
317 directive, the syntax F/A can be used instead of {F,A}, for
318 example:
319 -compile({no_auto_import,[error/1]}).
321 no_auto_import:
323 Do not auto-import any functions from erlang module.
324 no_line_info:
326 Omits line number information to produce a slightly smaller
327 output file.
328 {extra_chunks, [{binary(), binary()}]}:
330 Pass extra chunks to be stored in the .beam file. The extra
331 chunks must be a list of tuples with a four byte binary as
332 chunk name followed by a binary with the chunk contents. See
333 beam_lib for more information.
334 If warnings are turned on (option report_warnings described ear‐
336 lier), the following options control what type of warnings that
337 are generated. Except from {warn_format,Verbosity}, the follow‐
338 ing options have two forms:
339 * A warn_xxx form, to turn on the warning.
341 * A nowarn_xxx form, to turn off the warning.
343 In the descriptions that follow, the form that is used to change
345 the default value are listed.
346 {warn_format, Verbosity}:
348 Causes warnings to be emitted for malformed format strings
349 as arguments to io:format and similar functions.
350 Verbosity selects the number of warnings:
352 * 0 = No warnings
354 * 1 = Warnings for invalid format strings and incorrect num‐
356 ber of arguments
357 * 2 = Warnings also when the validity cannot be checked, for
359 example, when the format string argument is a variable.
360 The default verbosity is 1. Verbosity 0 can also be selected
362 by option nowarn_format.
363 nowarn_bif_clash:
365 This option is removed, it generates a fatal error if used.
366 Warning:
368 As from beginning with R14A, the compiler no longer calls the
369 auto-imported BIF if the name clashes with a local or explic‐
370 itly imported function, and a call without explicit module
371 name is issued. Instead, the local or imported function is
372 called. Still accepting nowarn_bif_clash would make a module
373 calling functions clashing with auto-imported BIFs compile
374 with both the old and new compilers, but with completely dif‐
375 ferent semantics. This is why the option is removed.
376 The use of this option has always been discouraged. As from
378 R14A, it is an error to use it.
379 To resolve BIF clashes, use explicit module names or the
381 {no_auto_import,[F/A]} compiler directive.
382 {nowarn_bif_clash, FAs}:
385 This option is removed, it generates a fatal error if used.
386 Warning:
388 The use of this option has always been discouraged. As from
389 R14A, it is an error to use it.
390 To resolve BIF clashes, use explicit module names or the
392 {no_auto_import,[F/A]} compiler directive.
393 nowarn_export_all:
396 Turns off warnings for uses of the export_all option.
397 Default is to emit a warning if option export_all is also
398 given.
399 warn_export_vars:
401 Emits warnings for all implicitly exported variables
402 referred to after the primitives where they were first
403 defined. By default, the compiler only emits warnings for
404 exported variables referred to in a pattern.
405 nowarn_shadow_vars:
407 Turns off warnings for "fresh" variables in functional
408 objects or list comprehensions with the same name as some
409 already defined variable. Default is to emit warnings for
410 such variables.
411 nowarn_unused_function:
413 Turns off warnings for unused local functions. Default is to
414 emit warnings for all local functions that are not called
415 directly or indirectly by an exported function. The compiler
416 does not include unused local functions in the generated
417 beam file, but the warning is still useful to keep the
418 source code cleaner.
419 {nowarn_unused_function, FAs}:
421 Turns off warnings for unused local functions like
422 nowarn_unused_function does, but only for the mentioned
423 local functions. FAs is a tuple {Name,Arity} or a list of
424 such tuples.
425 nowarn_deprecated_function:
427 Turns off warnings for calls to deprecated functions.
428 Default is to emit warnings for every call to a function
429 known by the compiler to be deprecated. Notice that the com‐
430 piler does not know about attribute -deprecated(), but uses
431 an assembled list of deprecated functions in Erlang/OTP. To
432 do a more general check, the Xref tool can be used. See also
433 xref(3) and the function xref:m/1, also accessible through
434 the function c:xm/1.
435 {nowarn_deprecated_function, MFAs}:
437 Turns off warnings for calls to deprecated functions like
438 nowarn_deprecated_function does, but only for the mentioned
439 functions. MFAs is a tuple {Module,Name,Arity} or a list of
440 such tuples.
441 nowarn_deprecated_type:
443 Turns off warnings for use of deprecated types. Default is
444 to emit warnings for every use of a type known by the com‐
445 piler to be deprecated.
446 nowarn_obsolete_guard:
448 Turns off warnings for calls to old type testing BIFs, such
449 as pid/1 and list/1. See the Erlang Reference Manual for a
450 complete list of type testing BIFs and their old equiva‐
451 lents. Default is to emit warnings for calls to old type
452 testing BIFs.
453 warn_unused_import:
455 Emits warnings for unused imported functions. Default is to
456 emit no warnings for unused imported functions.
457 nowarn_unused_vars:
459 By default, warnings are emitted for unused variables,
460 except for variables beginning with an underscore ("Prolog
461 style warnings"). Use this option to turn off this kind of
462 warnings.
463 nowarn_unused_record:
465 Turns off warnings for unused record types. Default is to
466 emit warnings for unused locally defined record types.
467 Another class of warnings is generated by the compiler during
469 optimization and code generation. They warn about patterns that
470 will never match (such as a=b), guards that always evaluate to
471 false, and expressions that always fail (such as atom+42).
472 Those warnings cannot be disabled (except by disabling all warn‐
474 ings).
475 Note:
477 The compiler does not warn for expressions that it does not
478 attempt to optimize. For example, the compiler tries to evaluate
479 1/0, detects that it will cause an exception, and emits a warn‐
480 ing. However, the compiler is silent about the similar expres‐
481 sion, X/0, because of the variable in it. Thus, the compiler
482 does not even try to evaluate and therefore it emits no warn‐
483 ings.
484 Warning:
487 The absence of warnings does not mean that there are no remain‐
488 ing errors in the code.
489 Note:
492 All options, except the include path ({i,Dir}), can also be
493 given in the file with attribute -compile([Option,...]).
494 Attribute -compile() is allowed after the function definitions.
495 Note:
498 The options {nowarn_unused_function, FAs}, {nowarn_bif_clash,
499 FAs}, and {nowarn_deprecated_function, MFAs} are only recognized
500 when given in files. They are not affected by options
501 warn_unused_function, warn_bif_clash, or warn_deprecated_func‐
502 tion.
503 For debugging of the compiler, or for pure curiosity, the inter‐
506 mediate code generated by each compiler pass can be inspected.
507 To print a complete list of the options to produce list files,
508 type compile:options() at the Erlang shell prompt. The options
509 are printed in the order that the passes are executed. If more
510 than one listing option is used, the one representing the earli‐
511 est pass takes effect.
512 Unrecognized options are ignored.
514 Both WarningList and ErrorList have the following format:
516 [{FileName,[ErrorInfo]}].
518 ErrorInfo is described later in this section. The filename is
520 included here, as the compiler uses the Erlang pre-processor
521 epp, which allows the code to be included in other files. It is
522 therefore important to know to which file the line number of an
523 error or a warning refers.
524 forms(Forms)
526 Is the same as forms(Forms, [verbose,report_errors,report_warn‐
528 ings]).
529 forms(Forms, Options) -> CompRet
531 Types:
533 Forms = [Form]
535 CompRet = BinRet | ErrRet
536 BinRet = {ok,ModuleName,BinaryOrCode} | {ok,ModuleName,Bina‐
537 ryOrCode,Warnings}
538 BinaryOrCode = binary() | term()
539 ErrRet = error | {error,Errors,Warnings}
540 Analogous to file/1, but takes a list of forms (in the Erlang
542 abstract format representation) as first argument. Option binary
543 is implicit, that is, no object code file is produced. For
544 options that normally produce a listing file, such as 'E', the
545 internal format for that compiler pass (an Erlang term, usually
546 not a binary) is returned instead of a binary.
547 format_error(ErrorDescriptor) -> chars()
549 Types:
551 ErrorDescriptor = errordesc()
553 Uses an ErrorDescriptor and returns a deep list of characters
555 that describes the error. This function is usually called
556 implicitly when an ErrorInfo structure (described in section
557 Error Information) is processed.
558 output_generated(Options) -> true | false
560 Types:
562 Options = [term()]
564 Determines whether the compiler generates a beam file with the
566 given options. true means that a beam file is generated. false
567 means that the compiler generates some listing file, returns a
568 binary, or merely checks the syntax of the source code.
569 noenv_file(File, Options) -> CompRet
571 Works like file/2, except that the environment variable ERL_COM‐
573 PILER_OPTIONS is not consulted.
574 noenv_forms(Forms, Options) -> CompRet
576 Works like forms/2, except that the environment variable
578 ERL_COMPILER_OPTIONS is not consulted.
579 noenv_output_generated(Options) -> true | false
581 Types:
583 Options = [term()]
585 Works like output_generated/1, except that the environment vari‐
587 able ERL_COMPILER_OPTIONS is not consulted.
588
590 The (host operating system) environment variable ERL_COMPILER_OPTIONS
591 can be used to give default compiler options. Its value must be a valid
592 Erlang term. If the value is a list, it is used as is. If it is not a
593 list, it is put into a list.
594 The list is appended to any options given to file/2, forms/2, and out‐
596 put_generated/2. Use the alternative functions noenv_file/2,
597 noenv_forms/2, or noenv_output_generated/2 if you do not want the envi‐
598 ronment variable to be consulted, for example, if you are calling the
599 compiler recursively from inside a parse transform.
600 The list can be retrieved with env_compiler_options/0.
602
604 The compiler can do function inlining within an Erlang module. Inlining
605 means that a call to a function is replaced with the function body with
606 the arguments replaced with the actual values. The semantics are pre‐
607 served, except if exceptions are generated in the inlined code. Excep‐
608 tions are reported as occurring in the function the body was inlined
609 into. Also, function_clause exceptions are converted to similar
610 case_clause exceptions.
611 When a function is inlined, the original function is kept if it is
613 exported (either by an explicit export or if the option export_all was
614 given) or if not all calls to the function are inlined.
615 Inlining does not necessarily improve running time. For example, inlin‐
617 ing can increase Beam stack use, which probably is detrimental to per‐
618 formance for recursive functions.
619 Inlining is never default. It must be explicitly enabled with a com‐
621 piler option or a -compile() attribute in the source module.
622 To enable inlining, either use the option inline to let the compiler
624 decide which functions to inline, or {inline,[{Name,Arity},...]} to
625 have the compiler inline all calls to the given functions. If the
626 option is given inside a compile directive in an Erlang module,
627 {Name,Arity} can be written as Name/Arity.
628 Example of explicit inlining:
630 -compile({inline,[pi/0]}).
632 pi() -> 3.1416.
634 Example of implicit inlining:
637 -compile(inline).
639 The option {inline_size,Size} controls how large functions that are
641 allowed to be inlined. Default is 24, which keeps the size of the
642 inlined code roughly the same as the un-inlined version (only rela‐
643 tively small functions are inlined).
644 Example:
646 %% Aggressive inlining - will increase code size.
648 -compile(inline).
649 -compile({inline_size,100}).
650
652 The compiler can also inline various list manipulation functions from
653 the module list in STDLIB.
654 This feature must be explicitly enabled with a compiler option or a
656 -compile() attribute in the source module.
657 To enable inlining of list functions, use option inline_list_funcs.
659 The following functions are inlined:
661 * lists:all/2
663 * lists:any/2
665 * lists:foreach/2
667 * lists:map/2
669 * lists:flatmap/2
671 * lists:filter/2
673 * lists:foldl/3
675 * lists:foldr/3
677 * lists:mapfoldl/3
679 * lists:mapfoldr/3
681
683 Parse transformations are used when a programmer wants to use Erlang
684 syntax but with different semantics. The original Erlang code is then
685 transformed into other Erlang code.
686
688 The ErrorInfo mentioned earlier is the standard ErrorInfo structure,
689 which is returned from all I/O modules. It has the following format:
690 {ErrorLine, Module, ErrorDescriptor}
692 ErrorLine is the atom none if the error does not correspond to a spe‐
694 cific line, for example, if the source file does not exist.
695 A string describing the error is obtained with the following call:
697 Module:format_error(ErrorDescriptor)
699
701 epp(3), erl_id_trans(3), erl_lint(3), beam_lib(3)
702Ericsson AB compiler 7.3.2 compile(3)