<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2011</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 syntax
      <c>fun Module:FunctionName/Arity</c> should be used.</p>
  </section>

  <section>
    <marker id="on_load"></marker>
    <title>Running a function when a module is loaded</title>

    <warning>
    <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>
    </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>ok</c> 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 <c>on_load</c>
    function has not yet returned will be suspended until the <c>on_load</c>
    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
      <c>ok</c></p>.

    <p>Example:</p>

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

    <p>If the call to <c>erlang:load_nif/2</c> fails, the module
      will be unloaded and there will be warning report sent to
      the error loader.</p>

  </section>

</chapter>

