1 ! Copyright (C) 2009 Slava Pestov.
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: accessors alien alien.syntax assocs help.markup
4 help.syntax io.backend kernel namespaces strings ;
9 { "path" "a pathname string" } { "abi" "the ABI used by the library, either " { $link cdecl } " or " { $link stdcall } }
10 { "library" library } }
11 { $description "Opens a C library using the path and ABI parameters and outputs a library tuple." }
12 { $notes "User code should use " { $link add-library } " so that the opened library is added to a global hashtable, " { $link libraries } "." } ;
15 { $description "A global hashtable that keeps a list of open libraries. Use the " { $link add-library } " word to construct a library and add it with a single call." } ;
18 { $values { "name" string } { "library" assoc } }
19 { $description "Looks up a library by its logical name. The library object is a hashtable with the following keys:"
21 { { $snippet "name" } " - the full path of the C library binary" }
22 { { $snippet "abi" } " - the ABI used by the library, either " { $link cdecl } " or " { $link stdcall } }
23 { { $snippet "dll" } " - an instance of the " { $link dll } " class; only set if the library is loaded" }
28 { $values { "path" "a pathname string" } { "dll" "a DLL handle" } }
29 { $description "Opens a native library and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } "." }
30 { $errors "Throws an error if the library could not be found, or if loading fails for some other reason." }
31 { $notes "This is the low-level facility used to implement " { $link load-library } ". Use the latter instead." } ;
34 { $values { "name" "a C symbol name" } { "dll" "a DLL handle" } { "alien" { $maybe alien } } }
35 { $description "Looks up a symbol in a native library. If " { $snippet "dll" } " is " { $link f } " looks for the symbol in the runtime executable. If the symbol was not found, outputs " { $link f } "." } ;
38 { $values { "dll" "a DLL handle" } }
39 { $description "Closes a DLL handle created by " { $link dlopen } ". This word might not be implemented on all platforms." } ;
42 { $values { "name" string } { "dll" "a DLL handle" } }
43 { $description "Loads a library by logical name and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } ". If the library is already loaded, returns the existing handle." } ;
46 { $values { "name" string } { "path" string } { "abi" "one of " { $link cdecl } " or " { $link stdcall } } }
47 { $description "Defines a new logical library named " { $snippet "name" } " located in the file system at " { $snippet "path" } " and the specified ABI. The logical library name can then be used by a " { $link POSTPONE: LIBRARY: } " form to specify the logical library for subsequent " { $link POSTPONE: FUNCTION: } " definitions." }
48 { $notes "Because the entire source file is parsed before top-level forms are executed, " { $link add-library } " must be placed within a " { $snippet "<< ... >>" } " parse-time evaluation block."
50 "This ensures that if the logical library is later used in the same file, for example by a " { $link POSTPONE: FUNCTION: } " definition. Otherwise, the " { $link add-library } " call will happen too late, after compilation, and the C function calls will not refer to the correct library."
52 "For details about parse-time evaluation, see " { $link "syntax-immediate" } "." }
53 { $examples "Here is a typical usage of " { $link add-library } ":"
56 " { [ os macosx? ] [ \"libfreetype.6.dylib\" cdecl add-library ] }"
57 " { [ os windows? ] [ \"freetype6.dll\" cdecl add-library ] }"
61 "Note the parse time evaluation with " { $link POSTPONE: << } "." } ;
64 { $values { "name" string } }
65 { $description "Specifies that the logical library named " { $snippet "name" } " should be included during " { $link "tools.deploy" } ". " { $snippet "name" } " must be the name of a library previously loaded with " { $link add-library } "." } ;
68 { $values { "name" string } }
69 { $description "Unloads a library and removes it from the internal list of libraries. The " { $snippet "name" } " parameter should be a name that was previously passed to " { $link add-library } ". If no library with that name exists, this word does nothing." } ;
71 ARTICLE: "loading-libs" "Loading native libraries"
72 "Before calling a C library, you must associate its path name on disk with a logical name which Factor uses to identify the library:"
77 "Once a library has been defined, you can try loading it to see if the path name is correct:"
78 { $subsections load-library }
79 "If the compiler cannot load a library, or cannot resolve a symbol in a library, a linkage error is reported using the compiler error mechanism (see " { $link "compiler-errors" } "). Once you install the right library, reload the source file containing the " { $link add-library } " form to force the compiler to try loading the library again."
81 "Libraries that do not come standard with the operating system need to be included with deployed applications that use them. A word is provided to instruct " { $link "tools.deploy" } " that a library must be so deployed:"