nimterop/cimport.html
Ganesh Viswanathan 78bc82644a Update documentation
2020-03-24 15:55:42 -05:00

410 lines
45 KiB
HTML

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- This file is generated by Nim. -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Favicon -->
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">
<!-- Google fonts -->
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
<!-- CSS -->
<title>cimport</title>
<link rel="stylesheet" type="text/css" href="nimdoc.out.css">
<script type="text/javascript" src="dochack.js"></script>
<script type="text/javascript">
function main() {
var pragmaDots = document.getElementsByClassName("pragmadots");
for (var i = 0; i < pragmaDots.length; i++) {
pragmaDots[i].onclick = function(event) {
// Hide tease
event.target.parentNode.style.display = "none";
// Show actual
event.target.parentNode.nextElementSibling.style.display = "inline";
}
}
const toggleSwitch = document.querySelector('.theme-switch input[type="checkbox"]');
function switchTheme(e) {
if (e.target.checked) {
document.documentElement.setAttribute('data-theme', 'dark');
localStorage.setItem('theme', 'dark');
} else {
document.documentElement.setAttribute('data-theme', 'light');
localStorage.setItem('theme', 'light');
}
}
toggleSwitch.addEventListener('change', switchTheme, false);
if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
document.documentElement.setAttribute('data-theme', "dark");
toggleSwitch.checked = true;
} else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches) {
document.documentElement.setAttribute('data-theme', "light");
toggleSwitch.checked = false;
} else {
const currentTheme = localStorage.getItem('theme') ? localStorage.getItem('theme') : null;
if (currentTheme) {
document.documentElement.setAttribute('data-theme', currentTheme);
if (currentTheme === 'dark') {
toggleSwitch.checked = true;
}
}
}
}
</script>
</head>
<body onload="main()">
<div class="document" id="documentId">
<div class="container">
<h1 class="title">cimport</h1>
<div class="row">
<div class="three columns">
<div class="theme-switch-wrapper">
<label class="theme-switch" for="checkbox">
<input type="checkbox" id="checkbox" />
<div class="slider round"></div>
</label>
&nbsp;&nbsp;&nbsp; <em>Dark Mode</em>
</div>
<div id="global-links">
<ul class="simple">
</ul>
</div>
<div id="searchInputDiv">
Search: <input type="text" id="searchInput"
onkeyup="search()" />
</div>
<div>
Group by:
<select onchange="groupBy(this.value)">
<option value="section">Section</option>
<option value="type">Type</option>
</select>
</div>
<ul class="simple simple-toc" id="toc-list">
<li>
<a class="reference reference-toplevel" href="#6" id="56">Imports</a>
<ul class="simple simple-toc-section">
</ul>
</li>
<li>
<a class="reference reference-toplevel" href="#7" id="57">Types</a>
<ul class="simple simple-toc-section">
<li><a class="reference" href="#Feature"
title="Feature = enum
ast2"><wbr />Feature<span class="attachedType"></span></a></li>
</ul>
</li>
<li>
<a class="reference reference-toplevel" href="#12" id="62">Procs</a>
<ul class="simple simple-toc-section">
<li><a class="reference" href="#cSkipSymbol%2Cseq%5BT%5D%5Bstring%5D"
title="cSkipSymbol(skips: seq[string])"><wbr />c<wbr />Skip<wbr />Symbol<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cSearchPath%2Cstring"
title="cSearchPath(path: string): string"><wbr />c<wbr />Search<wbr />Path<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cDebug"
title="cDebug()"><wbr />c<wbr />Debug<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cDisableCaching"
title="cDisableCaching()"><wbr />c<wbr />Disable<wbr />Caching<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cAddSearchDir%2Cstring"
title="cAddSearchDir(dir: string)"><wbr />c<wbr />Add<wbr />Search<wbr />Dir<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cAddStdDir%2Cstring"
title="cAddStdDir(mode = &quot;c&quot;)"><wbr />c<wbr />Add<wbr />Std<wbr />Dir<span class="attachedType"></span></a></li>
</ul>
</li>
<li>
<a class="reference reference-toplevel" href="#17" id="67">Macros</a>
<ul class="simple simple-toc-section">
<li><a class="reference" href="#cOverride.m"
title="cOverride(body): untyped"><wbr />c<wbr />Override<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cPlugin.m"
title="cPlugin(body): untyped"><wbr />c<wbr />Plugin<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cDefine.m%2C%2Cstring"
title="cDefine(name: static string; val: static string = &quot;&quot;): untyped"><wbr />c<wbr />Define<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cIncludeDir.m"
title="cIncludeDir(dir: static string): untyped"><wbr />c<wbr />Include<wbr />Dir<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cCompile.m%2C%2Cstring%2Cstring"
title="cCompile(path: static string; mode = &quot;c&quot;; exclude = &quot;&quot;): untyped"><wbr />c<wbr />Compile<span class="attachedType"></span></a></li>
<li><a class="reference" href="#cImport.m%2C%2Cstring%2Cstring%2Cstring"
title="cImport(filename: static string; recurse: static bool = false;
dynlib: static string = &quot;&quot;; mode: static string = &quot;c&quot;; flags: static string = &quot;&quot;): untyped"><wbr />c<wbr />Import<span class="attachedType"></span></a></li>
<li><a class="reference" href="#c2nImport.m%2C%2Cstring%2Cstring%2Cstring"
title="c2nImport(filename: static string; recurse: static bool = false;
dynlib: static string = &quot;&quot;; mode: static string = &quot;c&quot;; flags: static string = &quot;&quot;): untyped"><wbr />c2n<wbr />Import<span class="attachedType"></span></a></li>
</ul>
</li>
<li>
<a class="reference reference-toplevel" href="#19" id="69">Exports</a>
<ul class="simple simple-toc-section">
</ul>
</li>
</ul>
</div>
<div class="nine columns" id="content">
<div id="tocRoot"></div>
<p class="module-desc"><p>This is the main nimterop import file to help with wrapping C/C++ source code.</p>
<p>Check out <a class="reference external" href="https://github.com/nimterop/nimterop/blob/master/nimterop/template.nim">template.nim</a> as a starting point for wrapping a new library. The template can be copied and trimmed down and modified as required. <a class="reference external" href="https://github.com/nimterop/nimterop/blob/master/nimterop/templite.nim">templite.nim</a> is a shorter version for more experienced users.</p>
<p>All <tt class="docutils literal"><span class="pre">{.compileTime.}</span></tt> procs must be used in a compile time context, e.g. using:</p>
<pre class="listing"><span class="Keyword">static</span><span class="Punctuation">:</span>
<span class="Identifier">cAddStdDir</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
<div class="section" id="6">
<h1><a class="toc-backref" href="#6">Imports</a></h1>
<dl class="item">
<a class="reference external" href="plugin.html">plugin</a>, <a class="reference external" href="build.html">build</a>, <a class="reference external" href="paths.html">paths</a>, <a class="reference external" href="types.html">types</a>
</dl></div>
<div class="section" id="7">
<h1><a class="toc-backref" href="#7">Types</a></h1>
<dl class="item">
<a id="Feature"></a>
<dt><pre><a href="cimport.html#Feature"><span class="Identifier">Feature</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
<span class="Identifier">ast2</span></pre></dt>
<dd>
</dd>
</dl></div>
<div class="section" id="12">
<h1><a class="toc-backref" href="#12">Procs</a></h1>
<dl class="item">
<a id="cSkipSymbol,seq[T][string]"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#cSkipSymbol%2Cseq%5BT%5D%5Bstring%5D"><span class="Identifier">cSkipSymbol</span></a><span class="Other">(</span><span class="Identifier">skips</span><span class="Other">:</span> <span class="Identifier">seq</span><span class="Other">[</span><span class="Identifier">string</span><span class="Other">]</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">compileTime</span><span class="Other">,</span> <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
<dd>
<p>Similar to <a class="reference external" href="cimport.html#cOverride.m">cOverride()</a>, this macro allows filtering out symbols not of interest from the generated output.</p>
<p><a class="reference external" href="cimport.html#cSkipSymbol%2Cseq[T][string]">cSkipSymbol()</a> only affects calls to <a class="reference external" href="cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring">cImport()</a> that follow it.</p>
<p><strong class="examples_text">Examples:</strong></p>
<pre class="listing"><span class="Keyword">static</span> <span class="Other">:</span>
<span class="Identifier">cSkipSymbol</span> <span class="Operator">@</span><span class="Other">[</span><span class="StringLit">&quot;proc1&quot;</span><span class="Other">,</span> <span class="StringLit">&quot;Type2&quot;</span><span class="Other">]</span></pre>
</dd>
<a id="cSearchPath,string"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#cSearchPath%2Cstring"><span class="Identifier">cSearchPath</span></a><span class="Other">(</span><span class="Identifier">path</span><span class="Other">:</span> <span class="Identifier">string</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">string</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">compileTime</span><span class="Other">,</span> <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ReadDirEffect</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
<dd>
<p>Get full path to file or directory <tt class="docutils literal"><span class="pre">path</span></tt> in search path configured using <a class="reference external" href="cimport.html#cAddSearchDir%2Cstring">cAddSearchDir()</a> and <a class="reference external" href="cimport.html#cAddStdDir,string">cAddStdDir()</a>.</p>
<p>This can be used to locate files or directories that can be passed onto <a class="reference external" href="cimport.html#cCompile.m%2C%2Cstring%2Cstring">cCompile()</a>, <a class="reference external" href="cimport.html#cIncludeDir.m">cIncludeDir()</a> and <a class="reference external" href="cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring">cImport()</a>.</p>
</dd>
<a id="cDebug"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#cDebug"><span class="Identifier">cDebug</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">compileTime</span><span class="Other">,</span> <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
<dd>
Enable debug messages and display the generated Nim code
</dd>
<a id="cDisableCaching"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#cDisableCaching"><span class="Identifier">cDisableCaching</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">compileTime</span><span class="Other">,</span> <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
<dd>
<p>Disable caching of generated Nim code - useful during wrapper development</p>
<p>If files included by header being processed by <a class="reference external" href="cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring">cImport()</a> change and affect the generated content, they will be ignored and the cached value will continue to be used . Use <a class="reference external" href="cimport.html#cDisableCaching">cDisableCaching()</a> to avoid this scenario during development.</p>
<p><tt class="docutils literal"><span class="pre">nim -f</span></tt> was broken prior to 0.19.4 but can also be used to flush the cached content.</p>
</dd>
<a id="cAddSearchDir,string"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#cAddSearchDir%2Cstring"><span class="Identifier">cAddSearchDir</span></a><span class="Other">(</span><span class="Identifier">dir</span><span class="Other">:</span> <span class="Identifier">string</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">compileTime</span><span class="Other">,</span> <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
<dd>
Add directory <tt class="docutils literal"><span class="pre">dir</span></tt> to the search path used in calls to <a class="reference external" href="cimport.html#cSearchPath,string">cSearchPath()</a>.
<p><strong class="examples_text">Examples:</strong></p>
<pre class="listing"><span class="Keyword">import</span>
<span class="Identifier">paths</span><span class="Other">,</span> <span class="Identifier">os</span>
<span class="Keyword">static</span> <span class="Other">:</span>
<span class="Identifier">cAddSearchDir</span> <span class="Identifier">testsIncludeDir</span><span class="Other">(</span><span class="Other">)</span>
<span class="Identifier">doAssert</span> <span class="Identifier">cSearchPath</span><span class="Other">(</span><span class="StringLit">&quot;test.h&quot;</span><span class="Other">)</span><span class="Other">.</span><span class="Identifier">existsFile</span></pre>
</dd>
<a id="cAddStdDir,string"></a>
<dt><pre><span class="Keyword">proc</span> <a href="#cAddStdDir%2Cstring"><span class="Identifier">cAddStdDir</span></a><span class="Other">(</span><span class="Identifier">mode</span> <span class="Other">=</span> <span class="StringLit">&quot;c&quot;</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">compileTime</span><span class="Other">,</span> <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">IOError</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">,</span> <span class="Identifier">OSError</span><span class="Other">,</span>
<span class="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">Defect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ReadEnvEffect</span><span class="Other">,</span> <span class="Identifier">ReadIOEffect</span><span class="Other">,</span> <span class="Identifier">ReadDirEffect</span><span class="Other">,</span>
<span class="Identifier">WriteIOEffect</span><span class="Other">,</span> <span class="Identifier">ExecIOEffect</span><span class="Other">,</span> <span class="Identifier">RootEffect</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
<dd>
Add the standard <tt class="docutils literal"><span class="pre">c</span></tt> [default] or <tt class="docutils literal"><span class="pre">cpp</span></tt> include paths to search path used in calls to <a class="reference external" href="cimport.html#cSearchPath,string">cSearchPath()</a>
<p><strong class="examples_text">Examples:</strong></p>
<pre class="listing"><span class="Keyword">static</span> <span class="Other">:</span>
<span class="Identifier">cAddStdDir</span><span class="Other">(</span><span class="Other">)</span>
<span class="Keyword">import</span>
<span class="Identifier">os</span>
<span class="Identifier">doAssert</span> <span class="Identifier">cSearchPath</span><span class="Other">(</span><span class="StringLit">&quot;math.h&quot;</span><span class="Other">)</span><span class="Other">.</span><span class="Identifier">existsFile</span></pre>
</dd>
</dl></div>
<div class="section" id="17">
<h1><a class="toc-backref" href="#17">Macros</a></h1>
<dl class="item">
<a id="cOverride.m"></a>
<dt><pre><span class="Keyword">macro</span> <a href="#cOverride.m"><span class="Identifier">cOverride</span></a><span class="Other">(</span><span class="Identifier">body</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
<p>When the wrapper code generated by nimterop is missing certain symbols or not accurate, it may be required to hand wrap them. Define them in a <a class="reference external" href="cimport.html#cOverride.m">cOverride()</a> macro block so that Nimterop uses these definitions instead.</p>
<p>For example:</p>
<pre class="listing"><span class="Keyword">int</span> <span class="Identifier">svGetCallerInfo</span><span class="Punctuation">(</span><span class="Keyword">const</span> <span class="Keyword">char</span><span class="Operator">**</span> <span class="Identifier">fileName</span><span class="Punctuation">,</span> <span class="Keyword">int</span> <span class="Operator">*</span><span class="Identifier">lineNumber</span><span class="Punctuation">)</span><span class="Punctuation">;</span></pre><p>This might map to:</p>
<pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">svGetCallerInfo</span><span class="Punctuation">(</span><span class="Identifier">fileName</span><span class="Punctuation">:</span> <span class="Keyword">ptr</span> <span class="Identifier">cstring</span><span class="Punctuation">;</span> <span class="Identifier">lineNumber</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">cint</span><span class="Punctuation">)</span></pre><p>Whereas it might mean:</p>
<pre class="listing"><span class="Identifier">cOverride</span><span class="Punctuation">:</span>
<span class="Keyword">proc</span> <span class="Identifier">svGetCallerInfo</span><span class="Punctuation">(</span><span class="Identifier">fileName</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">cstring</span><span class="Punctuation">;</span> <span class="Identifier">lineNumber</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">cint</span><span class="Punctuation">)</span></pre><p>Using the <a class="reference external" href="cimport.html#cOverride.m">cOverride()</a> block, nimterop can be instructed to use this definition of <tt class="docutils literal"><span class="pre">svGetCallerInfo()</span></tt> instead. This works for procs, consts and types.</p>
<p><tt class="docutils literal"><span class="pre">cOverride()</span></tt> only affects the next <tt class="docutils literal"><span class="pre">cImport()</span></tt> call. This is because any recognized symbols get overridden in place and any remaining symbols get added to the top. If reused, the next <tt class="docutils literal"><span class="pre">cImport()</span></tt> would add those symbols again leading to redefinition errors.</p>
</dd>
<a id="cPlugin.m"></a>
<dt><pre><span class="Keyword">macro</span> <a href="#cPlugin.m"><span class="Identifier">cPlugin</span></a><span class="Other">(</span><span class="Identifier">body</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
When <a class="reference external" href="cimport.html#cOverride.m">cOverride()</a> and <a class="reference external" href="cimport.html#cSkipSymbol%2Cseq[T][string]">cSkipSymbol()</a> are not adequate, the <a class="reference external" href="cimport.html#cPlugin.m">cPlugin()</a> macro can be used to customize the generated Nim output. The following callbacks are available at this time.<pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">onSymbol</span><span class="Punctuation">(</span><span class="Identifier">sym</span><span class="Punctuation">:</span> <span class="Keyword">var</span> <span class="Identifier">Symbol</span><span class="Punctuation">)</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">exportc</span><span class="Punctuation">,</span> <span class="Identifier">dynlib</span><span class="Operator">.</span><span class="Punctuation">}</span></pre><p><tt class="docutils literal"><span class="pre">onSymbol()</span></tt> can be used to handle symbol name modifications required due to invalid characters in identifiers or to rename symbols that would clash due to Nim's style insensitivity. The symbol name and type is provided to the callback and the name can be modified.</p>
<p>While <tt class="docutils literal"><span class="pre">cPlugin</span></tt> can easily remove leading/trailing <tt class="docutils literal"><span class="pre">_</span></tt> or prefixes and suffixes like <tt class="docutils literal"><span class="pre">SDL_</span></tt>, passing <tt class="docutils literal"><span class="pre">--prefix</span></tt> or <tt class="docutils literal"><span class="pre">--suffix</span></tt> flags to <tt class="docutils literal"><span class="pre">cImport</span></tt> in the <tt class="docutils literal"><span class="pre">flags</span></tt> parameter is much easier. However, these flags will only be considered when no <tt class="docutils literal"><span class="pre">cPlugin</span></tt> is specified.</p>
<p>Returning a blank name will result in the symbol being skipped. This will fail for <tt class="docutils literal"><span class="pre">nskParam</span></tt> and <tt class="docutils literal"><span class="pre">nskField</span></tt> since the generated Nim code will be wrong.</p>
<p>Symbol types can be any of the following:</p>
<ul class="simple"><li><tt class="docutils literal"><span class="pre">nskConst</span></tt> for constants</li>
<li><tt class="docutils literal"><span class="pre">nskType</span></tt> for type identifiers, including primitive</li>
<li><tt class="docutils literal"><span class="pre">nskParam</span></tt> for param names</li>
<li><tt class="docutils literal"><span class="pre">nskField</span></tt> for struct field names</li>
<li><tt class="docutils literal"><span class="pre">nskEnumField</span></tt> for enum (field) names, though they are in the global namespace as <tt class="docutils literal"><span class="pre">nskConst</span></tt></li>
<li><tt class="docutils literal"><span class="pre">nskProc</span></tt> - for proc names</li>
</ul>
<p><tt class="docutils literal"><span class="pre">nimterop/plugins</span></tt> is implicitly imported to provide access to standard plugin facilities.</p>
<p><a class="reference external" href="cimport.html#cPlugin.m">cPlugin()</a> only affects calls to <a class="reference external" href="cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring">cImport()</a> that follow it.</p>
<p><strong class="examples_text">Examples:</strong></p>
<pre class="listing"><span class="Identifier">cPlugin</span><span class="Other">:</span>
<span class="Keyword">import</span>
<span class="Identifier">strutils</span>
<span class="Keyword">proc</span> <span class="Identifier">onSymbol</span><span class="Operator">*</span><span class="Other">(</span><span class="Identifier">sym</span><span class="Other">:</span> <span class="Keyword">var</span> <span class="Identifier">Symbol</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">exportc</span><span class="Other">,</span> <span class="Identifier">dynlib</span></span><span class="Other">.}</span></span> <span class="Other">=</span>
<span class="Identifier">sym</span><span class="Other">.</span><span class="Identifier">name</span> <span class="Other">=</span> <span class="Identifier">sym</span><span class="Other">.</span><span class="Identifier">name</span><span class="Other">.</span><span class="Identifier">strip</span><span class="Other">(</span><span class="Identifier">chars</span> <span class="Other">=</span> <span class="Other">{</span><span class="CharLit">'_'</span><span class="Other">}</span><span class="Other">)</span>
</pre>
<p><strong class="examples_text">Examples:</strong></p>
<pre class="listing"><span class="Identifier">cPlugin</span><span class="Other">:</span>
<span class="Keyword">import</span>
<span class="Identifier">strutils</span>
<span class="Keyword">proc</span> <span class="Identifier">onSymbol</span><span class="Operator">*</span><span class="Other">(</span><span class="Identifier">sym</span><span class="Other">:</span> <span class="Keyword">var</span> <span class="Identifier">Symbol</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">exportc</span><span class="Other">,</span> <span class="Identifier">dynlib</span></span><span class="Other">.}</span></span> <span class="Other">=</span>
<span class="Keyword">if</span> <span class="Identifier">sym</span><span class="Other">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">nskProc</span> <span class="Keyword">and</span> <span class="Identifier">sym</span><span class="Other">.</span><span class="Identifier">name</span><span class="Other">.</span><span class="Identifier">contains</span><span class="Other">(</span><span class="StringLit">&quot;SDL_&quot;</span><span class="Other">)</span><span class="Other">:</span>
<span class="Identifier">sym</span><span class="Other">.</span><span class="Identifier">name</span> <span class="Other">=</span> <span class="Identifier">sym</span><span class="Other">.</span><span class="Identifier">name</span><span class="Other">.</span><span class="Identifier">replace</span><span class="Other">(</span><span class="StringLit">&quot;SDL_&quot;</span><span class="Other">,</span> <span class="StringLit">&quot;&quot;</span><span class="Other">)</span>
</pre>
</dd>
<a id="cDefine.m,,string"></a>
<dt><pre><span class="Keyword">macro</span> <a href="#cDefine.m%2C%2Cstring"><span class="Identifier">cDefine</span></a><span class="Other">(</span><span class="Identifier">name</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span><span class="Other">;</span> <span class="Identifier">val</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span> <span class="Other">=</span> <span class="StringLit">&quot;&quot;</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
<tt class="docutils literal"><span class="pre">#define</span></tt> an identifer that is forwarded to the C/C++ preprocessor if called within <a class="reference external" href="cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring">cImport()</a> or <a class="reference external" href="cimport.html#c2nImport.m%2C%2Cstring%2Cstring%2Cstring">c2nImport()</a> as well as to the C/C++ compiler during Nim compilation using <tt class="docutils literal"><span class="pre">{.passC: &quot;-DXXX&quot;.}</span></tt>
</dd>
<a id="cIncludeDir.m"></a>
<dt><pre><span class="Keyword">macro</span> <a href="#cIncludeDir.m"><span class="Identifier">cIncludeDir</span></a><span class="Other">(</span><span class="Identifier">dir</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
Add an include directory that is forwarded to the C/C++ preprocessor if called within <a class="reference external" href="cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring">cImport()</a> or <a class="reference external" href="cimport.html#c2nImport.m%2C%2Cstring%2Cstring%2Cstring">c2nImport()</a> as well as to the C/C++ compiler during Nim compilation using <tt class="docutils literal"><span class="pre">{.passC: &quot;-IXXX&quot;.}</span></tt>.
</dd>
<a id="cCompile.m,,string,string"></a>
<dt><pre><span class="Keyword">macro</span> <a href="#cCompile.m%2C%2Cstring%2Cstring"><span class="Identifier">cCompile</span></a><span class="Other">(</span><span class="Identifier">path</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span><span class="Other">;</span> <span class="Identifier">mode</span> <span class="Other">=</span> <span class="StringLit">&quot;c&quot;</span><span class="Other">;</span> <span class="Identifier">exclude</span> <span class="Other">=</span> <span class="StringLit">&quot;&quot;</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
<p>Compile and link C/C++ implementation into resulting binary using <tt class="docutils literal"><span class="pre">{.compile.}</span></tt></p>
<p><tt class="docutils literal"><span class="pre">path</span></tt> can be a specific file or contain wildcards:</p>
<pre class="listing"><span class="Identifier">cCompile</span><span class="Punctuation">(</span><span class="StringLit">&quot;file.c&quot;</span><span class="Punctuation">)</span>
<span class="Identifier">cCompile</span><span class="Punctuation">(</span><span class="StringLit">&quot;path/to/*.c&quot;</span><span class="Punctuation">)</span></pre><p><tt class="docutils literal"><span class="pre">mode</span></tt> recursively searches for code files in <tt class="docutils literal"><span class="pre">path</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">c</span></tt> searches for <tt class="docutils literal"><span class="pre">*.c</span></tt> whereas <tt class="docutils literal"><span class="pre">cpp</span></tt> searches for <tt class="docutils literal"><span class="pre">*.C *.cpp *.c++ *.cc *.cxx</span></tt></p>
<pre class="listing"><span class="Identifier">cCompile</span><span class="Punctuation">(</span><span class="StringLit">&quot;path/to/dir&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;cpp&quot;</span><span class="Punctuation">)</span></pre><p><tt class="docutils literal"><span class="pre">exclude</span></tt> can be used to exclude files by partial string match. Comma separated to specify multiple exclude strings</p>
<pre class="listing"><span class="Identifier">cCompile</span><span class="Punctuation">(</span><span class="StringLit">&quot;path/to/dir&quot;</span><span class="Punctuation">,</span> <span class="Identifier">exclude</span><span class="Operator">=</span><span class="StringLit">&quot;test2.c&quot;</span><span class="Punctuation">)</span></pre>
</dd>
<a id="cImport.m,,string,string,string"></a>
<dt><pre><span class="Keyword">macro</span> <a href="#cImport.m%2C%2Cstring%2Cstring%2Cstring"><span class="Identifier">cImport</span></a><span class="Other">(</span><span class="Identifier">filename</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span><span class="Other">;</span> <span class="Identifier">recurse</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">bool</span> <span class="Other">=</span> <span class="Identifier">false</span><span class="Other">;</span>
<span class="Identifier">dynlib</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span> <span class="Other">=</span> <span class="StringLit">&quot;&quot;</span><span class="Other">;</span> <span class="Identifier">mode</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span> <span class="Other">=</span> <span class="StringLit">&quot;c&quot;</span><span class="Other">;</span>
<span class="Identifier">flags</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span> <span class="Other">=</span> <span class="StringLit">&quot;&quot;</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
<p>Import all supported definitions from specified header file. Generated content is cached in <tt class="docutils literal"><span class="pre">nimcache</span></tt> until <tt class="docutils literal"><span class="pre">filename</span></tt> changes unless <a class="reference external" href="cimport.html#cDisableCaching">cDisableCaching()</a> is set. <tt class="docutils literal"><span class="pre">nim -f</span></tt> can also be used after Nim v0.19.4 to flush the cache.</p>
<p><tt class="docutils literal"><span class="pre">recurse</span></tt> can be used to generate Nim wrappers from <tt class="docutils literal"><span class="pre">#include</span></tt> files referenced in <tt class="docutils literal"><span class="pre">filename</span></tt>. This is only done for files in the same directory as <tt class="docutils literal"><span class="pre">filename</span></tt> or in a directory added using <a class="reference external" href="cimport.html#cIncludeDir.m">cIncludeDir()</a></p>
<p><tt class="docutils literal"><span class="pre">dynlib</span></tt> can be used to specify the Nim string to use to specify the dynamic library to load the imported symbols from. For example:</p>
<pre class="listing"><span class="Keyword">const</span>
<span class="Identifier">dynpcre</span> <span class="Operator">=</span>
<span class="Keyword">when</span> <span class="Identifier">defined</span><span class="Punctuation">(</span><span class="Identifier">windows</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
<span class="Keyword">when</span> <span class="Identifier">defined</span><span class="Punctuation">(</span><span class="Identifier">cpu64</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
<span class="StringLit">&quot;pcre64.dll&quot;</span>
<span class="Keyword">else</span><span class="Punctuation">:</span>
<span class="StringLit">&quot;pcre32.dll&quot;</span>
<span class="Keyword">elif</span> <span class="Identifier">hostOS</span> <span class="Operator">==</span> <span class="StringLit">&quot;macosx&quot;</span><span class="Punctuation">:</span>
<span class="StringLit">&quot;libpcre(.3|.1|).dylib&quot;</span>
<span class="Keyword">else</span><span class="Punctuation">:</span>
<span class="StringLit">&quot;libpcre.so(.3|.1|)&quot;</span>
<span class="Identifier">cImport</span><span class="Punctuation">(</span><span class="StringLit">&quot;pcre.h&quot;</span><span class="Punctuation">,</span> <span class="Identifier">dynlib</span><span class="Operator">=</span><span class="StringLit">&quot;dynpcre&quot;</span><span class="Punctuation">)</span></pre><p>If <tt class="docutils literal"><span class="pre">dynlib</span></tt> is not specified, the C/C++ implementation files can be compiled in with <a class="reference external" href="cimport.html#cCompile.m%2C%2Cstring%2Cstring">cCompile()</a>, or the <tt class="docutils literal"><span class="pre">{.passL.}</span></tt> pragma can be used to specify the static lib to link.</p>
<p><tt class="docutils literal"><span class="pre">mode</span></tt> is purely for forward compatibility when toast adds C++ support. It can be ignored for the foreseeable future.</p>
<p><tt class="docutils literal"><span class="pre">flags</span></tt> can be used to pass any other command line arguments to <tt class="docutils literal"><span class="pre">toast</span></tt>. A good example would be <tt class="docutils literal"><span class="pre">--prefix</span></tt> and <tt class="docutils literal"><span class="pre">--suffix</span></tt> which strip leading and trailing strings from identifiers, <tt class="docutils literal"><span class="pre">_</span></tt> being quite common.</p>
<p><tt class="docutils literal"><span class="pre">cImport()</span></tt> consumes and resets preceding <tt class="docutils literal"><span class="pre">cOverride()</span></tt> calls. <tt class="docutils literal"><span class="pre">cPlugin()</span></tt> is retained for the next <tt class="docutils literal"><span class="pre">cImport()</span></tt> call unless a new <tt class="docutils literal"><span class="pre">cPlugin()</span></tt> call is defined.</p>
</dd>
<a id="c2nImport.m,,string,string,string"></a>
<dt><pre><span class="Keyword">macro</span> <a href="#c2nImport.m%2C%2Cstring%2Cstring%2Cstring"><span class="Identifier">c2nImport</span></a><span class="Other">(</span><span class="Identifier">filename</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span><span class="Other">;</span> <span class="Identifier">recurse</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">bool</span> <span class="Other">=</span> <span class="Identifier">false</span><span class="Other">;</span>
<span class="Identifier">dynlib</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span> <span class="Other">=</span> <span class="StringLit">&quot;&quot;</span><span class="Other">;</span> <span class="Identifier">mode</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span> <span class="Other">=</span> <span class="StringLit">&quot;c&quot;</span><span class="Other">;</span>
<span class="Identifier">flags</span><span class="Other">:</span> <span class="Identifier">static</span> <span class="Identifier">string</span> <span class="Other">=</span> <span class="StringLit">&quot;&quot;</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
<p>Import all supported definitions from specified header file using <tt class="docutils literal"><span class="pre">c2nim</span></tt></p>
<p>Similar to <a class="reference external" href="cimport.html#cImport.m%2C%2Cstring%2Cstring%2Cstring">cImport()</a> but uses <tt class="docutils literal"><span class="pre">c2nim</span></tt> to generate the Nim wrapper instead of <tt class="docutils literal"><span class="pre">toast</span></tt>. Note that neither <a class="reference external" href="cimport.html#cOverride.m">cOverride()</a>, <a class="reference external" href="cimport.html#cSkipSymbol%2Cseq[T][string]">cSkipSymbol()</a> nor <a class="reference external" href="cimport.html#cPlugin.m">cPlugin()</a> have any impact on <tt class="docutils literal"><span class="pre">c2nim</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">toast</span></tt> is only used to preprocess the header file and recurse if specified.</p>
<p><tt class="docutils literal"><span class="pre">mode</span></tt> should be set to <tt class="docutils literal"><span class="pre">cpp</span></tt> for c2nim to wrap C++ headers.</p>
<p><tt class="docutils literal"><span class="pre">flags</span></tt> can be used to pass other command line arguments to <tt class="docutils literal"><span class="pre">c2nim</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">nimterop</span></tt> does not depend on <tt class="docutils literal"><span class="pre">c2nim</span></tt> as a <tt class="docutils literal"><span class="pre">nimble</span></tt> dependency so it does not get installed automatically. Any wrapper or library that requires this proc needs to install <tt class="docutils literal"><span class="pre">c2nim</span></tt> with <tt class="docutils literal"><span class="pre">nimble install c2nim</span></tt> or add it as a dependency in its own <tt class="docutils literal"><span class="pre">.nimble</span></tt> file.</p>
</dd>
</dl></div>
<div class="section" id="19">
<h1><a class="toc-backref" href="#19">Exports</a></h1>
<dl class="item">
<a href="types.html#va_list"><span class="Identifier">va_list</span></a>, <a href="types.html#defineEnum"><span class="Identifier">defineEnum</span></a>, <a href="types.html#wchar_t"><span class="Identifier">wchar_t</span></a>, <a href="types.html#time_t"><span class="Identifier">time_t</span></a>, <a href="types.html#time64_t"><span class="Identifier">time64_t</span></a>, <a class="reference external" href="types.html">types</a>, <a href="types.html#enumOp"><span class="Identifier">enumOp</span></a>, <a href="types.html#ptrdiff_t"><span class="Identifier">ptrdiff_t</span></a>
</dl></div>
</div>
</div>
<div class="row">
<div class="twelve-columns footer">
<span class="nim-sprite"></span>
<br/>
<small style="color: var(--hint);">Made with Nim. Generated: 2020-03-24 20:55:42 UTC</small>
</div>
</div>
</div>
</div>
</body>
</html>