Loading libraries

This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Functions

The usual, in projects of relative size, is to divide the program code into libraries in order to be able to reuse them in different projects. The link of these libraries within the final executable can be done in three ways:

• Compile time: The library code is copied into the executable, forming an inseparable part of it (static libraries) (Figure 1) (a).
• Load time: The library code is distributed separately (dynamic libraries) and is loaded together with the main program, at the same time (Figure 1) (b).
• Runtime: Dynamic libraries that the program loads when it needs them (Figure 1) (c).

The linking process is relatively complicated and is handled automatically by the compiler and operating system's loader. The programmer should only intervene in the third case, since it is necessary to include code to load the libraries and access the appropriate methods or variables at all times.

• Use dlib_open to load a library at runtime.
• Use dlib_proc to get a pointer to a library function.
• Use dlib_var to get a pointer to a library variable.

1. Library search paths

A dynamic library is in a different file than the executables that can make use of it. Each operating system implements different search strategies that we must know to install and/or configure the programs correctly.

1.1. Search order in Windows

• Directory path of dlib_open.
• The same directory as the executable.
• The current directory bfile_dir_work.
• Directory %SystemRoot%\System32.
• Directory %SystemRoot%.
• The directories specified in the environment variable PATH.

1.2. Search order on Linux/macOS

• The directories specified in the environment variable LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS).
• The directories specified in the executable rpath.
• System directories /lib, /usr/lib, etc.

dlib_open ()

Load a dynamic library at runtime.

DLib*
dlib_open(const char_t *path,
          const char_t *libname);

1
2
3
4

DLib *lib = dlib_open(NULL, "myplugin");
// myplugin.dll         In Windows
// libmyplugin.so       In Linux
// libmyplugin.dylib    In macOS

Return

Pointer to library or NULL if failed to load.

Remarks

If path is NULL, the library search strategy of each operating system will be followed. See Library search paths.

dlib_close ()

Close a previously opened library with dlib_open.

void
dlib_close(DLib **dlib);

dlib_proc ()

Get a pointer to a library method.

type
dlib_proc(DLib *lib,
          const char_t *procname,
          type);

1
2
3

typedef uint32_t(*FPtr_add)(const uint32_t, const uint32_t);
FPtr_add func_add = dlib_proc(lib, "plugin_add", FPtr_add);
uint32_t ret = func_add(67, 44);

Return

Pointer to method.

dlib_var ()

Get a pointer to a library variable.

type*
dlib_var(DLib *lib,
         const char_t *varname,
         type);

1

const V2Df *vzero = dlib_var(lib, "kV2D_ZEROf", V2Df);

Return

Pointer to variable.