build based on c42c221

dev/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.8.5","generation_timestamp":"2023-12-24T10:20:24","documenter_version":"1.2.1"}}
+{"documenter":{"julia_version":"1.8.5","generation_timestamp":"2023-12-27T13:57:04","documenter_version":"1.2.1"}}

dev/generator/index.html

@@ -42,4 +42,4 @@
 build!(ctx, BUILDSTAGE_PRINTING_ONLY)</code></pre><h3 id="Multi-platform-configuration"><a class="docs-heading-anchor" href="#Multi-platform-configuration">Multi-platform configuration</a><a id="Multi-platform-configuration-1"></a><a class="docs-heading-anchor-permalink" href="#Multi-platform-configuration" title="Permalink"></a></h3><p>Some headers may contain system-dependent symbols such as <code>long</code> or <code>char</code>, or system-independent symbols may be resolved to system-dependent ones. For example, <code>time_t</code> is usually just a 64-bit unsigned integer, but implementations may conditionally implement it as <code>long</code> or <code>long long</code>, which is not portable. You can skip these symbols and add them back manually as in <a href="#Skipping-specific-symbols">Skipping specific symbols</a>. If the differences are too large to be manually fixed, you can generate wrappers for each platform as in <a href="https://github.com/Gnimuc/LibClang.jl/blob/v0.61.0/gen/generator.jl">LibClang.jl</a>.</p><h2 id="Variadic-Function"><a class="docs-heading-anchor" href="#Variadic-Function">Variadic Function</a><a id="Variadic-Function-1"></a><a class="docs-heading-anchor-permalink" href="#Variadic-Function" title="Permalink"></a></h2><p>With the help of <code>@ccall</code> macro, variadic C functions can be called from Julia. For example, <code>@ccall printf(&quot;%d\n&quot;::Cstring; 123::Cint)::Cint</code> can be used to call the C function <code>printf</code>. Note that those arguments after the semicolon <code>;</code> are variadic arguments.</p><p>If <code>wrap_variadic_function</code> in <code>codegen</code> section of options is set to <code>true</code>, <code>Clang.jl</code> will generate wrappers for variadic C functions. For example, <code>printf</code> will be wrapped as follows.</p><pre><code class="language-julia hljs">@generated function printf(fmt, va_list...)
         :(@ccall(libexample.printf(fmt::Ptr{Cchar}; $(to_c_type_pairs(va_list)...))::Cint))
     end</code></pre><p>It can be called just like normal Julia functions without specifying types: <code>LibExample.printf(&quot;%d\n&quot;, 123)</code>.</p><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>Although variadic functions are supported, the C type <code>va_list</code> cannot be used from Julia.</p></div></div><h3 id="Type-Correspondence"><a class="docs-heading-anchor" href="#Type-Correspondence">Type Correspondence</a><a id="Type-Correspondence-1"></a><a class="docs-heading-anchor-permalink" href="#Type-Correspondence" title="Permalink"></a></h3><p>However, variadic C functions must be called with the correct argument types. The most useful ones are listed below.</p><table><tr><th style="text-align: right">C type</th><th style="text-align: right">ccall signature</th><th style="text-align: right">Julia type</th></tr><tr><td style="text-align: right">Integers and floating point numbers</td><td style="text-align: right">the same type</td><td style="text-align: right">the same type</td></tr><tr><td style="text-align: right">Struct <code>T</code></td><td style="text-align: right">a concrete Julia struct <code>T</code> with the same layout</td><td style="text-align: right"><code>T</code></td></tr><tr><td style="text-align: right">Pointer (<code>T*</code>)</td><td style="text-align: right"><code>Ref{T}</code> or <code>Ptr{T}</code></td><td style="text-align: right"><code>Ref{T}</code> or <code>Ptr{T}</code> or any array type</td></tr><tr><td style="text-align: right">String (<code>char*</code>)</td><td style="text-align: right"><code>Cstring</code> or <code>Ptr{Cchar}</code></td><td style="text-align: right"><code>String</code></td></tr></table><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p><code>Ref</code> is not a concrete type but an abstract type in Julia. For example, <code>Ref(1)</code> is <code>Base.RefValue(1)</code>, which cannot be directly passed to C.</p></div></div><p>As observed from the table, if you want to pass strings or arrays to C, you need to annotate the type as <code>Ptr{T}</code> or <code>Ref{T}</code> (or <code>Cstring</code>). Otherwise, the struct that represents the <code>String</code> or <code>Array</code> type instead of the buffer itself will be passed. There are two methods to pass arguments of these types:</p><ul><li>Directly use the @ccall macro: <code>@ccall printf(&quot;%s\n&quot;; &quot;hello&quot;::Cstring)::Cint</code>. You can also create wrappers for common use cases of this.</li><li>Overload <code>to_c_type</code> to map Julia type to correct ccall signature type: add <code>to_c_type(::Type{String}) = Cstring</code> to prologue (prologue can be added by setting <code>prologue_file_path</code> in options). Then all arguments of type <code>String</code> will be annotated as <code>Cstring</code>.</li></ul><p>The above type correspondence can be implemented by including the following lines in the prologue.</p><pre><code class="language-julia hljs">to_c_type(::Type{&lt;:AbstractString}) = Cstring # or Ptr{Cchar}
-to_c_type(t::Type{&lt;:Union{AbstractArray,Ref}}) = Ptr{eltype(t)}</code></pre><p>For a complete tutorial on calling C functions, refer to <a href="https://docs.julialang.org/en/v1/manual/calling-c-and-fortran-code/#Calling-C-and-Fortran-Code">Calling C and Fortran Code</a> in the Julia manual.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« Introduction</a><a class="docs-footer-nextpage" href="../tutorial/">LibClang Tutorial »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Sunday 24 December 2023 10:20">Sunday 24 December 2023</span>. Using Julia version 1.8.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+to_c_type(t::Type{&lt;:Union{AbstractArray,Ref}}) = Ptr{eltype(t)}</code></pre><p>For a complete tutorial on calling C functions, refer to <a href="https://docs.julialang.org/en/v1/manual/calling-c-and-fortran-code/#Calling-C-and-Fortran-Code">Calling C and Fortran Code</a> in the Julia manual.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« Introduction</a><a class="docs-footer-nextpage" href="../tutorial/">LibClang Tutorial »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Wednesday 27 December 2023 13:57">Wednesday 27 December 2023</span>. Using Julia version 1.8.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>

dev/index.html

@@ -27,4 +27,4 @@
 ctx = create_context(headers, args, options)
 
 # run generator
-build!(ctx)</code></pre><div class="admonition is-info"><header class="admonition-header">Compatibility</header><div class="admonition-body"><p>The generator above is introduced in Clang.jl 0.14. If you are working with older versions of Clang.jl, check <a href="https://juliainterop.github.io/Clang.jl/v0.12/">older versions of documentation</a></p></div></div><h2 id="LibClang"><a class="docs-heading-anchor" href="#LibClang">LibClang</a><a id="LibClang-1"></a><a class="docs-heading-anchor-permalink" href="#LibClang" title="Permalink"></a></h2><p>LibClang is a thin wrapper over libclang. It&#39;s one-to-one mapped to the libclang APIs. By <code>using Clang.LibClang</code>, all of the <code>CX</code>/<code>clang_</code>-prefixed libclang APIs are imported into the current namespace, with which you could build up your own tools from scratch. If you are unfamiliar with the Clang AST, a good starting point is the <a href="http://clang.llvm.org/docs/IntroductionToTheClangAST.html">Introduction to the Clang AST</a>.</p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="generator/">Generator Tutorial »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Sunday 24 December 2023 10:20">Sunday 24 December 2023</span>. Using Julia version 1.8.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
+build!(ctx)</code></pre><div class="admonition is-info"><header class="admonition-header">Compatibility</header><div class="admonition-body"><p>The generator above is introduced in Clang.jl 0.14. If you are working with older versions of Clang.jl, check <a href="https://juliainterop.github.io/Clang.jl/v0.12/">older versions of documentation</a></p></div></div><h2 id="LibClang"><a class="docs-heading-anchor" href="#LibClang">LibClang</a><a id="LibClang-1"></a><a class="docs-heading-anchor-permalink" href="#LibClang" title="Permalink"></a></h2><p>LibClang is a thin wrapper over libclang. It&#39;s one-to-one mapped to the libclang APIs. By <code>using Clang.LibClang</code>, all of the <code>CX</code>/<code>clang_</code>-prefixed libclang APIs are imported into the current namespace, with which you could build up your own tools from scratch. If you are unfamiliar with the Clang AST, a good starting point is the <a href="http://clang.llvm.org/docs/IntroductionToTheClangAST.html">Introduction to the Clang AST</a>.</p></article><nav class="docs-footer"><a class="docs-footer-nextpage" href="generator/">Generator Tutorial »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.2.1 on <span class="colophon-date" title="Wednesday 27 December 2023 13:57">Wednesday 27 December 2023</span>. Using Julia version 1.8.5.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>