The R13B03 release.OTP_R13B03

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>
+