1compile(3) Erlang Module Definition compile(3)
2
3
4
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
16 See file/2 for detailed description
17
18 forms() = term()
19
20 List of Erlang abstract or Core Erlang format representations,
21 as used by forms/2
22
24 env_compiler_options()
25
26 Return compiler options given via the environment variable
27 ERL_COMPILER_OPTIONS. If the value is a list, it is returned as
28 is. If it is not a list, it is put into a list.
29
30 file(File)
31
32 Is the same as file(File, [verbose,report_errors,report_warn‐
33 ings]).
34
35 file(File, Options) -> CompRet
36
37 Types:
38
39 CompRet = ModRet | BinRet | ErrRet
40 ModRet = {ok,ModuleName} | {ok,ModuleName,Warnings}
41 BinRet = {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warn‐
42 ings}
43 ErrRet = error | {error,Errors,Warnings}
44
45 Compiles the code in the file File, which is an Erlang source
46 code file without the .erl extension. Options determine the be‐
47 havior of the compiler.
48
49 Returns {ok,ModuleName} if successful, or error if there are er‐
50 rors. An object code file is created if the compilation succeeds
51 without errors. It is considered to be an error if the module
52 name in the source code is not the same as the basename of the
53 output file.
54
55 Available options:
56
57 brief:
58 Restricts error and warning messages to a single line of
59 output. As of OTP 24, the compiler will by default also dis‐
60 play the part of the source code that the message refers to.
61
62 basic_validation:
63 This option is a fast way to test whether a module will com‐
64 pile successfully. This is useful for code generators that
65 want to verify the code that they emit. No code is gener‐
66 ated. If warnings are enabled, warnings generated by the
67 erl_lint module (such as warnings for unused variables and
68 functions) are also returned.
69
70 Use option strong_validation to generate all warnings that
71 the compiler would generate.
72
73 strong_validation:
74 Similar to option basic_validation. No code is generated,
75 but more compiler passes are run to ensure that warnings
76 generated by the optimization passes are generated (such as
77 clauses that will not match, or expressions that are guaran‐
78 teed to fail with an exception at runtime).
79
80 binary:
81 The compiler returns the object code in a binary instead of
82 creating an object file. If successful, the compiler returns
83 {ok,ModuleName,Binary}.
84
85 bin_opt_info:
86 The compiler will emit informational warnings about binary
87 matching optimizations (both successful and unsuccessful).
88 For more information, see the section about bin_opt_info in
89 the Efficiency Guide.
90
91 {compile_info, [{atom(), term()}]}:
92 Allows compilers built on top of compile to attach extra
93 compilation metadata to the compile_info chunk in the gener‐
94 ated beam file.
95
96 It is advised for compilers to remove all non-deterministic
97 information if the deterministic option is supported and it
98 was supplied by the user.
99
100 compressed:
101 The compiler will compress the generated object code, which
102 can be useful for embedded systems.
103
104 debug_info:
105
106
107 Includes debug information in the form of Erlang Abstract
108 Format in the debug_info chunk of the compiled beam module.
109 Tools such as Debugger, Xref, and Cover require the debug
110 information to be included.
111
112 Warning: Source code can be reconstructed from the debug in‐
113 formation. Use encrypted debug information (encrypt_de‐
114 bug_info) to prevent this.
115
116 For details, see beam_lib(3).
117
118 {debug_info, {Backend, Data}}:
119
120
121 Includes custom debug information in the form of a Backend
122 module with custom Data in the compiled beam module. The
123 given module must implement a debug_info/4 function and is
124 responsible for generating different code representations,
125 as described in the debug_info under beam_lib(3).
126
127 Warning: Source code can be reconstructed from the debug in‐
128 formation. Use encrypted debug information (encrypt_de‐
129 bug_info) to prevent this.
130
131 {debug_info_key,KeyString}:
132
133
134 {debug_info_key,{Mode,KeyString}}:
135
136
137 Includes debug information, but encrypts it so that it can‐
138 not be accessed without supplying the key. (To give option
139 debug_info as well is allowed, but not necessary.) Using
140 this option is a good way to always have the debug informa‐
141 tion available during testing, yet protecting the source
142 code.
143
144 Mode is the type of crypto algorithm to be used for encrypt‐
145 ing the debug information. The default (and currently the
146 only) type is des3_cbc.
147
148 For details, see beam_lib(3).
149
150 encrypt_debug_info:
151
152
153 Similar to the debug_info_key option, but the key is read
154 from an .erlang.crypt file.
155
156 For details, see beam_lib(3).
157
158 deterministic:
159 Omit the options and source tuples in the list returned by
160 Module:module_info(compile), and reduce the paths in stack
161 traces to the module name alone. This option will make it
162 easier to achieve reproducible builds.
163
164 {feature, Feature, enable | disable}:
165 Enable (disable) the feature Feature during compilation. The
166 special feature all can be used to enable (disable) all fea‐
167 tures.
168
169 Note:
170 This option has no effect when used in a -compile(..) attri‐
171 bute. Instead, the -feature(..) directive (below) should be
172 used.
173
174 A feature can also be enabled (disabled) using the -fea‐
175 ture(Feature, enable | disable). module directive. Note that
176 this directive can only be present in a prefix of the file,
177 before exports and function definitions. This is the preferred
178 method of enabling and disabling features, since it is a local
179 property of a module.
180
181
182 makedep:
183 Produces a Makefile rule to track headers dependencies. No
184 object file is produced.
185
186 By default, this rule is written to <File>.Pbeam. However,
187 if option binary is set, nothing is written and the rule is
188 returned in Binary.
189
190 The output will be encoded in UTF-8.
191
192 For example, if you have the following module:
193
194 -module(module).
195
196 -include_lib("eunit/include/eunit.hrl").
197 -include("header.hrl").
198
199 The Makefile rule generated by this option looks as follows:
200
201 module.beam: module.erl \
202 /usr/local/lib/erlang/lib/eunit/include/eunit.hrl \
203 header.hrl
204
205 makedep_side_effect:
206 The dependencies are created as a side effect to the normal
207 compilation process. This means that the object file will
208 also be produced. This option override the makedep option.
209
210 {makedep_output, Output}:
211 Writes generated rules to Output instead of the default
212 <File>.Pbeam. Output can be a filename or an io_device(). To
213 write to stdout, use standard_io. However, if binary is set,
214 nothing is written to Output and the result is returned to
215 the caller with {ok, ModuleName, Binary}.
216
217 {makedep_target, Target}:
218 Changes the name of the rule emitted to Target.
219
220 makedep_quote_target:
221 Characters in Target special to make(1) are quoted.
222
223 makedep_add_missing:
224 Considers missing headers as generated files and adds them
225 to the dependencies.
226
227 makedep_phony:
228 Adds a phony target for each dependency.
229
230 'P':
231 Produces a listing of the parsed code, after preprocessing
232 and parse transforms, in the file <File>.P. No object file
233 is produced.
234
235 'E':
236 Produces a listing of the code, after all source code trans‐
237 formations have been performed, in the file <File>.E. No ob‐
238 ject file is produced.
239
240 'S':
241 Produces a listing of the assembler code in the file
242 <File>.S. No object file is produced.
243
244 recv_opt_info:
245 The compiler will emit informational warnings about selec‐
246 tive receive optimizations (both successful and unsuccess‐
247 ful). For more information, see the section about selective
248 receive optimization in the Efficiency Guide.
249
250 report_errors/report_warnings:
251 Causes errors/warnings to be printed as they occur.
252
253 report:
254 A short form for both report_errors and report_warnings.
255
256 return_errors:
257 If this flag is set, {error,ErrorList,WarningList} is re‐
258 turned when there are errors.
259
260 return_warnings:
261 If this flag is set, an extra field, containing WarningList,
262 is added to the tuples returned on success.
263
264 warnings_as_errors:
265 Causes warnings to be treated as errors. This option is sup‐
266 ported since R13B04.
267
268 {error_location,line | column}:
269 If the value of this flag is line, the location ErrorLoca‐
270 tion of warnings and errors is a line number. If the value
271 is column, ErrorLocation includes both a line number and a
272 column number. Default is column. This option is supported
273 since Erlang/OTP 24.0.
274
275 If the value of this flag is column, debug information in‐
276 cludes column information.
277
278 return:
279 A short form for both return_errors and return_warnings.
280
281 verbose:
282 Causes more verbose information from the compiler, describ‐
283 ing what it is doing.
284
285 {source,FileName}:
286 Overrides the source file name as presented in mod‐
287 ule_info(compile) and stack traces.
288
289 absolute_source:
290 Turns the source file name (as presented in module_info(com‐
291 pile) and stack traces) into an absolute path, which helps
292 external tools like perf and gdb find Erlang source code.
293
294 {outdir,Dir}:
295 Sets a new directory for the object code. The current direc‐
296 tory is used for output, except when a directory has been
297 specified with this option.
298
299 export_all:
300 Causes all functions in the module to be exported.
301
302 {i,Dir}:
303 Adds Dir to the list of directories to be searched when in‐
304 cluding a file. When encountering an -include or -in‐
305 clude_lib directive, the compiler searches for header files
306 in the following directories:
307
308 * ".", the current working directory of the file server
309
310 * The base name of the compiled file
311
312 * The directories specified using option i; the directory
313 specified last is searched first
314
315 {d,Macro}:
316
317
318 {d,Macro,Value}:
319 Defines a macro Macro to have the value Value. Macro is of
320 type atom, and Value can be any term. The default Value is
321 true.
322
323 {parse_transform,Module}:
324 Causes the parse transformation function Module:parse_trans‐
325 form/2 to be applied to the parsed code before the code is
326 checked for errors.
327
328 from_abstr:
329 The input file is expected to contain Erlang terms repre‐
330 senting forms in abstract format (default file suffix ".ab‐
331 str"). Note that the format of such terms can change between
332 releases.
333
334 See also the no_lint option.
335
336 from_asm:
337 The input file is expected to be assembler code (default
338 file suffix ".S"). Notice that the format of assembler files
339 is not documented, and can change between releases.
340
341 from_core:
342 The input file is expected to be core code (default file
343 suffix ".core"). Notice that the format of core files is not
344 documented, and can change between releases.
345
346 no_spawn_compiler_process:
347 By default, all code is compiled in a separate process which
348 is terminated at the end of compilation. However, some
349 tools, like Dialyzer or compilers for other BEAM languages,
350 may already manage their own worker processes and spawning
351 an extra process may slow the compilation down. In such sce‐
352 narios, you can pass this option to stop the compiler from
353 spawning an additional process.
354
355 no_strict_record_tests:
356 This option is not recommended.
357
358 By default, the generated code for operation
359 Record#record_tag.field verifies that the tuple Record has
360 the correct size for the record, and that the first element
361 is the tag record_tag. Use this option to omit the verifica‐
362 tion code.
363
364 no_error_module_mismatch:
365 Normally the compiler verifies that the module name given in
366 the source code is the same as the base name of the output
367 file and refuses to generate an output file if there is a
368 mismatch. If you have a good reason (or other reason) for
369 having a module name unrelated to the name of the output
370 file, this option disables that verification (there will not
371 even be a warning if there is a mismatch).
372
373 {no_auto_import,[{F,A}, ...]}:
374 Makes the function F/A no longer being auto-imported from
375 the erlang module, which resolves BIF name clashes. This op‐
376 tion must be used to resolve name clashes with BIFs auto-im‐
377 ported before R14A, if it is needed to call the local func‐
378 tion with the same name as an auto-imported BIF without mod‐
379 ule prefix.
380
381 Note:
382 As from R14A and forward, the compiler resolves calls without
383 module prefix to local or imported functions before trying
384 with auto-imported BIFs. If the BIF is to be called, use the
385 erlang module prefix in the call, not {no_auto_import,[{F,A},
386 ...]}.
387
388
389 If this option is written in the source code, as a -compile
390 directive, the syntax F/A can be used instead of {F,A}, for
391 example:
392
393 -compile({no_auto_import,[error/1]}).
394
395 no_auto_import:
396 Do not auto-import any functions from erlang module.
397
398 no_line_info:
399 Omits line number information to produce a slightly smaller
400 output file.
401
402 no_lint:
403 Skips the pass that checks for errors and warnings. Only ap‐
404 plicable together with the from_abstr option. This is mainly
405 for implementations of other languages on top of Erlang,
406 which have already done their own checks to guarantee cor‐
407 rectness of the code.
408
409 Caveat: When this option is used, there are no guarantees
410 that the code output by the compiler is correct and safe to
411 use. The responsibility for correctness lies on the code or
412 person generating the abstract format. If the code contains
413 errors, the compiler may crash or produce unsafe code.
414
415 {extra_chunks, [{binary(), binary()}]}:
416 Pass extra chunks to be stored in the .beam file. The extra
417 chunks must be a list of tuples with a four byte binary as
418 chunk name followed by a binary with the chunk contents. See
419 beam_lib for more information.
420
421 {check_ssa, Tag :: atom()}:
422 Parse and check assertions on the structure and content of
423 the BEAM SSA code produced by the compiler. The Tag indi‐
424 cates the set of assertions to check and after which com‐
425 piler pass the check is performed. This option is internal
426 to the compiler and can be changed or removed at any time
427 without prior warning.
428
429 If warnings are turned on (option report_warnings described ear‐
430 lier), the following options control what type of warnings that
431 are generated. Except from {warn_format,Verbosity}, the follow‐
432 ing options have two forms:
433
434 * A warn_xxx form, to turn on the warning.
435
436 * A nowarn_xxx form, to turn off the warning.
437
438 In the descriptions that follow, the form that is used to change
439 the default value are listed.
440
441 {warn_format, Verbosity}:
442 Causes warnings to be emitted for malformed format strings
443 as arguments to io:format and similar functions.
444
445 Verbosity selects the number of warnings:
446
447 * 0 = No warnings
448
449 * 1 = Warnings for invalid format strings and incorrect num‐
450 ber of arguments
451
452 * 2 = Warnings also when the validity cannot be checked, for
453 example, when the format string argument is a variable.
454
455 The default verbosity is 1. Verbosity 0 can also be selected
456 by option nowarn_format.
457
458 nowarn_bif_clash:
459 This option is removed, it generates a fatal error if used.
460
461 Warning:
462 As from beginning with R14A, the compiler no longer calls the
463 auto-imported BIF if the name clashes with a local or explic‐
464 itly imported function, and a call without explicit module
465 name is issued. Instead, the local or imported function is
466 called. Still accepting nowarn_bif_clash would make a module
467 calling functions clashing with auto-imported BIFs compile
468 with both the old and new compilers, but with completely dif‐
469 ferent semantics. This is why the option is removed.
470
471 The use of this option has always been discouraged. As from
472 R14A, it is an error to use it.
473
474 To resolve BIF clashes, use explicit module names or the
475 {no_auto_import,[F/A]} compiler directive.
476
477
478 {nowarn_bif_clash, FAs}:
479 This option is removed, it generates a fatal error if used.
480
481 Warning:
482 The use of this option has always been discouraged. As from
483 R14A, it is an error to use it.
484
485 To resolve BIF clashes, use explicit module names or the
486 {no_auto_import,[F/A]} compiler directive.
487
488
489 nowarn_export_all:
490 Turns off warnings for uses of the export_all option. De‐
491 fault is to emit a warning if option export_all is also
492 given.
493
494 warn_export_vars:
495 Emits warnings for all implicitly exported variables re‐
496 ferred to after the primitives where they were first de‐
497 fined. By default, the compiler only emits warnings for ex‐
498 ported variables referred to in a pattern.
499
500 nowarn_shadow_vars:
501 Turns off warnings for "fresh" variables in functional ob‐
502 jects or list comprehensions with the same name as some al‐
503 ready defined variable. Default is to emit warnings for such
504 variables.
505
506 warn_keywords:
507 Emits warnings when the code contains atoms that are used as
508 keywords in some feature. When the feature is enabled, any
509 occurrences will lead to a syntax error. To prevent this,
510 the atom has to be renamed or quoted.
511
512 nowarn_unused_function:
513 Turns off warnings for unused local functions. Default is to
514 emit warnings for all local functions that are not called
515 directly or indirectly by an exported function. The compiler
516 does not include unused local functions in the generated
517 beam file, but the warning is still useful to keep the
518 source code cleaner.
519
520 {nowarn_unused_function, FAs}:
521 Turns off warnings for unused local functions like
522 nowarn_unused_function does, but only for the mentioned lo‐
523 cal functions. FAs is a tuple {Name,Arity} or a list of such
524 tuples.
525
526 nowarn_deprecated_function:
527 Turns off warnings for calls to deprecated functions. De‐
528 fault is to emit warnings for every call to a function known
529 by the compiler to be deprecated. Notice that the compiler
530 does not know about attribute -deprecated(), but uses an as‐
531 sembled list of deprecated functions in Erlang/OTP. To do a
532 more general check, the Xref tool can be used. See also
533 xref(3) and the function xref:m/1, also accessible through
534 the function c:xm/1.
535
536 {nowarn_deprecated_function, MFAs}:
537 Turns off warnings for calls to deprecated functions like
538 nowarn_deprecated_function does, but only for the mentioned
539 functions. MFAs is a tuple {Module,Name,Arity} or a list of
540 such tuples.
541
542 nowarn_deprecated_type:
543 Turns off warnings for use of deprecated types. Default is
544 to emit warnings for every use of a type known by the com‐
545 piler to be deprecated.
546
547 nowarn_removed:
548 Turns off warnings for calls to functions that have been re‐
549 moved. Default is to emit warnings for every call to a func‐
550 tion known by the compiler to have been recently removed
551 from Erlang/OTP.
552
553 {nowarn_removed, ModulesOrMFAs}:
554 Turns off warnings for calls to modules or functions that
555 have been removed. Default is to emit warnings for every
556 call to a function known by the compiler to have been re‐
557 cently removed from Erlang/OTP.
558
559 nowarn_obsolete_guard:
560 Turns off warnings for calls to old type testing BIFs, such
561 as pid/1 and list/1. See the Erlang Reference Manual for a
562 complete list of type testing BIFs and their old equiva‐
563 lents. Default is to emit warnings for calls to old type
564 testing BIFs.
565
566 warn_unused_import:
567 Emits warnings for unused imported functions. Default is to
568 emit no warnings for unused imported functions.
569
570 nowarn_underscore_match:
571 By default, warnings are emitted when a variable that begins
572 with an underscore is matched after being bound. Use this
573 option to turn off this kind of warning.
574
575 nowarn_unused_vars:
576 By default, warnings are emitted for unused variables, ex‐
577 cept for variables beginning with an underscore ("Prolog
578 style warnings"). Use this option to turn off this kind of
579 warning.
580
581 nowarn_unused_record:
582 Turns off warnings for unused record definitions. Default is
583 to emit warnings for unused locally defined records.
584
585 {nowarn_unused_record, RecordNames}:
586 Turns off warnings for unused record definitions. Default is
587 to emit warnings for unused locally defined records.
588
589 nowarn_unused_type:
590 Turns off warnings for unused type declarations. Default is
591 to emit warnings for unused local type declarations.
592
593 nowarn_nif_inline:
594 By default, warnings are emitted when inlining is enabled in
595 a module that may load NIFs, as the compiler may inline NIF
596 fallbacks by accident. Use this option to turn off this kind
597 of warnings.
598
599 warn_missing_spec:
600 By default, warnings are not emitted when a specification
601 (or contract) for an exported function is not given. Use
602 this option to turn on this kind of warning.
603
604 warn_missing_spec_all:
605 By default, warnings are not emitted when a specification
606 (or contract) for an exported or unexported function is not
607 given. Use this option to turn on this kind of warning.
608
609 nowarn_redefined_builtin_type:
610 By default, a warning is emitted when a built-in type is lo‐
611 cally redefined. Use this option to turn off this kind of
612 warning.
613
614 {nowarn_redefined_builtin_type, Types}:
615 By default, a warning is emitted when a built-in type is lo‐
616 cally redefined. Use this option to turn off this kind of
617 warning for the types in Types, where Types is a tuple
618 {TypeName,Arity} or a list of such tuples.
619
620 Other kinds of warnings are opportunistic warnings. They are
621 generated when the compiler happens to notice potential issues
622 during optimization and code generation.
623
624 Note:
625 The compiler does not warn for expressions that it does not at‐
626 tempt to optimize. For example, the compiler will emit a warning
627 for 1/0 but not for X/0, because 1/0 is a constant expression
628 that the compiler will attempt to evaluate.
629
630 The absence of warnings does not mean that there are no remain‐
631 ing errors in the code.
632
633
634 Opportunistic warnings can be disabled using the following op‐
635 tions:
636
637 nowarn_opportunistic:
638 Disable all opportunistic warnings.
639
640 nowarn_failed:
641 Disable warnings for expressions that will always fail (such
642 as atom+42).
643
644 nowarn_ignored:
645 Disable warnings for expressions whose values are ignored.
646
647 nowarn_nomatch:
648 Disable warnings for patterns that will never match (such as
649 a=b) and for guards that always evaluate to false.
650
651 Note:
652 All options, except the include path ({i,Dir}), can also be
653 given in the file with attribute -compile([Option,...]). Attri‐
654 bute -compile() is allowed after the function definitions.
655
656
657 Note:
658 Before OTP 22, the option {nowarn_deprecated_function, MFAs} was
659 only recognized when given in the file with attribute -com‐
660 pile(). (The option {nowarn_unused_function,FAs} was incorrectly
661 documented to only work in a file, but it also worked when given
662 in the option list.) Starting from OTP 22, all options that can
663 be given in the file can also be given in the option list.
664
665
666 For debugging of the compiler, or for pure curiosity, the inter‐
667 mediate code generated by each compiler pass can be inspected.
668 To print a complete list of the options to produce list files,
669 type compile:options() at the Erlang shell prompt. The options
670 are printed in the order that the passes are executed. If more
671 than one listing option is used, the one representing the earli‐
672 est pass takes effect.
673
674 Unrecognized options are ignored.
675
676 Both WarningList and ErrorList have the following format:
677
678 [{FileName,[ErrorInfo]}].
679
680 ErrorInfo is described later in this section. The filename is
681 included here, as the compiler uses the Erlang pre-processor
682 epp, which allows the code to be included in other files. It is
683 therefore important to know to which file the location of an er‐
684 ror or a warning refers.
685
686 forms(Forms)
687
688 Is the same as forms(Forms, [verbose,report_errors,report_warn‐
689 ings]).
690
691 forms(Forms, Options) -> CompRet
692
693 Types:
694
695 Forms = forms()
696 forms() = [erl_parse:abstract_form] | cerl:c_module()
697 Options = [option()]
698 CompRet = BinRet | ErrRet
699 BinRet = {ok,ModuleName,BinaryOrCode} | {ok,ModuleName,Bina‐
700 ryOrCode,Warnings}
701 ModuleName = module()
702 BinaryOrCode = binary() | term()
703 ErrRet = error | {error,Errors,Warnings}
704 Warnings = Errors = [{file:filename(), [{erl_anno:location()
705 | 'none', module(), term()}]}]
706
707 Analogous to file/1, but takes a list of forms (in either Erlang
708 abstract or Core Erlang format representation) as first argu‐
709 ment. Option binary is implicit, that is, no object code file is
710 produced. For options that normally produce a listing file, such
711 as 'E', the internal format for that compiler pass (an Erlang
712 term, usually not a binary) is returned instead of a binary.
713
714 format_error(ErrorDescriptor) -> chars()
715
716 Types:
717
718 ErrorDescriptor = errordesc()
719
720 Uses an ErrorDescriptor and returns a deep list of characters
721 that describes the error. This function is usually called im‐
722 plicitly when an ErrorInfo structure (described in section Error
723 Information) is processed.
724
725 output_generated(Options) -> true | false
726
727 Types:
728
729 Options = [term()]
730
731 Determines whether the compiler generates a beam file with the
732 given options. true means that a beam file is generated. false
733 means that the compiler generates some listing file, returns a
734 binary, or merely checks the syntax of the source code.
735
736 noenv_file(File, Options) -> CompRet
737
738 Works like file/2, except that the environment variable ERL_COM‐
739 PILER_OPTIONS is not consulted.
740
741 noenv_forms(Forms, Options) -> CompRet
742
743 Works like forms/2, except that the environment variable
744 ERL_COMPILER_OPTIONS is not consulted.
745
746 noenv_output_generated(Options) -> true | false
747
748 Types:
749
750 Options = [term()]
751
752 Works like output_generated/1, except that the environment vari‐
753 able ERL_COMPILER_OPTIONS is not consulted.
754
756 The (host operating system) environment variable ERL_COMPILER_OPTIONS
757 can be used to give default compiler options. Its value must be a valid
758 Erlang term. If the value is a list, it is used as is. If it is not a
759 list, it is put into a list.
760
761 The list is appended to any options given to file/2, forms/2, and out‐
762 put_generated/2. Use the alternative functions noenv_file/2,
763 noenv_forms/2, or noenv_output_generated/2 if you do not want the envi‐
764 ronment variable to be consulted, for example, if you are calling the
765 compiler recursively from inside a parse transform.
766
767 The list can be retrieved with env_compiler_options/0.
768
770 The compiler can do function inlining within an Erlang module. Inlining
771 means that a call to a function is replaced with the function body with
772 the arguments replaced with the actual values. The semantics are pre‐
773 served, except if exceptions are generated in the inlined code. Excep‐
774 tions are reported as occurring in the function the body was inlined
775 into. Also, function_clause exceptions are converted to similar
776 case_clause exceptions.
777
778 When a function is inlined, the original function is kept if it is ex‐
779 ported (either by an explicit export or if the option export_all was
780 given) or if not all calls to the function are inlined.
781
782 Inlining does not necessarily improve running time. For example, inlin‐
783 ing can increase Beam stack use, which probably is detrimental to per‐
784 formance for recursive functions.
785
786 Inlining is never default. It must be explicitly enabled with a com‐
787 piler option or a -compile() attribute in the source module.
788
789 To enable inlining, either use the option inline to let the compiler
790 decide which functions to inline, or {inline,[{Name,Arity},...]} to
791 have the compiler inline all calls to the given functions. If the op‐
792 tion is given inside a compile directive in an Erlang module, {Name,Ar‐
793 ity} can be written as Name/Arity.
794
795 Example of explicit inlining:
796
797 -compile({inline,[pi/0]}).
798
799 pi() -> 3.1416.
800
801
802 Example of implicit inlining:
803
804 -compile(inline).
805
806 The option {inline_size,Size} controls how large functions that are al‐
807 lowed to be inlined. Default is 24, which keeps the size of the inlined
808 code roughly the same as the un-inlined version (only relatively small
809 functions are inlined).
810
811 Example:
812
813 %% Aggressive inlining - will increase code size.
814 -compile(inline).
815 -compile({inline_size,100}).
816
818 The compiler can also inline various list manipulation functions from
819 the module list in STDLIB.
820
821 This feature must be explicitly enabled with a compiler option or a
822 -compile() attribute in the source module.
823
824 To enable inlining of list functions, use option inline_list_funcs.
825
826 The following functions are inlined:
827
828 * lists:all/2
829
830 * lists:any/2
831
832 * lists:foreach/2
833
834 * lists:map/2
835
836 * lists:flatmap/2
837
838 * lists:filter/2
839
840 * lists:foldl/3
841
842 * lists:foldr/3
843
844 * lists:mapfoldl/3
845
846 * lists:mapfoldr/3
847
849 Parse transformations are used when a programmer wants to use Erlang
850 syntax but with different semantics. The original Erlang code is then
851 transformed into other Erlang code.
852
853 See erl_id_trans(3) for an example and an explanation of the function
854 parse_transform_info/0.
855
857 The ErrorInfo mentioned earlier is the standard ErrorInfo structure,
858 which is returned from all I/O modules. It has the following format:
859
860 {ErrorLocation, Module, ErrorDescriptor}
861
862 ErrorLocation is the atom none if the error does not correspond to a
863 specific location, for example, if the source file does not exist.
864
865 A string describing the error is obtained with the following call:
866
867 Module:format_error(ErrorDescriptor)
868
870 epp(3), erl_id_trans(3), erl_lint(3), beam_lib(3)
871
872
873
874Ericsson AB compiler 8.4.1 compile(3)