add-library ( name path abi -- )
Factor handbook » C library interface » Loading native libraries

Next:

remove-library ( name -- )

Vocabulary
alien.libraries

Inputs

name	a string
path	a string
abi	one of cdecl or stdcall

Outputs
None

Word description
Defines a new logical library named name located in the file system at path and the specified ABI. You can find the location of the library via words in alien.libraries.finder. The logical library name can then be used by a LIBRARY: form to specify the logical library for subsequent FUNCTION: definitions.

Notes
Because the entire source file is parsed before top-level forms are executed, add-library must be placed within a << ... >> parse-time evaluation block.

This ensures that if the logical library is later used in the same file, for example by a FUNCTION: definition. Otherwise, the add-library call will happen too late, after compilation, and the C function calls will not refer to the correct library.

For details about parse-time evaluation, see Parse time evaluation.

Examples
Here is a typical usage of add-library:

<< "sqlite" "sqlite3" find-library cdecl add-library >>

You can also explicitly specify the library name by platform, if you prefer:

<< "freetype" { { [ os macos? ] [ "libfreetype.6.dylib" cdecl add-library ] } { [ os windows? ] [ "freetype6.dll" cdecl add-library ] } [ drop ] } cond >>

Note the parse time evaluation with <<.

Definition

USING: assocs kernel namespaces ;

IN: alien.libraries

: add-library ( name path abi -- )
    3dup add-library? [
        [ 2drop remove-library ] [ nipd make-library ]
        [ 2drop libraries get set-at ] 3tri
    ] [ 3drop ] if ;