In interactive mode, the code server maintains a search path -- usually called the code path -- consisting of a list of directories, which it searches sequentially when trying to load a module.

Initially, the code path consists of the current working directory and all Erlang object code directories under the library directory $OTPROOT/lib, where $OTPROOT is the installation directory of Erlang/OTP, code:root_dir(). Directories can be named Name[-Vsn] and the code server, by default, chooses the directory with the highest version number among those which have the same Name. The -Vsn suffix is optional. If an ebin directory exists under Name[-Vsn], it is this directory which is added to the code path.

The environment variable ERL_LIBS (defined in the operating system) can be used to define additional library directories that will be handled in the same way as the standard OTP library directory described above, except that directories that do not have an ebin directory will be ignored.

All application directories found in the additional directories will appear before the standard OTP applications, except for the Kernel and STDLIB applications, which will be placed before any additional applications. In other words, modules found in any of the additional library directories will override modules with the same name in OTP, except for modules in Kernel and STDLIB.

The environment variable ERL_LIBS (if defined) should contain a colon-separated (for Unix-like systems) or semicolon-separated (for Windows) list of additional libraries.

Example: On an Unix-like system, ERL_LIBS could be set to /usr/local/jungerl:/home/some_user/my_erlang_lib. (On Windows, use semi-colon as separator.)

The code server incorporates a code path cache. The cache functionality is disabled by default. To activate it, start the emulator with the command line flag -code_path_cache or call code:rehash(). When the cache is created (or updated), the code server searches for modules in the code path directories. This may take some time if the the code path is long. After the cache creation, the time for loading modules in a large system (one with a large directory structure) is significantly reduced compared to having the cache disabled. The code server is able to look up the location of a module from the cache in constant time instead of having to search through the code path directories.

Application resource files (.app files) are also stored in the code path cache. This feature is used by the application controller (see application(3)) to load applications efficiently in large systems.

Note that when the code path cache is created (or updated), any relative directory names in the code path are converted to absolute.

In the current implementation, Erlang archives are ZIP files with .ez extension. Erlang archives may also be enclosed in escript files whose file extension is arbitrary.

Erlang archive files may contain entire Erlang applications or parts of applications. The structure in an archive file is the same as the directory structure for an application. If you for example would create an archive of mnesia-4.4.7, the archive file must be named mnesia-4.4.7.ez and it must contain a top directory with the name mnesia-4.4.7. If the version part of the name is omitted, it must also be omitted in the archive. That is, a mnesia.ez archive must contain a mnesia top directory.

An archive file for an application may for example be created like this:

   zip:create("mnesia-4.4.7.ez", 
              ["mnesia-4.4.7"], 
              [{cwd, code:lib_dir()},
               {compress, all},
               {uncompress,[".beam",".app"]}]).

Any file in the archive may be compressed, but in order to speed up the access of frequently read files, it may be a good idea to store beam and app files uncompressed in the archive.

Normally the top directory of an application is located either in the library directory $OTPROOT/lib or in a directory referred to by the environment variable ERL_LIBS. At startup when the initial code path is computed, the code server will also look for archive files in these directories and possibly add ebin directories in archives to the code path. The code path will then contain paths to directories that looks like $OTPROOT/lib/mnesia.ez/mnesia/ebin or $OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin.

The code server uses the module erl_prim_loader (possibly via the erl_boot_server) to read code files from archives. But the functions in erl_prim_loader may also be used by other applications to read files from archives. For example, the call erl_prim_loader:list_dir( "/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/examples/bench)" would list the contents of a directory inside an archive. See erl_prim_loader(3).

An application archive file and a regular application directory may coexist. This may be useful when there is a need of having parts of the application as regular files. A typical case is the priv directory which must reside as a regular directory in order to be able to dynamically link in drivers and start port programs. For other applications that do not have this need, the priv directory may reside in the archive and the files under the priv directory may be read via the erl_prim_loader.

At the time point when a directory is added to the code path as well as when the entire code path is (re)set, the code server will decide which subdirectories in an application that shall be read from the archive and which that shall be read as regular files. If directories are added or removed afterwards, the file access may fail if the code path is not updated (possibly to the same path as before in order to trigger the directory resolution update). For each directory on the second level (ebin, priv, src etc.) in the application archive, the code server will firstly choose the regular directory if it exists and secondly from the archive. The function code:lib_dir/2 returns the path to the subdirectory. For example code:lib_dir(megaco,ebin) may return /otp/root/lib/megaco-3.9.1.1.ez/megaco-3.9.1.1/ebin while code:lib_dir(megaco,priv) may return /otp/root/lib/megaco-3.9.1.1/priv.

When an escript file contains an archive, there are neither restrictions on the name of the escript nor on how many applications that may be stored in the embedded archive. Single beam files may also reside on the top level in the archive. At startup, both the top directory in the embedded archive as well as all (second level) ebin directories in the embedded archive are added to the code path. See escript(1)

When the choice of directories in the code path is strict, the directory that ends up in the code path will be exactly the stated one. This means that if for example the directory $OTPROOT/lib/mnesia-4.4.7/ebin is explicitly added to the code path, the code server will not load files from $OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin and vice versa.

This behavior can be controlled via the command line flag -code_path_choice Choice. If the flag is set to relaxed, the code server will instead choose a suitable directory depending on the actual file structure. If there exists a regular application ebin directory, it will be chosen. But if it does not exist, the ebin directory in the archive is chosen if it exists. If neither of them exists the original directory will be chosen.

The command line flag -code_path_choice Choice does also affect how init interprets the boot script. The interpretation of the explicit code paths in the boot script may be strict or relaxed. It is particular useful to set the flag to relaxed when you want to elaborate with code loading from archives without editing the boot script. The default is relaxed. See init(3)

The code of a module can exists in two variants in a system: current code and old code. When a module is loaded into the system for the first time, the code of the module becomes 'current' and the global export table is updated with references to all functions exported from the module.

If then a new instance of the module is loaded (perhaps because of the correction of an error), then the code of the previous instance becomes 'old', and all export entries referring to the previous instance are removed. After that the new instance is loaded as if it was loaded for the first time, as described above, and becomes 'current'.

Both old and current code for a module are valid, and may even be evaluated concurrently. The difference is that exported functions in old code are unavailable. Hence there is no way to make a global call to an exported function in old code, but old code may still be evaluated because of processes lingering in it.

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

For more information about old and current code, and how to make a process switch from old to current code, refer to Erlang Reference Manual.

Generally, module and application names are atoms, while file and directory names are strings. For backward compatibility reasons, some functions accept both strings and atoms, but a future release will probably only allow the arguments that are documented.

From the R12B release, functions in this module will generally fail with an exception if they are passed an incorrect type (for instance, an integer or a tuple where an atom was expected). An error tuple will be returned if the type of the argument was correct, but there was some other error (for instance, a non-existing directory was given to set_path/1).

Functions that load code (such as load_file/1) will return {error,Reason} if the load operation fails. Here follows a description of the common reasons.