compile

MODULE

compile

MODULE SUMMARY

Erlang Compiler

DESCRIPTION

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.

EXPORTS

file(File)

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.

The elements of Options can be selected as follows:

binary: Causes the compiler to return the object code in a binary instead of creating an object file. If successful, the compiler returns {ok,ModuleName,Binary}
'P': Produces a listing of the parsed code in the file <File>.P. No object file is produced.
'E': Produces a listing of the pre-processed and expanded code in the file <File>.E. No object file is produced.
'S': Produces a listing of the assembler code in the file <File>.S. No object file is produced.
trace: Produces slightly slower code that can be traced function by function with the use of the BIF erlang:trace/3. For Beam, see the section about the object code format below for more information about the trace option.
report_errors/report_warnings: Causes errors/warnings to be printed as they occur.
report: This is a short form for both report_errors and report_warnings.
return_errors: If this flag is set, then {error,ErrorList,WarningList} is returned when there are errors.
return_warnings: If this flag is set, then an extra field containing WarningList is added to the tuples returned on success.
return: This is a short form for both return_errors and return_warnings.
verbose: Causes more verbose information from the compiler describing what it is doing.
{outdir,Dir}: Sets a new directory for the object code. The current directory is used for output, except when a directory has been specified with this option.
export_all: Causes all functions in the module to be exported.
{i,Dir}: Add Dir to the list of directories to be searched when including a file.
{d,Macro}
{d,Macro,Value}: Defines a macro Macro to have the value Value. The default is true).
{parse_transform,Module}: Causes the parse transformation function Module:parse_transform/2 to be applied to the parsed code before the code is checked for errors.
jam: The compiler will generate code for JAM.
beam: The compiler will generate code for BEAM.

Note that all the options except the include path can also be given in the file with a -compile([Option,...]). attribute.

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.

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.

Parse Transformations

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.

Error Information

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)

Object code format for Beam

The first part of the header for Beam object file is documented here.

Offset 0-5: Contains the byte 16#7F followed by the string "BEAM!". Identifies the file as a Beam file.
Offset 6-7: Version number in big-endian order. If the version number is 48 or higher, the following two fields are present. Lower version don't have them.
Offset 8-11: Big-endian flag word. If the least significant bit of this word is one, function calls to functions in this module can be traced with the help of the trace/3 BIF. The other bits are reserved. Tools that turn the trace bit on or off must preserve the other bits.
Offset 12-15: A big-endian word containing a byte offset to the attribute table located at the end of the file. The attribute table contains all atom-valued attributes from the source file. Each attribute contains the name of the attribute (as a string), followed by '=', followed by the value (the atom as a string), followed by a zero byte. The last attribute is followed by an additional zero byte. Example: If the source file contains -vsn('1.0'), the attribute will be stored like this in the object code: "vsn=1.0\0".

Bugs

If Erlang crashes during compilation, <File>.ja# files may be created in the current directory. Such files can be safely deleted.

compile

MODULE

MODULE SUMMARY

DESCRIPTION

EXPORTS

Parse Transformations

Error Information

Object code format for Beam

See Also

Bugs

AUTHORS