1compile(3)                 Erlang Module Definition                 compile(3)
2
3
4

NAME

6       compile - Erlang Compiler
7

DESCRIPTION

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

DATA TYPES

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

EXPORTS

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                makedep:
165                  Produces a Makefile rule to track headers  dependencies.  No
166                  object file is produced.
167
168                  By  default,  this rule is written to <File>.Pbeam. However,
169                  if option binary is set, nothing is written and the rule  is
170                  returned in Binary.
171
172                  The output will be encoded in UTF-8.
173
174                  For example, if you have the following module:
175
176                -module(module).
177
178                -include_lib("eunit/include/eunit.hrl").
179                -include("header.hrl").
180
181                  The Makefile rule generated by this option looks as follows:
182
183                module.beam: module.erl \
184                  /usr/local/lib/erlang/lib/eunit/include/eunit.hrl \
185                  header.hrl
186
187                makedep_side_effect:
188                  The  dependecies  are created as a side effect to the normal
189                  compilation process. This means that the  object  file  will
190                  also be produced. This option override the makedep option.
191
192                {makedep_output, Output}:
193                  Writes  generated  rules  to  Output  instead of the default
194                  <File>.Pbeam. Output can be a filename or an io_device(). To
195                  write to stdout, use standard_io. However, if binary is set,
196                  nothing is written to Output and the result is  returned  to
197                  the caller with {ok, ModuleName, Binary}.
198
199                {makedep_target, Target}:
200                  Changes the name of the rule emitted to Target.
201
202                makedep_quote_target:
203                  Characters in Target special to make(1) are quoted.
204
205                makedep_add_missing:
206                  Considers  missing  headers as generated files and adds them
207                  to the dependencies.
208
209                makedep_phony:
210                  Adds a phony target for each dependency.
211
212                'P':
213                  Produces a listing of the parsed code,  after  preprocessing
214                  and  parse  transforms, in the file <File>.P. No object file
215                  is produced.
216
217                'E':
218                  Produces a listing of the code, after all source code trans‐
219                  formations have been performed, in the file <File>.E. No ob‐
220                  ject file is produced.
221
222                'S':
223                  Produces a  listing  of  the  assembler  code  in  the  file
224                  <File>.S. No object file is produced.
225
226                recv_opt_info:
227                  The  compiler  will emit informational warnings about selec‐
228                  tive receive optimizations (both successful  and  unsuccess‐
229                  ful). For more information, see the section about  selective
230                  receive optimization in the Efficiency Guide.
231
232                report_errors/report_warnings:
233                  Causes errors/warnings to be printed as they occur.
234
235                report:
236                  A short form for both report_errors and report_warnings.
237
238                return_errors:
239                  If this flag is set,  {error,ErrorList,WarningList}  is  re‐
240                  turned when there are errors.
241
242                return_warnings:
243                  If this flag is set, an extra field, containing WarningList,
244                  is added to the tuples returned on success.
245
246                warnings_as_errors:
247                  Causes warnings to be treated as errors. This option is sup‐
248                  ported since R13B04.
249
250                {error_location,line | column}:
251                  If  the  value of this flag is line, the location ErrorLoca‐
252                  tion of warnings and errors is a line number. If  the  value
253                  is  column,  ErrorLocation includes both a line number and a
254                  column number. Default is column. This option  is  supported
255                  since Erlang/OTP 24.0.
256
257                  If  the  value of this flag is column, debug information in‐
258                  cludes column information.
259
260                return:
261                  A short form for both return_errors and return_warnings.
262
263                verbose:
264                  Causes more verbose information from the compiler,  describ‐
265                  ing what it is doing.
266
267                {source,FileName}:
268                  Overrides   the  source  file  name  as  presented  in  mod‐
269                  ule_info(compile) and stack traces.
270
271                {outdir,Dir}:
272                  Sets a new directory for the object code. The current direc‐
273                  tory  is  used  for output, except when a directory has been
274                  specified with this option.
275
276                export_all:
277                  Causes all functions in the module to be exported.
278
279                {i,Dir}:
280                  Adds Dir to the list of directories to be searched when  in‐
281                  cluding  a  file.  When  encountering  an  -include  or -in‐
282                  clude_lib directive, the compiler searches for header  files
283                  in the following directories:
284
285                  * ".", the current working directory of the file server
286
287                  * The base name of the compiled file
288
289                  * The  directories  specified  using option i; the directory
290                    specified last is searched first
291
292                {d,Macro}:
293
294
295                {d,Macro,Value}:
296                  Defines a macro Macro to have the value Value. Macro  is  of
297                  type  atom,  and Value can be any term. The default Value is
298                  true.
299
300                {parse_transform,Module}:
301                  Causes the parse transformation function Module:parse_trans‐
302                  form/2  to  be applied to the parsed code before the code is
303                  checked for errors.
304
305                from_abstr:
306                  The input file is expected to contain  Erlang  terms  repre‐
307                  senting  forms in abstract format (default file suffix ".ab‐
308                  str"). Note that the format of such terms can change between
309                  releases.
310
311                  See also the no_lint option.
312
313                from_asm:
314                  The  input  file  is  expected to be assembler code (default
315                  file suffix ".S"). Notice that the format of assembler files
316                  is not documented, and can change between releases.
317
318                from_core:
319                  The  input  file  is  expected to be core code (default file
320                  suffix ".core"). Notice that the format of core files is not
321                  documented, and can change between releases.
322
323                no_spawn_compiler_process:
324                  By default, all code is compiled in a separate process which
325                  is terminated at  the  end  of  compilation.  However,  some
326                  tools,  like Dialyzer or compilers for other BEAM languages,
327                  may already manage their own worker processes  and  spawning
328                  an extra process may slow the compilation down. In such sce‐
329                  narios, you can pass this option to stop the  compiler  from
330                  spawning an additional process.
331
332                no_strict_record_tests:
333                  This option is not recommended.
334
335                  By    default,    the    generated    code   for   operation
336                  Record#record_tag.field verifies that the tuple  Record  has
337                  the  correct size for the record, and that the first element
338                  is the tag record_tag. Use this option to omit the verifica‐
339                  tion code.
340
341                no_error_module_mismatch:
342                  Normally the compiler verifies that the module name given in
343                  the source code is the same as the base name of  the  output
344                  file  and  refuses  to generate an output file if there is a
345                  mismatch. If you have a good reason (or  other  reason)  for
346                  having  a  module  name  unrelated to the name of the output
347                  file, this option disables that verification (there will not
348                  even be a warning if there is a mismatch).
349
350                {no_auto_import,[{F,A}, ...]}:
351                  Makes  the  function  F/A no longer being auto-imported from
352                  the erlang module, which resolves BIF name clashes. This op‐
353                  tion must be used to resolve name clashes with BIFs auto-im‐
354                  ported before R14A, if it is needed to call the local  func‐
355                  tion with the same name as an auto-imported BIF without mod‐
356                  ule prefix.
357
358            Note:
359                As from R14A and forward, the compiler resolves calls  without
360                module  prefix  to  local  or imported functions before trying
361                with auto-imported BIFs. If the BIF is to be called,  use  the
362                erlang  module prefix in the call, not {no_auto_import,[{F,A},
363                ...]}.
364
365
366                  If this option is written in the source code, as a  -compile
367                  directive,  the syntax F/A can be used instead of {F,A}, for
368                  example:
369
370                -compile({no_auto_import,[error/1]}).
371
372                no_auto_import:
373                  Do not auto-import any functions from erlang module.
374
375                no_line_info:
376                  Omits line number information to produce a slightly  smaller
377                  output file.
378
379                no_lint:
380                  Skips the pass that checks for errors and warnings. Only ap‐
381                  plicable together with the from_abstr option. This is mainly
382                  for  implementations  of  other  languages on top of Erlang,
383                  which have already done their own checks to  guarantee  cor‐
384                  rectness of the code.
385
386                  Caveat:  When  this  option is used, there are no guarantees
387                  that the code output by the compiler is correct and safe  to
388                  use.  The responsibility for correctness lies on the code or
389                  person generating the abstract format. If the code  contains
390                  errors, the compiler may crash or produce unsafe code.
391
392                {extra_chunks, [{binary(), binary()}]}:
393                  Pass  extra chunks to be stored in the .beam file. The extra
394                  chunks must be a list of tuples with a four byte  binary  as
395                  chunk name followed by a binary with the chunk contents. See
396                  beam_lib for more information.
397
398              If warnings are turned on (option report_warnings described ear‐
399              lier),  the following options control what type of warnings that
400              are generated. Except from {warn_format,Verbosity}, the  follow‐
401              ing options have two forms:
402
403                * A warn_xxx form, to turn on the warning.
404
405                * A nowarn_xxx form, to turn off the warning.
406
407              In the descriptions that follow, the form that is used to change
408              the default value are listed.
409
410                {warn_format, Verbosity}:
411                  Causes warnings to be emitted for malformed  format  strings
412                  as arguments to io:format and similar functions.
413
414                  Verbosity selects the number of warnings:
415
416                  * 0 = No warnings
417
418                  * 1 = Warnings for invalid format strings and incorrect num‐
419                    ber of arguments
420
421                  * 2 = Warnings also when the validity cannot be checked, for
422                    example, when the format string argument is a variable.
423
424                  The default verbosity is 1. Verbosity 0 can also be selected
425                  by option nowarn_format.
426
427                nowarn_bif_clash:
428                  This option is removed, it generates a fatal error if used.
429
430            Warning:
431                As from beginning with R14A, the compiler no longer calls  the
432                auto-imported  BIF if the name clashes with a local or explic‐
433                itly imported function, and a  call  without  explicit  module
434                name  is  issued.  Instead,  the local or imported function is
435                called. Still accepting nowarn_bif_clash would make  a  module
436                calling  functions  clashing  with  auto-imported BIFs compile
437                with both the old and new compilers, but with completely  dif‐
438                ferent semantics. This is why the option is removed.
439
440                The  use  of  this option has always been discouraged. As from
441                R14A, it is an error to use it.
442
443                To resolve BIF clashes,  use  explicit  module  names  or  the
444                {no_auto_import,[F/A]} compiler directive.
445
446
447                {nowarn_bif_clash, FAs}:
448                  This option is removed, it generates a fatal error if used.
449
450            Warning:
451                The  use  of  this option has always been discouraged. As from
452                R14A, it is an error to use it.
453
454                To resolve BIF clashes,  use  explicit  module  names  or  the
455                {no_auto_import,[F/A]} compiler directive.
456
457
458                nowarn_export_all:
459                  Turns  off  warnings  for uses of the export_all option. De‐
460                  fault is to emit a warning  if  option  export_all  is  also
461                  given.
462
463                warn_export_vars:
464                  Emits  warnings  for  all  implicitly exported variables re‐
465                  ferred to after the primitives where  they  were  first  de‐
466                  fined.  By default, the compiler only emits warnings for ex‐
467                  ported variables referred to in a pattern.
468
469                nowarn_shadow_vars:
470                  Turns off warnings for "fresh" variables in  functional  ob‐
471                  jects  or list comprehensions with the same name as some al‐
472                  ready defined variable. Default is to emit warnings for such
473                  variables.
474
475                nowarn_unused_function:
476                  Turns off warnings for unused local functions. Default is to
477                  emit warnings for all local functions that  are  not  called
478                  directly or indirectly by an exported function. The compiler
479                  does not include unused local  functions  in  the  generated
480                  beam  file,  but  the  warning  is  still useful to keep the
481                  source code cleaner.
482
483                {nowarn_unused_function, FAs}:
484                  Turns  off  warnings  for  unused   local   functions   like
485                  nowarn_unused_function  does, but only for the mentioned lo‐
486                  cal functions. FAs is a tuple {Name,Arity} or a list of such
487                  tuples.
488
489                nowarn_deprecated_function:
490                  Turns  off  warnings  for calls to deprecated functions. De‐
491                  fault is to emit warnings for every call to a function known
492                  by  the  compiler to be deprecated. Notice that the compiler
493                  does not know about attribute -deprecated(), but uses an as‐
494                  sembled  list of deprecated functions in Erlang/OTP. To do a
495                  more general check, the Xref tool  can  be  used.  See  also
496                  xref(3)  and  the function xref:m/1, also accessible through
497                  the function c:xm/1.
498
499                {nowarn_deprecated_function, MFAs}:
500                  Turns off warnings for calls to  deprecated  functions  like
501                  nowarn_deprecated_function  does, but only for the mentioned
502                  functions. MFAs is a tuple {Module,Name,Arity} or a list  of
503                  such tuples.
504
505                nowarn_deprecated_type:
506                  Turns  off  warnings for use of deprecated types. Default is
507                  to emit warnings for every use of a type known by  the  com‐
508                  piler to be deprecated.
509
510                nowarn_removed:
511                  Turns off warnings for calls to functions that have been re‐
512                  moved. Default is to emit warnings for every call to a func‐
513                  tion  known  by  the  compiler to have been recently removed
514                  from Erlang/OTP.
515
516                {nowarn_removed, ModulesOrMFAs}:
517                  Turns off warnings for calls to modules  or  functions  that
518                  have  been  removed.  Default  is to emit warnings for every
519                  call to a function known by the compiler to  have  been  re‐
520                  cently removed from Erlang/OTP.
521
522                nowarn_obsolete_guard:
523                  Turns  off warnings for calls to old type testing BIFs, such
524                  as pid/1 and list/1. See the Erlang Reference Manual  for  a
525                  complete  list  of  type  testing BIFs and their old equiva‐
526                  lents. Default is to emit warnings for  calls  to  old  type
527                  testing BIFs.
528
529                warn_unused_import:
530                  Emits  warnings for unused imported functions. Default is to
531                  emit no warnings for unused imported functions.
532
533                nowarn_underscore_match:
534                  By default, warnings are emitted when a variable that begins
535                  with  an  underscore  is matched after being bound. Use this
536                  option to turn off this kind of warning.
537
538                nowarn_unused_vars:
539                  By default, warnings are emitted for unused  variables,  ex‐
540                  cept  for  variables  beginning  with an underscore ("Prolog
541                  style warnings"). Use this option to turn off this  kind  of
542                  warning.
543
544                nowarn_unused_record:
545                  Turns off warnings for unused record definitions. Default is
546                  to emit warnings for unused locally defined records.
547
548                {nowarn_unused_record, RecordNames}:
549                  Turns off warnings for unused record definitions. Default is
550                  to emit warnings for unused locally defined records.
551
552                nowarn_unused_type:
553                  Turns  off warnings for unused type declarations. Default is
554                  to emit warnings for unused local type declarations.
555
556                nowarn_nif_inline:
557                  By default, warnings are emitted when inlining is enabled in
558                  a  module that may load NIFs, as the compiler may inline NIF
559                  fallbacks by accident. Use this option to turn off this kind
560                  of warnings.
561
562                warn_missing_spec:
563                  By  default,  warnings  are not emitted when a specification
564                  (or contract) for an exported function  is  not  given.  Use
565                  this option to turn on this kind of warning.
566
567                warn_missing_spec_all:
568                  By  default,  warnings  are not emitted when a specification
569                  (or contract) for an exported or unexported function is  not
570                  given. Use this option to turn on this kind of warning.
571
572              Other  kinds  of  warnings  are opportunistic warnings. They are
573              generated when the compiler happens to notice  potential  issues
574              during optimization and code generation.
575
576          Note:
577              The  compiler does not warn for expressions that it does not at‐
578              tempt to optimize. For example, the compiler will emit a warning
579              for  1/0  but  not for X/0, because 1/0 is a constant expression
580              that the compiler will attempt to evaluate.
581
582              The absence of warnings does not mean that there are no  remain‐
583              ing errors in the code.
584
585
586              Opportunistic  warnings  can be disabled using the following op‐
587              tions:
588
589                nowarn_opportunistic:
590                  Disable all opportunistic warnings.
591
592                nowarn_failed:
593                  Disable warnings for expressions that will always fail (such
594                  as atom+42).
595
596                nowarn_ignored:
597                  Disable warnings for expressions whose values are ignored.
598
599                nowarn_nomatch:
600                  Disable warnings for patterns that will never match (such as
601                  a=b) and for guards that always evaluate to false.
602
603          Note:
604              All options, except the include  path  ({i,Dir}),  can  also  be
605              given  in the file with attribute -compile([Option,...]). Attri‐
606              bute -compile() is allowed after the function definitions.
607
608
609          Note:
610              Before OTP 22, the option {nowarn_deprecated_function, MFAs} was
611              only  recognized  when  given  in  the file with attribute -com‐
612              pile(). (The option {nowarn_unused_function,FAs} was incorrectly
613              documented to only work in a file, but it also worked when given
614              in the option list.) Starting from OTP 22, all options that  can
615              be given in the file can also be given in the option list.
616
617
618              For debugging of the compiler, or for pure curiosity, the inter‐
619              mediate code generated by each compiler pass can  be  inspected.
620              To  print  a complete list of the options to produce list files,
621              type compile:options() at the Erlang shell prompt.  The  options
622              are  printed  in the order that the passes are executed. If more
623              than one listing option is used, the one representing the earli‐
624              est pass takes effect.
625
626              Unrecognized options are ignored.
627
628              Both WarningList and ErrorList have the following format:
629
630              [{FileName,[ErrorInfo]}].
631
632              ErrorInfo  is  described  later in this section. The filename is
633              included here, as the compiler  uses  the  Erlang  pre-processor
634              epp,  which allows the code to be included in other files. It is
635              therefore important to know to which file the location of an er‐
636              ror or a warning refers.
637
638       forms(Forms)
639
640              Is  the same as forms(Forms, [verbose,report_errors,report_warn‐
641              ings]).
642
643       forms(Forms, Options) -> CompRet
644
645              Types:
646
647                 Forms = forms()
648                 forms() = [erl_parse:abstract_form] | cerl:c_module()
649                 Options = [option()]
650                 CompRet = BinRet | ErrRet
651                 BinRet = {ok,ModuleName,BinaryOrCode} |  {ok,ModuleName,Bina‐
652                 ryOrCode,Warnings}
653                 ModuleName = module()
654                 BinaryOrCode = binary() | term()
655                 ErrRet = error | {error,Errors,Warnings}
656                 Warnings  = Errors = [{file:filename(), [{erl_anno:location()
657                 | 'none', module(), term()}]}]
658
659              Analogous to file/1, but takes a list of forms (in either Erlang
660              abstract  or  Core  Erlang format representation) as first argu‐
661              ment. Option binary is implicit, that is, no object code file is
662              produced. For options that normally produce a listing file, such
663              as 'E', the internal format for that compiler  pass  (an  Erlang
664              term, usually not a binary) is returned instead of a binary.
665
666       format_error(ErrorDescriptor) -> chars()
667
668              Types:
669
670                 ErrorDescriptor = errordesc()
671
672              Uses  an  ErrorDescriptor  and returns a deep list of characters
673              that describes the error. This function is  usually  called  im‐
674              plicitly when an ErrorInfo structure (described in section Error
675              Information) is processed.
676
677       output_generated(Options) -> true | false
678
679              Types:
680
681                 Options = [term()]
682
683              Determines whether the compiler generates a beam file  with  the
684              given  options.  true means that a beam file is generated. false
685              means that the compiler generates some listing file,  returns  a
686              binary, or merely checks the syntax of the source code.
687
688       noenv_file(File, Options) -> CompRet
689
690              Works like file/2, except that the environment variable ERL_COM‐
691              PILER_OPTIONS is not consulted.
692
693       noenv_forms(Forms, Options) -> CompRet
694
695              Works  like  forms/2,  except  that  the  environment   variable
696              ERL_COMPILER_OPTIONS is not consulted.
697
698       noenv_output_generated(Options) -> true | false
699
700              Types:
701
702                 Options = [term()]
703
704              Works like output_generated/1, except that the environment vari‐
705              able ERL_COMPILER_OPTIONS is not consulted.
706

DEFAULT COMPILER OPTIONS

708       The (host operating system) environment  variable  ERL_COMPILER_OPTIONS
709       can be used to give default compiler options. Its value must be a valid
710       Erlang term. If the value is a list, it is used as is. If it is  not  a
711       list, it is put into a list.
712
713       The  list is appended to any options given to file/2, forms/2, and out‐
714       put_generated/2.   Use   the   alternative   functions    noenv_file/2,
715       noenv_forms/2, or noenv_output_generated/2 if you do not want the envi‐
716       ronment variable to be consulted, for example, if you are  calling  the
717       compiler recursively from inside a parse transform.
718
719       The list can be retrieved with env_compiler_options/0.
720

INLINING

722       The compiler can do function inlining within an Erlang module. Inlining
723       means that a call to a function is replaced with the function body with
724       the  arguments  replaced with the actual values. The semantics are pre‐
725       served, except if exceptions are generated in the inlined code.  Excep‐
726       tions  are  reported  as occurring in the function the body was inlined
727       into.  Also,  function_clause  exceptions  are  converted  to   similar
728       case_clause exceptions.
729
730       When  a function is inlined, the original function is kept if it is ex‐
731       ported (either by an explicit export or if the  option  export_all  was
732       given) or if not all calls to the function are inlined.
733
734       Inlining does not necessarily improve running time. For example, inlin‐
735       ing can increase Beam stack use, which probably is detrimental to  per‐
736       formance for recursive functions.
737
738       Inlining  is  never  default. It must be explicitly enabled with a com‐
739       piler option or a -compile() attribute in the source module.
740
741       To enable inlining, either use the option inline to  let  the  compiler
742       decide  which  functions  to  inline, or {inline,[{Name,Arity},...]} to
743       have the compiler inline all calls to the given functions. If  the  op‐
744       tion is given inside a compile directive in an Erlang module, {Name,Ar‐
745       ity} can be written as Name/Arity.
746
747       Example of explicit inlining:
748
749       -compile({inline,[pi/0]}).
750
751       pi() -> 3.1416.
752
753
754       Example of implicit inlining:
755
756       -compile(inline).
757
758       The option {inline_size,Size} controls how large functions that are al‐
759       lowed to be inlined. Default is 24, which keeps the size of the inlined
760       code roughly the same as the un-inlined version (only relatively  small
761       functions are inlined).
762
763       Example:
764
765       %% Aggressive inlining - will increase code size.
766       -compile(inline).
767       -compile({inline_size,100}).
768

INLINING OF LIST FUNCTIONS

770       The  compiler  can also inline various list manipulation functions from
771       the module list in STDLIB.
772
773       This feature must be explicitly enabled with a  compiler  option  or  a
774       -compile() attribute in the source module.
775
776       To enable inlining of list functions, use option inline_list_funcs.
777
778       The following functions are inlined:
779
780         * lists:all/2
781
782         * lists:any/2
783
784         * lists:foreach/2
785
786         * lists:map/2
787
788         * lists:flatmap/2
789
790         * lists:filter/2
791
792         * lists:foldl/3
793
794         * lists:foldr/3
795
796         * lists:mapfoldl/3
797
798         * lists:mapfoldr/3
799

PARSE TRANSFORMATIONS

801       Parse  transformations  are  used when a programmer wants to use Erlang
802       syntax but with different semantics. The original Erlang code  is  then
803       transformed into other Erlang code.
804
805       See  erl_id_trans(3)  for an example and an explanation of the function
806       parse_transform_info/0.
807

ERROR INFORMATION

809       The ErrorInfo mentioned earlier is the  standard  ErrorInfo  structure,
810       which is returned from all I/O modules. It has the following format:
811
812       {ErrorLocation, Module, ErrorDescriptor}
813
814       ErrorLocation  is  the  atom none if the error does not correspond to a
815       specific location, for example, if the source file does not exist.
816
817       A string describing the error is obtained with the following call:
818
819       Module:format_error(ErrorDescriptor)
820

SEE ALSO

822       epp(3), erl_id_trans(3), erl_lint(3), beam_lib(3)
823
824
825
826Ericsson AB                     compiler 8.1.1                      compile(3)
Impressum