Update documentation

This commit is contained in:
Ganesh Viswanathan 2019-01-23 19:58:21 -06:00
commit 674f008fe8
4 changed files with 98 additions and 56 deletions

View file

@ -16,7 +16,7 @@
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
<!-- CSS -->
<title>Module cimport</title>
<title>cimport</title>
<style type="text/css" >
/*
Stylesheet for use with Docutils/rst2html.
@ -1199,7 +1199,7 @@ span.pragmawrap {
</style>
<script type="text/javascript" src="../dochack.js"></script>
<script type="text/javascript" src="dochack.js"></script>
<script type="text/javascript">
function main() {
@ -1219,7 +1219,7 @@ function main() {
<body onload="main()">
<div class="document" id="documentId">
<div class="container">
<h1 class="title">Module cimport</h1>
<h1 class="title">cimport</h1>
<div class="row">
<div class="three columns">
<div id="global-links">
@ -1253,7 +1253,7 @@ function main() {
<li>
<a class="reference reference-toplevel" href="#12" id="62">Procs</a>
<ul class="simple simple-toc-section">
<li><a class="reference" href="#cSearchPath,string"
<li><a class="reference" href="#cSearchPath%2Cstring"
title="cSearchPath(path: string): string"><wbr />c<wbr />Search<wbr />Path<span class="attachedType" style="visibility:hidden"></span></a></li>
</ul>
@ -1261,21 +1261,25 @@ function main() {
<li>
<a class="reference reference-toplevel" href="#17" id="67">Macros</a>
<ul class="simple simple-toc-section">
<li><a class="reference" href="#cDebug.m,"
<li><a class="reference" href="#cOverride.m%2C"
title="cOverride(body): untyped"><wbr />c<wbr />Override<span class="attachedType" style="visibility:hidden"></span></a></li>
<li><a class="reference" href="#cSkipSymbol.m%2Cvarargs%5Bstring%5D"
title="cSkipSymbol(skips: varargs[string]): untyped"><wbr />c<wbr />Skip<wbr />Symbol<span class="attachedType" style="visibility:hidden"></span></a></li>
<li><a class="reference" href="#cDebug.m%2C"
title="cDebug(): untyped"><wbr />c<wbr />Debug<span class="attachedType" style="visibility:hidden"></span></a></li>
<li><a class="reference" href="#cDisableCaching.m,"
<li><a class="reference" href="#cDisableCaching.m%2C"
title="cDisableCaching(): untyped"><wbr />c<wbr />Disable<wbr />Caching<span class="attachedType" style="visibility:hidden"></span></a></li>
<li><a class="reference" href="#cDefine.m,,string"
<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" style="visibility:hidden"></span></a></li>
<li><a class="reference" href="#cAddSearchDir.m,"
<li><a class="reference" href="#cAddSearchDir.m%2C"
title="cAddSearchDir(dir: static string): untyped"><wbr />c<wbr />Add<wbr />Search<wbr />Dir<span class="attachedType" style="visibility:hidden"></span></a></li>
<li><a class="reference" href="#cIncludeDir.m,"
<li><a class="reference" href="#cIncludeDir.m%2C"
title="cIncludeDir(dir: static string): untyped"><wbr />c<wbr />Include<wbr />Dir<span class="attachedType" style="visibility:hidden"></span></a></li>
<li><a class="reference" href="#cAddStdDir.m,string"
<li><a class="reference" href="#cAddStdDir.m%2Cstring"
title="cAddStdDir(mode = &quot;c&quot;): untyped"><wbr />c<wbr />Add<wbr />Std<wbr />Dir<span class="attachedType" style="visibility:hidden"></span></a></li>
<li><a class="reference" href="#cCompile.m,,string"
<li><a class="reference" href="#cCompile.m%2C%2Cstring"
title="cCompile(path: static string; mode = &quot;c&quot;): untyped"><wbr />c<wbr />Compile<span class="attachedType" style="visibility:hidden"></span></a></li>
<li><a class="reference" href="#cImport.m,"
<li><a class="reference" href="#cImport.m%2C"
title="cImport(filename: static string; recurse: static bool = false): untyped"><wbr />c<wbr />Import<span class="attachedType" style="visibility:hidden"></span></a></li>
</ul>
@ -1300,10 +1304,11 @@ function main() {
<div class="section" id="12">
<h1><a class="toc-backref" href="#12">Procs</a></h1>
<dl class="item">
<dt id="cSearchPath"><a name="cSearchPath,string"></a><pre><span class="Keyword">proc</span> <span class="Identifier">cSearchPath</span><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>
<a id="cSearchPath,string"></a>
<dt><pre><span class="Keyword">proc</span> <span class="Identifier">cSearchPath</span><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>Return a file or directory found in search path configured using <tt class="docutils literal"><span class="pre">cSearchPath()</span></tt></p>
<p>This proc can be used to locate files or directories in calls to <tt class="docutils literal"><span class="pre">cCompile()</span></tt>, <tt class="docutils literal"><span class="pre">cIncludeDir()</span></tt> and <tt class="docutils literal"><span class="pre">cImport()</span></tt>.</p>
<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.m,">cAddSearchDir()</a> and <a class="reference external" href="cimport.html#cAddStdDir.m,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,,string">cCompile()</a>, <a class="reference external" href="cimport.html#cIncludeDir.m,">cIncludeDir()</a> and <a class="reference external" href="cimport.html#cImport.m,">cImport()</a>.</p>
</dd>
@ -1312,46 +1317,71 @@ function main() {
<div class="section" id="17">
<h1><a class="toc-backref" href="#17">Macros</a></h1>
<dl class="item">
<dt id="cDebug"><a name="cDebug.m,"></a><pre><span class="Keyword">macro</span> <span class="Identifier">cDebug</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<a id="cOverride.m,"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cOverride</span><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 no longer defines these symbols.</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 could get mapped 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 skip over <tt class="docutils literal"><span class="pre">svGetCallerInfo()</span></tt>. This works for procs, consts and types.</p>
</dd>
<a id="cSkipSymbol.m,varargs[string]"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cSkipSymbol</span><span class="Other">(</span><span class="Identifier">skips</span><span class="Other">:</span> <span class="Identifier">varargs</span><span class="Other">[</span><span class="Identifier">string</span><span class="Other">]</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
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.<pre class="listing"><span class="Identifier">cSkipSymbol</span> <span class="StringLit">&quot;proc1&quot;</span><span class="Punctuation">,</span> <span class="StringLit">&quot;Type2&quot;</span></pre>
</dd>
<a id="cDebug.m,"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cDebug</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
Enable debug messages and display the generated Nim code
</dd>
<dt id="cDisableCaching"><a name="cDisableCaching.m,"></a><pre><span class="Keyword">macro</span> <span class="Identifier">cDisableCaching</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<a id="cDisableCaching.m,"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cDisableCaching</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
<p>Disable caching of generated Nim code - useful during wrapper development</p>
<p>If files included by header bring processed by <tt class="docutils literal"><span class="pre">cImport()</span></tt> change and affect the generated content, <tt class="docutils literal"><span class="pre">cImport()</span></tt> won't detect the change and use the cached value. Use <tt class="docutils literal"><span class="pre">cDisableCaching()</span></tt> to avoid this scenario.</p>
<p><tt class="docutils literal"><span class="pre">nim -f</span></tt> is currently broken but will eventually allow forcing regeneration.</p>
<p>If files included by header being processed by <a class="reference external" href="cimport.html#cImport.m,">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.m,">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>
<dt id="cDefine"><a name="cDefine.m,,string"></a><pre><span class="Keyword">macro</span> <span class="Identifier">cDefine</span><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>
<a id="cDefine.m,,string"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cDefine</span><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++ compiler using <tt class="docutils literal"><span class="pre">{.passC: &quot;-DXXX&quot;.}</span></tt>
</dd>
<dt id="cAddSearchDir"><a name="cAddSearchDir.m,"></a><pre><span class="Keyword">macro</span> <span class="Identifier">cAddSearchDir</span><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>
<a id="cAddSearchDir.m,"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cAddSearchDir</span><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>
<p>Add directory <tt class="docutils literal"><span class="pre">dir</span></tt> to the search path used in calls to <tt class="docutils literal"><span class="pre">cSearchPath()</span></tt></p>
<p>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>
<p>This allows something like this:</p>
<pre class="listing"><span class="Identifier">cAddSearchDir</span><span class="Punctuation">(</span><span class="StringLit">&quot;path/to/includes&quot;</span><span class="Punctuation">)</span>
<span class="Identifier">cImport</span> <span class="Identifier">cSearchPath</span><span class="Punctuation">(</span><span class="StringLit">&quot;file.h&quot;</span><span class="Punctuation">)</span></pre>
</dd>
<dt id="cIncludeDir"><a name="cIncludeDir.m,"></a><pre><span class="Keyword">macro</span> <span class="Identifier">cIncludeDir</span><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>
<a id="cIncludeDir.m,"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cIncludeDir</span><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++ compiler using <tt class="docutils literal"><span class="pre">{.passC: &quot;-IXXX&quot;.}</span></tt>
Add an include directory that is forwarded to the C/C++ compiler using <tt class="docutils literal"><span class="pre">{.passC: &quot;-IXXX&quot;.}</span></tt>. This is also provided to the preprocessor during Nim code generation.
</dd>
<dt id="cAddStdDir"><a name="cAddStdDir.m,string"></a><pre><span class="Keyword">macro</span> <span class="Identifier">cAddStdDir</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="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<a id="cAddStdDir.m,string"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cAddStdDir</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="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<dd>
<p>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 <tt class="docutils literal"><span class="pre">cSearchPath()</span></tt></p>
<p>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>
<p>This allows something like this:</p>
<pre class="listing"><span class="Identifier">cAddStdDir</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
<span class="Identifier">cImport</span> <span class="Identifier">cSearchPath</span><span class="Punctuation">(</span><span class="StringLit">&quot;math.h&quot;</span><span class="Punctuation">)</span></pre>
</dd>
<dt id="cCompile"><a name="cCompile.m,,string"></a><pre><span class="Keyword">macro</span> <span class="Identifier">cCompile</span><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="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<a id="cCompile.m,,string"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cCompile</span><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="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>
@ -1361,10 +1391,11 @@ Add an include directory that is forwarded to the C/C++ compiler using <tt class
<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>
</dd>
<dt id="cImport"><a name="cImport.m,"></a><pre><span class="Keyword">macro</span> <span class="Identifier">cImport</span><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="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
<a id="cImport.m,"></a>
<dt><pre><span class="Keyword">macro</span> <span class="Identifier">cImport</span><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="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 <tt class="docutils literal"><span class="pre">cDisableCaching()</span></tt> is set.</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 <tt class="docutils literal"><span class="pre">cIncludeDir()</span></tt>.</p>
<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.m,">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>
</dd>
@ -1378,7 +1409,7 @@ Add an include directory that is forwarded to the C/C++ compiler using <tt class
<div class="twelve-columns footer">
<span class="nim-sprite"></span>
<br/>
<small>Made with Nim. Generated: 2019-01-21 17:06:38 UTC</small>
<small>Made with Nim. Generated: 2019-01-24 01:58:20 UTC</small>
</div>
</div>
</div>