This module provides an interface to the standard Erlang compiler. It can generate either a new file which contains the object code, or return a binary which can be loaded directly.
Is the same as file(File,
[verbose,report_errors,report_warnings])
.
file(File, Options) -> CompRet
CompRet = ModRet | BinRet | ErrRet
ModRet = {ok,ModuleName} | {ok,ModuleName,Warnings}
BinRet = {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warnings}
ErrRet = error | {error,Errors,Warnings}
Compiles the code in the file File
, which is an
Erlang source code file without the .erl
extension. Options
determine the behavior of the compiler.
Returns {ok,ModuleName}
if successful, or
error
if there are errors. An object code file is created if the compilation succeeds with no errors.
As a step in the compilation of Erlang code, erl_lint
is run, resulting in warning and error messages, if appropriate.
The options relevant to the syntactic and semantic controls of
erl_lint
are listed in the documentation of the module
erl_lint
.
The elements of Options
can be selected as
follows:
binary
{ok,ModuleName,Binary}
'P'
<File>.P
.
No object file is produced.
'E'
<File>.E
.
No object file is produced.
'S'
<File>.S
.
No object file is produced.
trace
erlang:trace/3
.
report_errors/report_warnings
report
report_errors
and
report_warnings
.
return_errors
{error,ErrorList,WarningList}
is returned when
there are errors.
return_warnings
WarningList
is added to the tuples returned on
success.
return
return_errors
and
return_warnings
.
verbose
{outdir,Dir}
export_all
{i,Dir}
Dir
to the list of directories to be searched
when including a file.
{d,Macro}
{d,Macro,Value}
Macro
to have the value
Value
. The default is true
).
{parse_transform,Module}
Module:parse_transform/2
to be applied to the
parsed code before the code is checked for errors.
asm
v1
v2
Note that all the options except the include path can also
be given in the file with a -compile([Option,...])
.
attribute.
For debugging of the compiler, or for pure curiosity,
the intermediate code generated by each compiler pass can
be inspected.
A complete list of the options to produce list files can
be printed by typing compile:options()
at the
Erlang shell prompt.
The options will be printed in order that the passes are executed.
If more than one listing option is used, the one representing the
earliest pass takes effect.
Unrecognized options are ignored.
Both WarningList
and ErrorList
have the
following format:
[{FileName,[ErrorInfo]}].
ErrorInfo
is described below. The file name
has been included here as the compiler uses the Erlang
pre-processor epp
, which allows the code to be included in
other files. For this reason, it is important to know to
which file an error or warning line number refers.
Is the same as forms(File,
[verbose,report_errors,report_warnings])
.
forms(Forms, Options) -> CompRet
Forms = [Form]
CompRet = ModRet | BinRet | ErrRet
ModRet = {ok,ModuleName} | {ok,ModuleName,Warnings}
BinRet = {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warnings}
ErrRet = error | {error,Errors,Warnings}
Analogous to file/1
, but takes a list of forms (in the
Erlang abstract format representation) as first argument.
The option binary
is implicit; i.e., no object code file
is produced. If the options indicate that a listing file should
be produced (e.g., 'E'), the module name is taken as the file name.
format_error(ErrorDescriptor) -> string()
ErrorDescriptor = errordesc()
Uses an ErrorDescriptor
and returns a string
which describes the error. This function is usually called
implicitly when an ErrorInfo
structure is processed.
See below.
The (host operating system) environment variable ERL_COMPILER_OPTIONS
can be used to give default compiler options.
Its value must be a valid Erlang term. If the value is a list, it will
be used as is. If it's not a list, it will be put into a list.
The list will be appended to any options given to file/2
or forms/2
.
Example: Setting ERL_COMPILER_OPTIONS
to "[v1]
" will by default
use the old compiler. This default version can be overriden by a v2
option
given to file/2
.
Parse transformations are used when a programmer wants to use Erlang syntax but with different semantics. The original Erlang code is then transformed into other Erlang code.
This type of activity is strongly discouraged.
The ErrorInfo
mentioned above is the standard
ErrorInfo
structure which is returned from all IO
modules. It has the following format
{ErrorLine, Module, ErrorDescriptor}
A string describing the error is obtained with the following call:
apply(Module, format_error, ErrorDescriptor)
epp, erl_id_trans, erl_lint