doc/guide/localhost/LibrarySupport

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta name="generator" content="AsciiDoc 8.6.9">
   6 <title>LibrarySupport</title>
   7 <link rel="stylesheet" href="./asciidoc.css" type="text/css">
   8 <link rel="stylesheet" href="./pygments.css" type="text/css">
   9
  10
  11 <script type="text/javascript" src="./asciidoc.js"></script>
  12 <script type="text/javascript">
  13 /*<![CDATA[*/
  14 asciidoc.install();
  15 /*]]>*/
  16 </script>
  17 <link rel="stylesheet" href="./mlton.css" type="text/css">
  18 </head>
  19 <body class="article">
  20 <div id="banner">
  21 <div id="banner-home">
  22 <a href="./Home">MLton 20180207</a>
  23 </div>
  24 </div>
  25 <div id="header">
  26 <h1>LibrarySupport</h1>
  27 </div>
  28 <div id="content">
  29 <div id="preamble">
  30 <div class="sectionbody">
  31 <div class="paragraph"><p>MLton supports both linking to and creating system-level libraries.
  32 While Standard ML libraries should be designed with the <a href="MLBasis">MLBasis</a> system to work with other Standard ML programs,
  33 system-level library support allows MLton to create libraries for use by other programming languages.
  34 Even more importantly, system-level library support allows MLton to access libraries from other languages.
  35 This article will explain how to use libraries portably with MLton.</p></div>
  36 </div>
  37 </div>
  38 <div class="sect1">
  39 <h2 id="_the_basics">The Basics</h2>
  40 <div class="sectionbody">
  41 <div class="paragraph"><p>A Dynamic Shared Object (DSO) is a piece of executable code written in a format understood by the operating system.
  42 Executable programs and dynamic libraries are the two most common examples of a DSO.
  43 They are called shared because if they are used more than once, they are only loaded once into main memory.
  44 For example, if you start two instances of your web browser (an executable), there may be two processes running, but the program code of the executable is only loaded once.
  45 A dynamic library, for example a graphical toolkit, might be used by several different executable programs, each possibly running multiple times.
  46 Nevertheless, the dynamic library is only loaded once and it&#8217;s program code is shared between all of the processes.</p></div>
  47 <div class="paragraph"><p>In addition to program code, DSOs contain a table of textual strings called symbols.
  48 These are used in order to make the DSO do something useful, like execute.
  49 For example, on linux the symbol <span class="monospaced">_start</span> refers to the point in the program code where the operating system should start executing the program.
  50 Dynamic libraries generally provide many symbols, corresponding to functions which can be called and variables which can be read or written.
  51 Symbols can be used by the DSO itself, or by other DSOs which require services.</p></div>
  52 <div class="paragraph"><p>When a DSO creates a symbol, this is called <em>exporting</em>.
  53 If a DSO needs to use a symbol, this is called <em>importing</em>.
  54 A DSO might need to use symbols defined within itself or perhaps from another DSO.
  55 In both cases, it is importing that symbol, but the scope of the import differs.
  56 Similarly, a DSO might export a symbol for use only within itself, or it might export a symbol for use by other DSOs.
  57 Some symbols are resolved at compile time by the linker (those used within the DSO) and some are resolved at runtime by the dynamic link loader (symbols accessed between DSOs).</p></div>
  58 </div>
  59 </div>
  60 <div class="sect1">
  61 <h2 id="_symbols_in_mlton">Symbols in MLton</h2>
  62 <div class="sectionbody">
  63 <div class="paragraph"><p>Symbols in MLton are both imported and exported via the <a href="ForeignFunctionInterface">ForeignFunctionInterface</a>.
  64 The notation <span class="monospaced">_import "symbolname"</span> imports functions, <span class="monospaced">_symbol "symbolname"</span> imports variables, and <span class="monospaced">_address "symbolname"</span> imports an address.
  65 To create and export a symbol, <span class="monospaced">_export "symbolname"</span> creates a function symbol and <span class="monospaced">_symbol "symbolname" 'alloc'</span> creates and exports a variable.
  66 For details of the syntax and restrictions on the supported FFI types, read the <a href="ForeignFunctionInterface">ForeignFunctionInterface</a> page.
  67 In this discussion it only matters that every FFI use is either an import or an export.</p></div>
  68 <div class="paragraph"><p>When exporting a symbol, MLton supports controlling the export scope.
  69 If the symbol should only be used within the same DSO, that symbol has <em><span class="monospaced">private</span></em> scope.
  70 Conversely, if the symbol should also be available to other DSOs the symbol has <em><span class="monospaced">public</span></em> scope.
  71 Generally, one should have as few public exports as possible.
  72 Since they are public, other DSOs will come to depend on them, limiting your ability to change them.
  73 You specify the export scope in MLton by putting <span class="monospaced">private</span> or <span class="monospaced">public</span> after the symbol&#8217;s name in an FFI directive.
  74 eg: <span class="monospaced">_export "foo" private: int-&gt;int;</span> or <span class="monospaced">_export "bar" public: int-&gt;int;</span> .</p></div>
  75 <div class="paragraph"><p>For technical reasons, the linker and loader on various platforms need to know the scope of a symbol being imported.
  76 If the symbol is exported by the same DSO, use <span class="monospaced">public</span> or <span class="monospaced">private</span> as appropriate.
  77 If the symbol is exported by a different DSO, then the scope <em><span class="monospaced">external</span></em> should be used to import it.
  78 Within a DSO, all references to a symbol must use the same scope.
  79 MLton will check this at compile time, reporting: <span class="monospaced">symbol "foo" redeclared as public (previously external)</span>. This may cause linker errors.
  80 However, MLton can only check usage within Standard ML.
  81 All objects being linked into a resulting DSO must agree, and it is the programmer&#8217;s responsibility to ensure this.</p></div>
  82 <div class="paragraph"><p>Summary of symbol scopes:</p></div>
  83 <div class="ulist"><ul>
  84 <li>
  85 <p>
  86 <span class="monospaced">private</span>: used for symbols exported within a DSO only for use within that DSO
  87 </p>
  88 </li>
  89 <li>
  90 <p>
  91 <span class="monospaced">public</span>: used for symbols exported within a DSO that may also be used outside that DSO
  92 </p>
  93 </li>
  94 <li>
  95 <p>
  96 <span class="monospaced">external</span>: used for importing symbols from another DSO
  97 </p>
  98 </li>
  99 <li>
 100 <p>
 101 All uses of a symbol within a DSO (both imports and exports) must agree on the symbol scope
 102 </p>
 103 </li>
 104 </ul></div>
 105 </div>
 106 </div>
 107 <div class="sect1">
 108 <h2 id="_output_formats">Output Formats</h2>
 109 <div class="sectionbody">
 110 <div class="paragraph"><p>MLton can create executables (<span class="monospaced">-format executable</span>) and dynamic shared libraries (<span class="monospaced">-format library</span>).
 111 To link a shared library, use <span class="monospaced">-link-opt -l&lt;dso_name&gt;</span>.
 112 The default output format is executable.</p></div>
 113 <div class="paragraph"><p>MLton can also create archives.
 114 An archive is not a DSO, but it does have a collection of symbols.
 115 When an archive is linked into a DSO, it is completely absorbed.
 116 Other objects being compiled into the DSO should refer to the public symbols in the archive as public, since they are still in the same DSO.
 117 However, in the interest of modular programming, private symbols in an archive cannot be used outside of that archive, even within the same DSO.</p></div>
 118 <div class="paragraph"><p>Although both executables and libraries are DSOs, some implementation details differ on some platforms.
 119 For this reason, MLton can create two types or archives.
 120 A normal archive (<span class="monospaced">-format archive</span>) is appropriate for linking into an executable.
 121 Conversely, a libarchive (<span class="monospaced">-format libarchive</span>) should be used if it will be linked into a dynamic library.</p></div>
 122 <div class="paragraph"><p>When MLton does not create an executable, it creates two special symbols.
 123 The symbol <span class="monospaced">libname_open</span> is a function which must be called before any other symbols are accessed.
 124 The <span class="monospaced">libname</span> is controlled by the <span class="monospaced">-libname</span> compile option and defaults to the name of the output, with any prefixing lib stripped (eg: <span class="monospaced">foo</span> &#8594; <span class="monospaced">foo</span>, <span class="monospaced">libfoo</span> &#8594; <span class="monospaced">foo</span>).
 125 The symbol <span class="monospaced">libname_close</span> is a function which should be called to clean up memory once done.</p></div>
 126 <div class="paragraph"><p>Summary of <span class="monospaced">-format</span> options:</p></div>
 127 <div class="ulist"><ul>
 128 <li>
 129 <p>
 130 <span class="monospaced">executable</span>: create an executable (a DSO)
 131 </p>
 132 </li>
 133 <li>
 134 <p>
 135 <span class="monospaced">library</span>: create a dynamic shared library (a DSO)
 136 </p>
 137 </li>
 138 <li>
 139 <p>
 140 <span class="monospaced">archive</span>: create an archive of symbols (not a DSO) that can be linked into an executable
 141 </p>
 142 </li>
 143 <li>
 144 <p>
 145 <span class="monospaced">libarchive</span>: create an archive of symbols (not a DSO) that can be linked into a library
 146 </p>
 147 </li>
 148 </ul></div>
 149 <div class="paragraph"><p>Related options:</p></div>
 150 <div class="ulist"><ul>
 151 <li>
 152 <p>
 153 <span class="monospaced">-libname x</span>: controls the name of the special <span class="monospaced">_open</span> and <span class="monospaced">_close</span> functions.
 154 </p>
 155 </li>
 156 </ul></div>
 157 </div>
 158 </div>
 159 <div class="sect1">
 160 <h2 id="_interfacing_with_c">Interfacing with C</h2>
 161 <div class="sectionbody">
 162 <div class="paragraph"><p>MLton can generate a C header file.
 163 When the output format is not an executable, it creates one by default named <span class="monospaced">libname.h</span>.
 164 This can be overridden with <span class="monospaced">-export-header foo.h</span>.
 165 This header file should be included by any C files using the exported Standard ML symbols.</p></div>
 166 <div class="paragraph"><p>If C is being linked with Standard ML into the same output archive or DSO,
 167 then the C code should <span class="monospaced">#define PART_OF_LIBNAME</span> before it includes the header file.
 168 This ensures that the C code is using the symbols with correct scope.
 169 Any symbols exported from C should also be marked using the <span class="monospaced">PRIVATE</span>/<span class="monospaced">PUBLIC</span>/<span class="monospaced">EXTERNAL</span> macros defined in the Standard ML export header.
 170 The declared C scope on exported C symbols should match the import scope used in Standard ML.</p></div>
 171 <div class="paragraph"><p>An example:</p></div>
 172 <div class="listingblock">
 173 <div class="content"><div class="highlight"><pre><span class="cp">#define PART_OF_FOO</span>
 174 <span class="cp">#include</span> <span class="cpf">&quot;foo.h&quot;</span><span class="cp"></span>
 175
 176 <span class="n">PUBLIC</span> <span class="kt">int</span> <span class="nf">cFoo</span><span class="p">()</span> <span class="p">{</span>
 177   <span class="k">return</span> <span class="n">smlFoo</span><span class="p">();</span>
 178 <span class="p">}</span>
 179 </pre></div></div></div>
 180 <div class="listingblock">
 181 <div class="content"><div class="highlight"><pre><span class="k">val</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">&quot;smlFoo&quot;</span><span class="w"> </span><span class="n">private</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">int</span><span class="p">;</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="mi">5</span><span class="p">)</span><span class="w"></span>
 182 <span class="k">val</span><span class="w"> </span><span class="n">cFoo</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">&quot;cFoo&quot;</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">int</span><span class="p">;</span><span class="w"></span>
 183 </pre></div></div></div>
 184 </div>
 185 </div>
 186 <div class="sect1">
 187 <h2 id="_operating_system_specific_details">Operating-system specific details</h2>
 188 <div class="sectionbody">
 189 <div class="paragraph"><p>On Windows, <span class="monospaced">libarchive</span> and <span class="monospaced">archive</span> are the same.
 190 However, depending on this will lead to portability problems.
 191 Windows is also especially sensitive to mixups of <em><span class="monospaced">public</span></em> and <em><span class="monospaced">external</span></em>.
 192 If an archive is linked, make sure it&#8217;s symbols are imported as <span class="monospaced">public</span>.
 193 If a DLL is linked, make sure it&#8217;s symbols are imported as <span class="monospaced">external</span>.
 194 Using <span class="monospaced">external</span> instead of <span class="monospaced">public</span> will result in link errors that <span class="monospaced">__imp__foo is undefined</span>.
 195 Using <span class="monospaced">public</span> instead of <span class="monospaced">external</span> will result in inconsistent function pointer addresses and failure to update the imported variables.</p></div>
 196 <div class="paragraph"><p>On Linux, <span class="monospaced">libarchive</span> and <span class="monospaced">archive</span> are different.
 197 Libarchives are quite rare, but necessary if creating a library from an archive.
 198 It is common for a library to provide both an archive and a dynamic library on this platform.
 199 The linker will pick one or the other, usually preferring the dynamic library.
 200 While a quirk of the operating system allows external import to work for both archives and libraries,
 201 portable projects should not depend on this behaviour.
 202 On other systems it can matter how the library is linked (static or dynamic).</p></div>
 203 </div>
 204 </div>
 205 </div>
 206 <div id="footnotes"><hr></div>
 207 <div id="footer">
 208 <div id="footer-text">
 209 </div>
 210 <div id="footer-badges">
 211 </div>
 212 </div>
 213 </body>
 214 </html>