diff options
Diffstat (limited to 'lib/compiler/doc/src/compile.xml')
| -rw-r--r-- | lib/compiler/doc/src/compile.xml | 743 |
1 files changed, 743 insertions, 0 deletions
diff --git a/lib/compiler/doc/src/compile.xml b/lib/compiler/doc/src/compile.xml new file mode 100644 index 0000000000..c39c9b25eb --- /dev/null +++ b/lib/compiler/doc/src/compile.xml @@ -0,0 +1,743 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1996</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>compile</title> + <prepared>Robert Virding</prepared> + <docno></docno> + <date>1996-11-04</date> + <rev>A</rev> + <file>compile.sgml</file> + </header> + <module>compile</module> + <modulesummary>Erlang Compiler</modulesummary> + <description> + <p>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. + </p> + </description> + + <funcs> + <func> + <name>file(File)</name> + <fsummary>Compile a file</fsummary> + <desc> + <p>Is the same as + <c>file(File, [verbose,report_errors,report_warnings])</c>. + </p> + </desc> + </func> + + <func> + <name>file(File, Options) -> CompRet</name> + <fsummary>Compile a file</fsummary> + <type> + <v>CompRet = ModRet | BinRet | ErrRet</v> + <v>ModRet = {ok,ModuleName} | {ok,ModuleName,Warnings}</v> + <v>BinRet = {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warnings}</v> + <v>ErrRet = error | {error,Errors,Warnings}</v> + </type> + <desc> + <p>Compiles the code in the file <c>File</c>, which is an + Erlang source code file without the <c>.erl</c> extension. + <c>Options</c> determine the behavior of the compiler.</p> + + <p>Returns <c>{ok,ModuleName}</c> if successful, or <c>error</c> + if there are errors. An object code file is created if + the compilation succeeds with no errors. It is considered + to be an error if the module name in the source code is + not the same as the basename of the output file.</p> + + <p>Here follows first all elements of <c>Options</c> that in + some way control the behavior of the compiler.</p> + <taglist> + <tag><c>basic_validation</c></tag> + <item> + <p>This option is fast way to test whether a module will + compile successfully (mainly useful for code generators + that want to verify the code they emit). No code will + generated. If warnings are enabled, warnings generated by + the <c>erl_lint</c> module (such as warnings for unused + variables and functions) will be returned too.</p> + + <p>Use the <c>strong_validation</c> option to generate all + warnings that the compiler would generate.</p> + </item> + + <tag><c>strong_validation</c></tag> + <item> + <p>Similar to the <c>basic_validation</c> option, no code + will be generated, but more compiler passes will be run + to ensure also warnings generated by the optimization + passes are generated (such as clauses that will not match + or expressions that are guaranteed to fail with an + exception at run-time).</p> + </item> + + <tag><c>binary</c></tag> + <item> + <p>Causes the compiler to return the object code in a + binary instead of creating an object file. If successful, + the compiler returns <c>{ok,ModuleName,Binary}</c>.</p> + </item> + + <tag><c>bin_opt_info</c></tag> + <item> + <p>The compiler will emit informational warnings about binary + matching optimizations (both successful and unsuccessful). + See the <em>Efficiency Guide</em> for further information.</p> + </item> + + <tag><c>compressed</c></tag> + <item> + <p>The compiler will compress the generated object code, + which can be useful for embedded systems.</p> + </item> + + <tag><c>debug_info</c></tag> + <item> + <marker id="debug_info"></marker> + <p>Include debug information in the form of abstract code + (see + <seealso marker="erts:absform">The Abstract Format</seealso> + in ERTS User's Guide) in the compiled beam module. Tools + such as Debugger, Xref and Cover require the debug + information to be included.</p> + + <p><em>Warning</em>: Source code can be reconstructed from + the debug information. Use encrypted debug information + (see below) to prevent this.</p> + + <p>See + <seealso marker="stdlib:beam_lib#debug_info">beam_lib(3)</seealso> + for details.</p> + </item> + + <tag><c>{debug_info_key,KeyString}</c></tag> + <item></item> + <tag><c>{debug_info_key,{Mode,KeyString}}</c></tag> + <item> + <marker id="debug_info_key"></marker> + <p>Include debug information, but encrypt it, so that it + cannot be accessed without supplying the key. (To give + the <c>debug_info</c> option as well is allowed, but is + not necessary.) Using this option is a good way to always + have the debug information available during testing, yet + protect the source code.</p> + <p><c>Mode</c> is the type of crypto algorithm to be used + for encrypting the debug information. The default type -- + and currently the only type -- is <c>des3_cbc</c>.</p> + <p>See + <seealso marker="stdlib:beam_lib#debug_info">beam_lib(3)</seealso> + for details.</p> + </item> + + <tag><c>encrypt_debug_info</c></tag> + <item> + <marker id="encrypt_debug_info"></marker> + <p>Like the <c>debug_info_key</c> option above, except that + the key will be read from an <c>.erlang.crypt</c> file. + </p> + + <p>See + <seealso marker="stdlib:beam_lib#debug_info">beam_lib(3)</seealso> + for details.</p> + </item> + + <tag><c>'P'</c></tag> + <item> + <p>Produces a listing of the parsed code after preprocessing + and parse transforms, in the file + <c><![CDATA[<File>.P]]></c>. No object file is produced. + </p> + </item> + + <tag><c>'E'</c></tag> + <item> + <p>Produces a listing of the code after all source code + transformations have been performed, in the file + <c><![CDATA[<File>.E]]></c>. No object file is produced. + </p> + </item> + + <tag><c>'S'</c></tag> + <item> + <p>Produces a listing of the assembler code in the file + <c><![CDATA[<File>.S]]></c>. No object file is produced. + </p> + </item> + + <tag><c>report_errors/report_warnings</c></tag> + <item> + <p>Causes errors/warnings to be printed as they occur.</p> + </item> + + <tag><c>report</c></tag> + <item> + <p>This is a short form for both <c>report_errors</c> and + <c>report_warnings</c>.</p> + </item> + + <tag><c>return_errors</c></tag> + <item> + <p>If this flag is set, then + <c>{error,ErrorList,WarningList}</c> is returned when + there are errors.</p> + </item> + + <tag><c>return_warnings</c></tag> + <item> + <p>If this flag is set, then an extra field containing + <c>WarningList</c> is added to the tuples returned on + success.</p> + </item> + + <tag><c>return</c></tag> + <item> + <p>This is a short form for both <c>return_errors</c> and + <c>return_warnings</c>.</p> + </item> + + <tag><c>verbose</c></tag> + <item> + <p>Causes more verbose information from the compiler + describing what it is doing.</p> + </item> + + <tag><c>{outdir,Dir}</c></tag> + <item> + <p>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.</p> + </item> + + <tag><c>export_all</c></tag> + <item> + <p>Causes all functions in the module to be exported.</p> + </item> + + <tag><c>{i,Dir}</c></tag> + <item> + <p>Add <c>Dir</c> to the list of directories to be searched + when including a file. When encountering an + <c>-include</c> or <c>-include_dir</c> directive, + the compiler searches for header files in the following + directories:</p> + <list type="ordered"> + <item> + <p><c>"."</c>, the current working directory of + the file server;</p> + </item> + <item> + <p>the base name of the compiled file;</p> + </item> + <item> + <p>the directories specified using the <c>i</c> option. + The directory specified last is searched first.</p> + </item> + </list> + </item> + + <tag><c>{d,Macro}</c></tag> + <item></item> + <tag><c>{d,Macro,Value}</c></tag> + <item> + <p>Defines a macro <c>Macro</c> to have the value + <c>Value</c>. The default is <c>true</c>).</p> + </item> + + <tag><c>{parse_transform,Module}</c></tag> + <item> + <p>Causes the parse transformation function + <c>Module:parse_transform/2</c> to be applied to the + parsed code before the code is checked for errors.</p> + </item> + + <tag><c>asm</c></tag> + <item> + <p>The input file is expected to be assembler code (default + file suffix ".S"). Note that the format of assembler files + is not documented, and may change between releases - this + option is primarily for internal debugging use.</p> + </item> + + <tag><c>no_strict_record_tests</c></tag> + <item> + <p>This option is not recommended.</p> + + <p>By default, the generated code for + the <c>Record#record_tag.field</c> operation verifies that + the tuple <c>Record</c> is of the correct size for + the record and that the first element is the tag + <c>record_tag</c>. Use this option to omit + the verification code.</p> + </item> + + <tag><c>no_error_module_mismatch</c></tag> + <item> + <p>Normally the compiler verifies that the module name + given in the source code is the same as the base name + of the output file and refuses to generate an output file + if there is a mismatch. If you have a good reason (or + other reason) for having a module name unrelated to the + name of the output file, this option disables that verification + (there will not even be a warning if there is a mismatch).</p> + </item> + + </taglist> + + <p>If warnings are turned on (the <c>report_warnings</c> option + described above), the following options control what type of + warnings that will be generated. + <marker id="erl_lint_options"></marker> + With the exception of <c>{warn_format,Verbosity}</c> all + options below have two forms; one <c>warn_xxx</c> form to + turn on the warning and one <c>nowarn_xxx</c> form to turn off + the warning. In the description that follows, the form that + is used to change the default value is listed.</p> + + <taglist> + <tag><c>{warn_format, Verbosity}</c></tag> + <item> + <p>Causes warnings to be emitted for malformed format + strings as arguments to <c>io:format</c> and similar + functions. <c>Verbosity</c> selects the amount of + warnings: 0 = no warnings; 1 = warnings for invalid + format strings and incorrect number of arguments; 2 = + warnings also when the validity could not be checked + (for example, when the format string argument is a + variable). The default verbosity is 1. Verbosity 0 can + also be selected by the option <c>nowarn_format</c>.</p> + </item> + + <tag><c>nowarn_bif_clash</c></tag> + <item> + <p>By default, there will be a compilation error if a + module contains an exported function with the same name + as an auto-imported BIF (such as <c>size/1</c>) AND + there is a call to it without a qualifying module name. + The reason is that the BIF will be called, not + the function in the same module. The recommended way to + eliminate that warning is to use a call with a module + name - either <c>erlang</c> to call the BIF or + <c>?MODULE</c> to call the function in the same module. + The warning can also be turned off using this option, + but that is not recommended.</p> + + <p><em>The use of this option is strongly discouraged, + as code that uses it will probably break in a future + major release (R14 or R15).</em></p> + </item> + + <tag><c>{nowarn_bif_clash, FAs}</c></tag> + <item> + <p>Turns off warnings as <c>nowarn_bif_clash</c> but only + for the mentioned local functions. <c>FAs</c> is a tuple + <c>{Name,Arity}</c> or a list of such tuples.</p> + <p><em>The use of this option is strongly discouraged, + as code that uses it will probably break in a future + major release (R14 or R15).</em></p> + </item> + + <tag><c>warn_export_all</c></tag> + <item> + <p>Causes a warning to be emitted if the <c>export_all</c> + option has also been given.</p> + </item> + + <tag><c>warn_export_vars</c></tag> + <item> + <p>Causes warnings to be emitted for all implicitly + exported variables referred to after the primitives + where they were first defined. No warnings for exported + variables unless they are referred to in some pattern, + which is the default, can be selected by the option + <c>nowarn_export_vars</c>.</p> + </item> + + <tag><c>warn_shadow_vars</c></tag> + <item> + <p>Causes warnings to be emitted for "fresh" variables + in functional objects or list comprehensions with the same + name as some already defined variable. The default is to + warn for such variables. No warnings for shadowed + variables can be selected by the option + <c>nowarn_shadow_vars</c>.</p> + </item> + + <tag><c>nowarn_unused_function</c></tag> + <item> + <p>Turns off warnings for unused local functions. + By default (<c>warn_unused_function</c>), warnings are + emitted for all local functions that are not called + directly or indirectly by an exported function. + The compiler does not include unused local functions in + the generated beam file, but the warning is still useful + to keep the source code cleaner.</p> + </item> + + <tag><c>{nowarn_unused_function, FAs}</c></tag> + <item> + <p>Turns off warnings for unused local functions as + <c>nowarn_unused_function</c> but only for the mentioned + local functions. <c>FAs</c> is a tuple <c>{Name,Arity}</c> + or a list of such tuples.</p> + </item> + + <tag><c>nowarn_deprecated_function</c></tag> + <item> + <p>Turns off warnings for calls to deprecated functions. By + default (<c>warn_deprecated_function</c>), warnings are + emitted for every call to a function known by the compiler + to be deprecated. Note that the compiler does not know + about the <c>-deprecated()</c> attribute but uses an + assembled list of deprecated functions in Erlang/OTP. To + do a more general check the <c>Xref</c> tool can be used. + See also + <seealso marker="tools:xref#deprecated_function">xref(3)</seealso> + and the function + <seealso marker="tools:xref#m/1">xref:m/1</seealso> also + accessible through + the <seealso marker="stdlib:c#xm/1">c:xm/1</seealso> + function.</p> + </item> + + <tag><c>{nowarn_deprecated_function, MFAs}</c></tag> + <item> + <p>Turns off warnings for calls to deprecated functions as + <c>nowarn_deprecated_function</c> but only for + the mentioned functions. <c>MFAs</c> is a tuple + <c>{Module,Name,Arity}</c> or a list of such tuples.</p> + </item> + + <tag><c>warn_obsolete_guard</c></tag> + <item> + <p>Causes warnings to be emitted for calls to old type + testing BIFs such as <c>pid/1</c> and <c>list/1</c>. See + the + <seealso marker="doc/reference_manual:expressions#guards">Erlang Reference Manual</seealso> + for a complete list of type testing BIFs and their old + equivalents. No warnings for calls to old type testing + BIFs, which is the default, can be selected by the option + <c>nowarn_obsolete_guard</c>.</p> + </item> + + <tag><c>warn_unused_import</c></tag> + <item> + <p>Causes warnings to be emitted for unused imported + functions. No warnings for unused imported functions, + which is the default, can be selected by the option + <c>nowarn_unused_import</c>. </p> + </item> + + <tag><c>nowarn_unused_vars</c></tag> + <item> + <p>By default, warnings are emitted for variables which + are not used, with the exception of variables beginning + with an underscore ("Prolog style warnings"). + Use this option to turn off this kind of warnings.</p> + </item> + + <tag><c>nowarn_unused_record</c></tag> + <item> + <p>Turns off warnings for unused record types. By + default (<c>warn_unused_records</c>), warnings are + emitted for unused locally defined record types.</p> + </item> + </taglist> + + <p>Another class of warnings is generated by the compiler + during optimization and code generation. They warn about + patterns that will never match (such as <c>a=b</c>), guards + that will always evaluate to false, and expressions that will + always fail (such as <c>atom+42</c>).</p> + + <p>Note that the compiler does not warn for expressions that it + does not attempt to optimize. For instance, the compiler tries + to evaluate <c>1/0</c>, notices that it will cause an + exception and emits a warning. On the other hand, + the compiler is silent about the similar expression + <c>X/0</c>; because of the variable in it, the compiler does + not even try to evaluate and therefore it emits no warnings. + </p> + + <p>Currently, those warnings cannot be disabled (except by + disabling all warnings).</p> + + <warning> + <p>Obviously, the absence of warnings does not mean that + there are no remaining errors in the code.</p> + </warning> + + <p>Note that all the options except the include path + (<c>{i,Dir}</c>) can also be given in the file with a + <c>-compile([Option,...])</c>. attribute. + The <c>-compile()</c> attribute is allowed after function + definitions.</p> + + <p>Note also that the <c>{nowarn_unused_function, FAs}</c>, + <c>{nowarn_bif_clash, FAs}</c>, and + <c>{nowarn_deprecated_function, MFAs}</c> options are only + recognized when given in files. They are not affected by + the <c>warn_unused_function</c>, <c>warn_bif_clash</c>, or + <c>warn_deprecated_function</c> options.</p> + + <p>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 <c>compile:options()</c> 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.</p> + + <p><em>Unrecognized options are ignored.</em></p> + + <p>Both <c>WarningList</c> and <c>ErrorList</c> have + the following format:</p> + <code> +[{FileName,[ErrorInfo]}]. + </code> + + <p><c>ErrorInfo</c> is described below. The file name has been + included here as the compiler uses the Erlang pre-processor + <c>epp</c>, which allows the code to be included in other + files. For this reason, it is important to know to + <em>which</em> file an error or warning line number refers. + </p> + </desc> + </func> + + <func> + <name>forms(Forms)</name> + <fsummary>Compile a list of forms</fsummary> + <desc> + <p>Is the same as + <c>forms(File, [verbose,report_errors,report_warnings])</c>. + </p> + </desc> + </func> + + <func> + <name>forms(Forms, Options) -> CompRet</name> + <fsummary>Compile a list of forms</fsummary> + <type> + <v>Forms = [Form]</v> + <v>CompRet = BinRet | ErrRet</v> + <v>BinRet = {ok,ModuleName,BinaryOrCode} | {ok,ModuleName,BinaryOrCode,Warnings}</v> + <v>BinaryOrCode = binary() | term()</v> + <v>ErrRet = error | {error,Errors,Warnings}</v> + </type> + <desc> + <p>Analogous to <c>file/1</c>, but takes a list of forms (in + the Erlang abstract format representation) as first argument. + The option <c>binary</c> is implicit; i.e., no object code + file is produced. Options that would ordinarily produce a + listing file, such as 'E', will instead cause the internal + format for that compiler pass (an Erlang term; usually not a + binary) to be returned instead of a binary.</p> + </desc> + </func> + + <func> + <name>format_error(ErrorDescriptor) -> chars()</name> + <fsummary>Format an error descriptor</fsummary> + <type> + <v>ErrorDescriptor = errordesc()</v> + </type> + <desc> + <p>Uses an <c>ErrorDescriptor</c> and returns a deep list of + characters which describes the error. This function is + usually called implicitly when an <c>ErrorInfo</c> structure + is processed. See below.</p> + </desc> + </func> + + <func> + <name>output_generated(Options) -> true | false</name> + <fsummary>Determine whether the compile will generate an output file</fsummary> + <type> + <v>Options = [term()]</v> + </type> + <desc> + <p>Determines whether the compiler would generate a <c>beam</c> + file with the given options. <c>true</c> means that a <c>beam</c> + file would be generated; <c>false</c> means that the compiler + would generate some listing file, return a binary, or merely + check the syntax of the source code.</p> + </desc> + </func> + + <func> + <name>noenv_file(File, Options) -> CompRet</name> + <fsummary>Compile a file (ignoring ERL_COMPILER_OPTIONS)</fsummary> + <desc> + <p>Works exactly like <seealso marker="#file/2">file/2</seealso>, + except that the environment variable <c>ERL_COMPILER_OPTIONS</c> + is not consulted.</p> + </desc> + </func> + + <func> + <name>noenv_forms(Forms, Options) -> CompRet</name> + <fsummary>Compile a list of forms (ignoring ERL_COMPILER_OPTIONS)</fsummary> + <desc> + <p>Works exactly like <seealso marker="#forms/2">forms/2</seealso>, + except that the environment variable <c>ERL_COMPILER_OPTIONS</c> + is not consulted.</p> + </desc> + </func> + + <func> + <name>noenv_output_generated(Options) -> true | false</name> + <fsummary>Determine whether the compile will generate an output file (ignoring ERL_COMPILER_OPTIONS)</fsummary> + <type> + <v>Options = [term()]</v> + </type> + <desc> + <p>Works exactly like + <seealso marker="#output_generated/1">output_generated/1</seealso>, + except that the environment variable <c>ERL_COMPILER_OPTIONS</c> + is not consulted.</p> + </desc> + </func> + + </funcs> + + <section> + <title>Default compiler options</title> + <p>The (host operating system) environment variable + <c>ERL_COMPILER_OPTIONS</c> 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 is not a list, it will be put + into a list.</p> + + <p>The list will be appended to any options given to + <seealso marker="#file/2">file/2</seealso>, + <seealso marker="#forms/2">forms/2</seealso>, and + <seealso marker="#output_generated/1">output_generated/2</seealso>. + Use the alternative functions + <seealso marker="#noenv_file/2">noenv_file/2</seealso>, + <seealso marker="#noenv_forms/2">noenv_forms/2</seealso>, or + <seealso marker="#noenv_output_generated/1">noenv_output_generated/2</seealso> + if you don't want the environment variable to be consulted + (for instance, if you are calling the compiler recursively from + inside a parse transform).</p> + </section> + + <section> + <title>Inlining</title> + <p>The compiler can do function inlining within an Erlang + module. Inlining means that a call to a function is replaced with + the function body with the arguments replaced with the actual + values. The semantics are preserved, except if exceptions are + generated in the inlined code. Exceptions will be reported as + occurring in the function the body was inlined into. Also, + <c>function_clause</c> exceptions will be converted to similar + <c>case_clause</c> exceptions.</p> + + <p>When a function is inlined, the original function will be + kept if it is exported (either by an explicit export or if the + <c>export_all</c> option was given) or if not all calls to the + function were inlined.</p> + + <p>Inlining does not necessarily improve running time. + For instance, inlining may increase Beam stack usage which will + probably be detrimental to performance for recursive functions. + </p> + + <p>Inlining is never default; it must be explicitly enabled with a + compiler option or a <c>-compile()</c> attribute in the source + module.</p> + + <p>To enable inlining, either use the <c>inline</c> option to + let the compiler decide which functions to inline or + <c>{inline,[{Name,Arity},...]}</c> to have the compiler inline + all calls to the given functions. If the option is given inside + a <c>compile</c> directive in an Erlang module, <c>{Name,Arity}</c> + may be written as <c>Name/Arity</c>.</p> + + <p>Example of explicit inlining:</p> + + <pre> +-compile({inline,[pi/0]}). + +pi() -> 3.1416. + </pre> + + <p>Example of implicit inlining:</p> + <pre> +-compile(inline). + </pre> + + <p>The <c>{inline_size,Size}</c> option controls how large functions + that are allowed to be inlined. Default is <c>24</c>, which will + keep the size of the inlined code roughly the same as + the un-inlined version (only relatively small functions will be + inlined).</p> + + <p>Example:</p> + <pre> +%% Aggressive inlining - will increase code size. +-compile(inline). +-compile({inline_size,100}). + </pre> + </section> + + <section> + <title>Parse Transformations</title> + + <p>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.</p> + </section> + + <section> + <title>Error Information</title> + + <p>The <c>ErrorInfo</c> mentioned above is the standard + <c>ErrorInfo</c> structure which is returned from all IO modules. + It has the following format:</p> + <code> +{ErrorLine, Module, ErrorDescriptor} + </code> + + <p>A string describing the error is obtained with the following + call:</p> + <code> +apply(Module, format_error, ErrorDescriptor) + </code> + </section> + + <section> + <title>See Also</title> + <p> + <seealso marker="stdlib:epp">epp(3)</seealso>, + <seealso marker="stdlib:erl_id_trans">erl_id_trans(3)</seealso>, + <seealso marker="stdlib:erl_lint">erl_lint(3)</seealso>, + <seealso marker="stdlib:beam_lib">beam_lib(3)</seealso> + </p> + </section> +</erlref> + |