aboutsummaryrefslogtreecommitdiffstats
path: root/lib/compiler/doc/src/compile.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/compiler/doc/src/compile.xml')
-rw-r--r--lib/compiler/doc/src/compile.xml743
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>
+