<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../otp_doc.css" type="text/css">
<title>Erlang -- Compilation and Code Loading</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="../pdf/otp-system-documentation-5.9.3.1.pdf">PDF</a><br><a href="../index.html">Top</a></small><p><strong>Erlang Reference Manual</strong><br><strong>User's Guide</strong><br><small>Version 5.9.3.1</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="introduction.html">
Top of chapter
</a></li>
<li title="Purpose"><a href="introduction.html#id73748">Purpose</a></li>
<li title="Prerequisites"><a href="introduction.html#id66106">Prerequisites</a></li>
<li title="Document Conventions"><a href="introduction.html#id67296">Document Conventions</a></li>
<li title="Complete List of BIFs"><a href="introduction.html#id68121">Complete List of BIFs</a></li>
<li title="Reserved Words"><a href="introduction.html#id60679">Reserved Words</a></li>
<li title="Character Set"><a href="introduction.html#id61758">Character Set</a></li>
</ul>
</li>
<li id="no" title="Data Types" expanded="false">Data Types<ul>
<li><a href="data_types.html">
Top of chapter
</a></li>
<li title="Terms"><a href="data_types.html#id63330">Terms</a></li>
<li title="Number"><a href="data_types.html#id68697">Number</a></li>
<li title="Atom"><a href="data_types.html#id62285">Atom</a></li>
<li title="Bit Strings and Binaries"><a href="data_types.html#id68011">Bit Strings and Binaries</a></li>
<li title="Reference"><a href="data_types.html#id58120">Reference</a></li>
<li title="Fun"><a href="data_types.html#id67499">Fun</a></li>
<li title="Port Identifier"><a href="data_types.html#id69290">Port Identifier</a></li>
<li title="Pid"><a href="data_types.html#id60853">Pid</a></li>
<li title="Tuple"><a href="data_types.html#id73719">Tuple</a></li>
<li title="List"><a href="data_types.html#id73198">List</a></li>
<li title="String"><a href="data_types.html#id68626">String</a></li>
<li title="Record"><a href="data_types.html#id65682">Record</a></li>
<li title="Boolean"><a href="data_types.html#id67471">Boolean</a></li>
<li title="Escape Sequences"><a href="data_types.html#id73885">Escape Sequences</a></li>
<li title="Type Conversions"><a href="data_types.html#id69219">Type Conversions</a></li>
</ul>
</li>
<li id="no" title="Pattern Matching" expanded="false">Pattern Matching<ul>
<li><a href="patterns.html">
Top of chapter
</a></li>
<li title="Pattern Matching"><a href="patterns.html#id68202">Pattern Matching</a></li>
</ul>
</li>
<li id="no" title="Modules" expanded="false">Modules<ul>
<li><a href="modules.html">
Top of chapter
</a></li>
<li title="Module Syntax"><a href="modules.html#id68326">Module Syntax</a></li>
<li title="Module Attributes"><a href="modules.html#id68358">Module Attributes</a></li>
<li title="Comments"><a href="modules.html#id74337">Comments</a></li>
<li title="The module_info/0 and module_info/1 functions"><a href="modules.html#id74350">The module_info/0 and module_info/1 functions</a></li>
</ul>
</li>
<li id="no" title="Functions" expanded="false">Functions<ul>
<li><a href="functions.html">
Top of chapter
</a></li>
<li title="Function Declaration Syntax"><a href="functions.html#id74609">Function Declaration Syntax</a></li>
<li title="Function Evaluation"><a href="functions.html#id74724">Function Evaluation</a></li>
<li title="Tail recursion"><a href="functions.html#id74875">Tail recursion</a></li>
<li title="Built-In Functions, BIFs"><a href="functions.html#id74908">Built-In Functions, BIFs</a></li>
</ul>
</li>
<li id="no" title="Types and Function Specifications" expanded="false">Types and Function Specifications<ul>
<li><a href="typespec.html">
Top of chapter
</a></li>
<li title="Introduction of Types"><a href="typespec.html#id75024">Introduction of Types</a></li>
<li title="Types and their Syntax"><a href="typespec.html#id75072">Types and their Syntax</a></li>
<li title="Type declarations of user-defined types"><a href="typespec.html#id75688">Type declarations of user-defined types</a></li>
<li title="Type information in record declarations"><a href="typespec.html#id75770">Type information in record declarations</a></li>
<li title="Specifications for functions"><a href="typespec.html#id75847">Specifications for functions</a></li>
</ul>
</li>
<li id="no" title="Expressions" expanded="false">Expressions<ul>
<li><a href="expressions.html">
Top of chapter
</a></li>
<li title="Expression Evaluation"><a href="expressions.html#id76067">Expression Evaluation</a></li>
<li title="Terms"><a href="expressions.html#id76110">Terms</a></li>
<li title="Variables"><a href="expressions.html#id76122">Variables</a></li>
<li title="Patterns"><a href="expressions.html#id76253">Patterns</a></li>
<li title="Match"><a href="expressions.html#id76372">Match</a></li>
<li title="Function Calls"><a href="expressions.html#id76431">Function Calls</a></li>
<li title="If"><a href="expressions.html#id76631">If</a></li>
<li title="Case"><a href="expressions.html#id76696">Case</a></li>
<li title="Send"><a href="expressions.html#id76761">Send</a></li>
<li title="Receive"><a href="expressions.html#id76844">Receive</a></li>
<li title="Term Comparisons"><a href="expressions.html#id77009">Term Comparisons</a></li>
<li title="Arithmetic Expressions"><a href="expressions.html#id77270">Arithmetic Expressions</a></li>
<li title="Boolean Expressions"><a href="expressions.html#id77776">Boolean Expressions</a></li>
<li title="Short-Circuit Expressions"><a href="expressions.html#id77931">Short-Circuit Expressions</a></li>
<li title="List Operations"><a href="expressions.html#id78047">List Operations</a></li>
<li title="Bit Syntax Expressions"><a href="expressions.html#id78116">Bit Syntax Expressions</a></li>
<li title="Fun Expressions"><a href="expressions.html#id78658">Fun Expressions</a></li>
<li title="Catch and Throw"><a href="expressions.html#id78840">Catch and Throw</a></li>
<li title="Try"><a href="expressions.html#id78986">Try</a></li>
<li title="Parenthesized Expressions"><a href="expressions.html#id79344">Parenthesized Expressions</a></li>
<li title="Block Expressions"><a href="expressions.html#id79376">Block Expressions</a></li>
<li title="List Comprehensions"><a href="expressions.html#id79401">List Comprehensions</a></li>
<li title="Bit String Comprehensions"><a href="expressions.html#id79541">Bit String Comprehensions</a></li>
<li title="Guard Sequences"><a href="expressions.html#id79673">Guard Sequences</a></li>
<li title="Operator Precedence"><a href="expressions.html#id80211">Operator Precedence</a></li>
</ul>
</li>
<li id="no" title="The Preprocessor" expanded="false">The Preprocessor<ul>
<li><a href="macros.html">
Top of chapter
</a></li>
<li title="File Inclusion"><a href="macros.html#id80530">File Inclusion</a></li>
<li title="Defining and Using Macros"><a href="macros.html#id80659">Defining and Using Macros</a></li>
<li title="Predefined Macros"><a href="macros.html#id80782">Predefined Macros</a></li>
<li title="Macros Overloading"><a href="macros.html#id80850">Macros Overloading</a></li>
<li title="Flow Control in Macros"><a href="macros.html#id80919">Flow Control in Macros</a></li>
<li title="Stringifying Macro Arguments"><a href="macros.html#id81056">Stringifying Macro Arguments</a></li>
</ul>
</li>
<li id="no" title="Records" expanded="false">Records<ul>
<li><a href="records.html">
Top of chapter
</a></li>
<li title="Defining Records"><a href="records.html#id81178">Defining Records</a></li>
<li title="Creating Records"><a href="records.html#id81209">Creating Records</a></li>
<li title="Accessing Record Fields"><a href="records.html#id81264">Accessing Record Fields</a></li>
<li title="Updating Records"><a href="records.html#id81303">Updating Records</a></li>
<li title="Records in Guards"><a href="records.html#id81336">Records in Guards</a></li>
<li title="Records in Patterns"><a href="records.html#id81368">Records in Patterns</a></li>
<li title="Nested records"><a href="records.html#id81395">Nested records</a></li>
<li title="Internal Representation of Records"><a href="records.html#id81430">Internal Representation of Records</a></li>
</ul>
</li>
<li id="no" title="Errors and Error Handling" expanded="false">Errors and Error Handling<ul>
<li><a href="errors.html">
Top of chapter
</a></li>
<li title="Terminology"><a href="errors.html#id81550">Terminology</a></li>
<li title="Exceptions"><a href="errors.html#id81678">Exceptions</a></li>
<li title="Handling of Run-Time Errors in Erlang"><a href="errors.html#id81851">Handling of Run-Time Errors in Erlang</a></li>
<li title="Exit Reasons"><a href="errors.html#id81913">Exit Reasons</a></li>
</ul>
</li>
<li id="no" title="Processes" expanded="false">Processes<ul>
<li><a href="processes.html">
Top of chapter
</a></li>
<li title="Processes"><a href="processes.html#id82387">Processes</a></li>
<li title="Process Creation"><a href="processes.html#id82400">Process Creation</a></li>
<li title="Registered Processes"><a href="processes.html#id82449">Registered Processes</a></li>
<li title="Process Termination"><a href="processes.html#id82560">Process Termination</a></li>
<li title="Message Sending"><a href="processes.html#id82650">Message Sending</a></li>
<li title="Links"><a href="processes.html#id82679">Links</a></li>
<li title="Error Handling"><a href="processes.html#id82744">Error Handling</a></li>
<li title="Monitors"><a href="processes.html#id82854">Monitors</a></li>
<li title="Process Dictionary"><a href="processes.html#id82946">Process Dictionary</a></li>
</ul>
</li>
<li id="no" title="Distributed Erlang" expanded="false">Distributed Erlang<ul>
<li><a href="distributed.html">
Top of chapter
</a></li>
<li title="Distributed Erlang System"><a href="distributed.html#id83013">Distributed Erlang System</a></li>
<li title="Nodes"><a href="distributed.html#id83044">Nodes</a></li>
<li title="Node Connections"><a href="distributed.html#id83114">Node Connections</a></li>
<li title="epmd"><a href="distributed.html#id83164">epmd</a></li>
<li title="Hidden Nodes"><a href="distributed.html#id83184">Hidden Nodes</a></li>
<li title="C Nodes"><a href="distributed.html#id83230">C Nodes</a></li>
<li title="Security"><a href="distributed.html#id83254">Security</a></li>
<li title="Distribution BIFs"><a href="distributed.html#id83364">Distribution BIFs</a></li>
<li title="Distribution Command Line Flags"><a href="distributed.html#id83662">Distribution Command Line Flags</a></li>
<li title="Distribution Modules"><a href="distributed.html#id83799">Distribution Modules</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Compilation and Code Loading" expanded="true">Compilation and Code Loading<ul>
<li><a href="code_loading.html">
Top of chapter
</a></li>
<li title="Compilation"><a href="code_loading.html#id84002">Compilation</a></li>
<li title="Code Loading"><a href="code_loading.html#id84112">Code Loading</a></li>
<li title="Code Replacement"><a href="code_loading.html#id84159">Code Replacement</a></li>
<li title="Running a function when a module is loaded"><a href="code_loading.html#id84234">Running a function when a module is loaded</a></li>
</ul>
</li>
<li id="no" title="Ports and Port Drivers" expanded="false">Ports and Port Drivers<ul>
<li><a href="ports.html">
Top of chapter
</a></li>
<li title="Ports"><a href="ports.html#id84374">Ports</a></li>
<li title="Port Drivers"><a href="ports.html#id84409">Port Drivers</a></li>
<li title="Port BIFs"><a href="ports.html#id84449">Port BIFs</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>13 Compilation and Code Loading</h1>
<p>How code is compiled and loaded is not a language issue, but
is system dependent. This chapter describes compilation and
code loading in Erlang/OTP with pointers to relevant parts of
the documentation.</p>
<h3><a name="id84002">13.1
Compilation</a></h3>
<p>Erlang programs must be <strong>compiled</strong> to object code.
The compiler can generate a new file which contains the object
code. The current abstract machine which runs the object code is
called BEAM, therefore the object files get the suffix
<span class="code">.beam</span>. The compiler can also generate a binary which can
be loaded directly.</p>
<p>The compiler is located in the Kernel module <span class="code">compile</span>, see
<span class="code">compile(3)</span>.</p>
<div class="example"><pre>
compile:file(Module)
compile:file(Module, Options)</pre></div>
<p>The Erlang shell understands the command <span class="code">c(Module)</span> which
both compiles and loads <span class="code">Module</span>.</p>
<p>There is also a module <span class="code">make</span> which provides a set of
functions similar to the UNIX type Make functions, see
<span class="code">make(3)</span>.</p>
<p>The compiler can also be accessed from the OS prompt, see
<span class="code">erl(1)</span>.</p>
<div class="example"><pre>
% erl -compile <span class="bold_code">Module1</span>...<span class="bold_code">ModuleN</span>
% erl -make</pre></div>
<p>The <span class="code">erlc</span> program provides an even better way to compile
modules from the shell, see <span class="code">erlc(1)</span>. It understands a
number of flags that can be used to define macros, add search
paths for include files, and more.</p>
<div class="example"><pre>
% erlc <span class="bold_code"><flags></span> <span class="bold_code">File1.erl</span>...<span class="bold_code">FileN.erl</span></pre></div>
<h3><a name="id84112">13.2
Code Loading</a></h3>
<a name="loading"></a>
<p>The object code must be <strong>loaded</strong> into the Erlang runtime
system. This is handled by the <strong>code server</strong>, see
<span class="code">code(3)</span>.</p>
<p>The code server loads code according to a code loading strategy
which is either <strong>interactive</strong> (default) or
<strong>embedded</strong>. In interactive mode, code are searched for in
a <strong>code path</strong> and loaded when first referenced. In
embedded mode, code is loaded at start-up according to a <strong>boot script</strong>. This is described in <strong>System Principles</strong>.</p>
<h3><a name="id84159">13.3
Code Replacement</a></h3>
<p>Erlang supports change of code in a running system. Code
replacement is done on module level.</p>
<p>The code of a module can exist in two variants in a system:
<strong>current</strong> and <strong>old</strong>. When a module is loaded into
the system for the first time, the code becomes 'current'. If then
a new instance of the module is loaded, the code of the previous
instance becomes 'old' and the new instance becomes 'current'.</p>
<p>Both old and current code is valid, and may be evaluated
concurrently. Fully qualified function calls always refer to
current code. Old code may still be evaluated because of processes
lingering in the old code.</p>
<p>If a third instance of the module is loaded, the code server will
remove (purge) the old code and any processes lingering in it will
be terminated. Then the third instance becomes 'current' and
the previously current code becomes 'old'.</p>
<p>To change from old code to current code, a process must make a
fully qualified function call. Example:</p>
<div class="example"><pre>
-module(m).
-export([loop/0]).
loop() ->
receive
code_switch ->
m:loop();
Msg ->
...
loop()
end.</pre></div>
<p>To make the process change code, send the message
<span class="code">code_switch</span> to it. The process then will make a fully
qualified call to <span class="code">m:loop()</span> and change to current code.
Note that <span class="code">m:loop/0</span> must be exported.</p>
<p>For code replacement of funs to work, the syntax
<span class="code">fun Module:FunctionName/Arity</span> should be used.</p>
<h3><a name="id84234">13.4
Running a function when a module is loaded</a></h3>
<a name="on_load"></a>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p>
<p>This section describes an experimental feature that was
introduced in R13B03, and changed in a backwards-incompatible
way in R13B04. There may be more backward-incompatible changes
in future releases.</p>
</p></div>
</div>
<p>The <span class="code">-on_load()</span> directive names a function that should
be run automatically when a module a loaded. Its syntax is:</p>
<div class="example"><pre>
-on_load(Name/0).</pre></div>
<p>It is not necessary to export the function. It will be called in a
freshly spawned process (which will be terminated as soon as the function
returns). The function must return <span class="code">ok</span> if the module is to
be remained loaded and become callable, or any other value if the module
is to be unloaded. Generating an exception will also cause the
module to be unloaded. If the return value is not an atom,
a warning error report will be sent to the error logger.</p>
<p>A process that calls any function in a module whose <span class="code">on_load</span>
function has not yet returned will be suspended until the <span class="code">on_load</span>
function has returned.</p>
<p>In embedded mode, all modules will be loaded first and then
will all on_load functions be called. The system will be
terminated unless all of the on_load functions return
<span class="code">ok</span></p>.
<p>Example:</p>
<div class="example"><pre>
-module(m).
-on_load(load_my_nifs/0).
load_my_nifs() ->
NifPath = ..., %Set up the path to the NIF library.
Info = ..., %Initialize the Info term
erlang:load_nif(NifPath, Info).</pre></div>
<p>If the call to <span class="code">erlang:load_nif/2</span> fails, the module
will be unloaded and there will be warning report sent to
the error loader.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 2003-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
109
