aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/reference_manual/code_loading.xml
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc/reference_manual/code_loading.xml')
-rw-r--r--system/doc/reference_manual/code_loading.xml158
1 files changed, 158 insertions, 0 deletions
diff --git a/system/doc/reference_manual/code_loading.xml b/system/doc/reference_manual/code_loading.xml
new file mode 100644
index 0000000000..8861b3bea5
--- /dev/null
+++ b/system/doc/reference_manual/code_loading.xml
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2003</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>Compilation and Code Loading</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>code_loading.xml</file>
+ </header>
+ <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>
+
+ <section>
+ <title>Compilation</title>
+ <p>Erlang programs must be <em>compiled</em> 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
+ <c>.beam</c>. The compiler can also generate a binary which can
+ be loaded directly.</p>
+ <p>The compiler is located in the Kernel module <c>compile</c>, see
+ <c>compile(3)</c>.</p>
+ <pre>
+compile:file(Module)
+compile:file(Module, Options)</pre>
+ <p>The Erlang shell understands the command <c>c(Module)</c> which
+ both compiles and loads <c>Module</c>.</p>
+ <p>There is also a module <c>make</c> which provides a set of
+ functions similar to the UNIX type Make functions, see
+ <c>make(3)</c>.</p>
+ <p>The compiler can also be accessed from the OS prompt, see
+ <c>erl(1)</c>.</p>
+ <pre>
+% erl -compile <input>Module1</input>...<input>ModuleN</input>
+% erl -make</pre>
+ <p>The <c>erlc</c> program provides an even better way to compile
+ modules from the shell, see <c>erlc(1)</c>. It understands a
+ number of flags that can be used to define macros, add search
+ paths for include files, and more.</p>
+ <pre>
+% erlc <input>&lt;flags&gt;</input> <input>File1.erl</input>...<input>FileN.erl</input></pre>
+ </section>
+
+ <section>
+ <marker id="loading"></marker>
+ <title>Code Loading</title>
+ <p>The object code must be <em>loaded</em> into the Erlang runtime
+ system. This is handled by the <em>code server</em>, see
+ <c>code(3)</c>.</p>
+ <p>The code server loads code according to a code loading strategy
+ which is either <em>interactive</em> (default) or
+ <em>embedded</em>. In interactive mode, code are searched for in
+ a <em>code path</em> and loaded when first referenced. In
+ embedded mode, code is loaded at start-up according to a <em>boot script</em>. This is described in <em>System Principles</em>.</p>
+ </section>
+
+ <section>
+ <title>Code Replacement</title>
+ <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:
+ <em>current</em> and <em>old</em>. 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>
+ <pre>
+-module(m).
+-export([loop/0]).
+
+loop() ->
+ receive
+ code_switch ->
+ m:loop();
+ Msg ->
+ ...
+ loop()
+ end.</pre>
+ <p>To make the process change code, send the message
+ <c>code_switch</c> to it. The process then will make a fully
+ qualified call to <c>m:loop()</c> and change to current code.
+ Note that <c>m:loop/0</c> must be exported.</p>
+ <p>For code replacement of funs to work, the tuple syntax
+ <c>{Module,FunctionName}</c> must be used to represent the fun.</p>
+ </section>
+
+ <section>
+ <title>Running a function when a module is loaded</title>
+
+ <warning>
+ <p>This section describes an experimental feature introduced in R13B03.
+ There may be backward-incompatible changes in the feature in future releases.</p>
+ </warning>
+
+ <p>The <c>-on_load()</c> directive names a function that should
+ be run automatically when a module a loaded. Its syntax is:</p>
+
+<pre>
+-on_load(Name/0).</pre>
+
+ <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 <c>true</c> if the module is to
+ be remained loaded and be callable, or <c>false</c> if the module
+ is to be unloaded. Returning any other value or generating an exception
+ will also cause the module to be unloaded.</p>
+
+ <p>A process that calls any function in a module whose <c>on_load</c>
+ function has not yet returned will be suspended until the <c>on_load</c>
+ function has returned.</p>
+
+ <p>Example:</p>
+
+ <pre>
+-module(m).
+-on_load(run_me/0).
+
+run_me() ->
+ %% Do something with side effects here, for instance load a library
+ %% containing native-implemented functions.
+ true.</pre>
+
+ </section>
+
+</chapter>
+