basis/alien/libraries/libraries-docs.factor

   1 ! Copyright (C) 2009 Slava Pestov.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: alien alien.syntax assocs help.markup help.syntax kernel
   4 strings ;
   5 IN: alien.libraries
   6
   7 HELP: add-library
   8 { $values { "name" string } { "path" string } { "abi" "one of " { $link cdecl } " or " { $link stdcall } } }
   9 { $description "Defines a new logical library named " { $snippet "name" } " located in the file system at " { $snippet "path" } " and the specified ABI. You can find the location of the library via words in " { $vocab-link "alien.libraries.finder" } ". 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." }
  10 { $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."
  11 $nl
  12 "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."
  13 $nl
  14 "For details about parse-time evaluation, see " { $link "syntax-immediate" } "." }
  15 { $examples "Here is a typical usage of " { $link add-library } ":"
  16 { $code
  17     "<< \"sqlite\" \"sqlite3\" find-library cdecl add-library >>"
  18 }
  19 "You can also explicitly specify the library name by platform, if you prefer:"
  20 { $code
  21     "<< \"freetype\" {"
  22     "    { [ os macosx? ] [ \"libfreetype.6.dylib\" cdecl add-library ] }"
  23     "    { [ os windows? ] [ \"freetype6.dll\" cdecl add-library ] }"
  24     "    [ drop ]"
  25     "} cond >>"
  26 }
  27 "Note the parse time evaluation with " { $link POSTPONE: << } "." } ;
  28
  29 HELP: deploy-library
  30 { $values { "name" string } }
  31 { $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 } "." } ;
  32
  33 HELP: dlclose
  34 { $values { "dll" "a DLL handle" } }
  35 { $description "Closes a DLL handle created by " { $link dlopen } ". This word might not be implemented on all platforms." } ;
  36
  37 HELP: dlopen
  38 { $values { "path" "a pathname string" } { "dll" "a DLL handle" } }
  39 { $description "Opens a native library and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } "." }
  40 { $errors "Throws an error if the library could not be found, or if loading fails for some other reason." }
  41 { $notes "This is the low-level facility used to implement " { $link add-library } ". Use the latter instead." } ;
  42
  43 HELP: dlsym
  44 { $values { "name" "a C symbol name" } { "dll" "a DLL handle" } { "alien" { $maybe alien } } }
  45 { $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 } "." } ;
  46
  47 HELP: dlsym?
  48 { $values
  49   { "function" string }
  50   { "library" string }
  51   { "alien/f" { $maybe alien } }
  52 }
  53 { $description "Outputs the alien dynamically loaded with the given name in the given library. If no symbol is loaded, output f." } ;
  54
  55 HELP: make-library
  56 { $values
  57      { "path" "a pathname string" } { "abi" "the ABI used by the library, either " { $link cdecl } " or " { $link stdcall } }
  58      { "library" library } }
  59 { $description "Opens a C library using the path and ABI parameters and outputs a library tuple." }
  60 { $notes "User code should use " { $link add-library } " so that the opened library is added to a global hashtable, " { $link libraries } "." } ;
  61
  62 HELP: libraries
  63 { $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." } ;
  64
  65 HELP: library
  66 { $values { "name" string } { "library" assoc } }
  67 { $description "Looks up a library by its logical name. The library object is a hashtable with the following keys:"
  68     { $list
  69         { { $snippet "name" } " - the full path of the C library binary" }
  70         { { $snippet "abi" } " - the ABI used by the library, either " { $link cdecl } " or " { $link stdcall } }
  71         { { $snippet "dll" } " - an instance of the " { $link dll } " class; only set if the library is loaded" }
  72     }
  73 } ;
  74
  75 HELP: library-dll
  76 { $values { "obj" object } { "dll" "a DLL handle" } }
  77 { $description "Looks up a library by logical name and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } "." } ;
  78
  79 HELP: remove-library
  80 { $values { "name" string } }
  81 { $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." } ;
  82
  83 ARTICLE: "loading-libs" "Loading native libraries"
  84 "Before calling a C library, you must associate its path name on disk with a logical name which Factor uses to identify the library:"
  85 { $subsections
  86     add-library
  87     remove-library
  88 }
  89 "Once a library has been defined, you can see if the library has correctly loaded:"
  90 { $subsections library-dll }
  91 "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."
  92 $nl
  93 "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:"
  94 { $subsections
  95     deploy-library
  96 } ;