Module that should import everything so that nim doc --project nimtero/all runs docs on everything.
+ +Module that should import everything so that nim doc --project nimtero/all runs docs on everything.
This is the main nimterop import file to help with wrapping C/C++ source code.
-Check out template.nim as a starting point for wrapping a new library. The template can be copied and trimmed down and modified as required.
+Check out template.nim as a starting point for wrapping a new library. The template can be copied and trimmed down and modified as required. templite.nim is a shorter version for more experienced users.
All {.compileTime.} procs must be used in a compile time context, e.g. using:
static: cAddStdDir()- -
proc cSkipSymbol(skips: seq[string]) {...}{.compileTime, raises: [], tags: [].}
proc cSkipSymbol(skips: seq[string]) {...}{.compileTime, raises: [], tags: [].}
Similar to cOverride(), this macro allows filtering out symbols not of interest from the generated output.
+cSkipSymbol() only affects calls to cImport() that follow it.
+Examples:
static : cSkipSymbol @["proc1", "Type2"]
proc cSearchPath(path: string): string {...}{.compileTime, raises: [], tags: [ReadDirEffect].}
proc cSearchPath(path: string): string {...}{.compileTime, raises: [], tags: [ReadDirEffect].}
Get full path to file or directory path in search path configured using cAddSearchDir() and cAddStdDir().
This can be used to locate files or directories that can be passed onto cCompile(), cIncludeDir() and cImport().
proc cDebug() {...}{.compileTime, raises: [], tags: [].}
proc cDebug() {...}{.compileTime, raises: [], tags: [].}
proc cDisableCaching() {...}{.compileTime, raises: [], tags: [].}
proc cDisableCaching() {...}{.compileTime, raises: [], tags: [].}
Disable caching of generated Nim code - useful during wrapper development
If files included by header being processed by cImport() change and affect the generated content, they will be ignored and the cached value will continue to be used . Use cDisableCaching() to avoid this scenario during development.
nim -f was broken prior to 0.19.4 but can also be used to flush the cached content.
@@ -1344,8 +934,9 @@ Enable debug messages and display the generated Nim codeproc cAddSearchDir(dir: string) {...}{.compileTime, raises: [], tags: [].}
proc cAddSearchDir(dir: string) {...}{.compileTime, raises: [], tags: [].}
Examples:
import @@ -1357,8 +948,9 @@ Add directory dir to
proc cAddStdDir(mode = "c") {...}{.compileTime, raises: [], tags: [].}
proc cAddStdDir(mode = "c") {...}{.compileTime, raises: [ValueError], tags: [ReadEnvEffect].}
Examples:
static : @@ -1374,32 +966,36 @@ Add the standard c [d+Macros
- -
- + +
macro cOverride(body): untyped- +
- -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 cOverride() macro block so that Nimterop no longer defines these symbols.
For example:
int svGetCallerInfo(const char** fileName, int *lineNumber);This might map to:
proc svGetCallerInfo(fileName: ptr cstring; lineNumber: var cint)Whereas it might mean:
cOverride: proc svGetCallerInfo(fileName: var cstring; lineNumber: var cint)Using the cOverride() block, nimterop can be instructed to skip over svGetCallerInfo(). This works for procs, consts and types.
+cOverride() only affects calls to cImport() that follow it.
- + +
macro cPlugin(body): untyped- -When cOverride() and cSkipSymbol() are not adequate, the cPlugin() macro can be used to customize the generated Nim output. The following callbacks are available at this time.
-proc onSymbol(sym: var Symbol) {.exportc, dynlib.}onSymbol() can be used to handle symbol name modifications required due to invalid characters like leading/trailing _ or rename symbols that would clash due to Nim's style insensitivity. It can also be used to remove prefixes and suffixes like SDL_. The symbol name and type is provided to the callback and the name can be modified.
-Returning a blank name will result in the symbol being skipped. This will fail for nskParam and nskField since the generated Nim code will be wrong.
+ +When cOverride() and cSkipSymbol() are not adequate, the cPlugin() macro can be used to customize the generated Nim output. The following callbacks are available at this time.proc onSymbol(sym: var Symbol) {.exportc, dynlib.}onSymbol() can be used to handle symbol name modifications required due to invalid characters like leading/trailing _ or rename symbols that would clash due to Nim's style insensitivity. It can also be used to remove prefixes and suffixes like SDL_. The symbol name and type is provided to the callback and the name can be modified.
+Returning a blank name will result in the symbol being skipped. This will fail for nskParam and nskField since the generated Nim code will be wrong.
Symbol types can be any of the following:
-
- nskConst for constants
-- nskType for type identifiers, including primitive
-- nskParam for param names
-- nskField for struct field names
-- nskEnumField for enum (field) names, though they are in the global namespace as nskConst
-- nskProc - for proc names
+-
- nskConst for constants
+- nskType for type identifiers, including primitive
+- nskParam for param names
+- nskField for struct field names
+- nskEnumField for enum (field) names, though they are in the global namespace as nskConst
+- nskProc - for proc names
nimterop/plugins is implicitly imported to provide access to standard plugin facilities.
+nimterop/plugins is implicitly imported to provide access to standard plugin facilities.
+cPlugin() only affects calls to cImport() that follow it.
Examples:
cPlugin: @@ -1421,20 +1017,23 @@ When cOverride()<- +
macro cDefine(name: static string; val: static string = ""): untyped- + #define an identifer that is forwarded to the C/C++ compiler using {.passC: "-DXXX".}
- -- + +
macro cIncludeDir(dir: static string): untyped- + Add an include directory that is forwarded to the C/C++ compiler using {.passC: "-IXXX".}. This is also provided to the preprocessor during Nim code generation.
-- +
macro cCompile(path: static string; mode = "c"; exclude = ""): untyped- +
Compile and link C/C++ implementation into resulting binary using {.compile.}
path can be a specific file or contain wildcards:
cCompile("file.c") @@ -1445,9 +1044,10 @@ Add an include directory that is forwarded to the C/C++ compiler using -- +
Import all supported definitions from specified header file. Generated content is cached in nimcache until filename changes unless cDisableCaching() is set. nim -f can also be used after Nim v0.19.4 to flush the cache.
recurse can be used to generate Nim wrappers from #include files referenced in filename. This is only done for files in the same directory as filename or in a directory added using cIncludeDir()
dynlib can be used to specify the Nim string to use to specify the dynamic library to load the imported symbols from. For example:
@@ -1467,7 +1067,27 @@ Add an include directory that is forwarded to the C/C++ compiler using + +- +
macro c2nImport(filename: static string; recurse: static bool = false; + dynlib: static string = ""; mode: static string = "c"; + flags: static string = ""): untyped- +
+ +Import all supported definitions from specified header file using c2nim
+Similar to cImport() but uses c2nim to generate the Nim wrapper instead of toast. Note that neither cOverride(), cSkipSymbol() nor cPlugin() have any impact on c2nim.
+toast is only used to preprocess the header file and recurse if specified.
+mode should be set to cpp for c2nim to wrap C++ headers.
+flags can be used to pass other command line arguments to c2nim.
+nimterop does not depend on c2nim as a nimble dependency so it does not get installed automatically. Any wrapper or library that requires this proc needs to install c2nim with nimble install c2nim or add it as a dependency in its own .nimble file.
+ + +
proc relativePath(file, base: string): string {...}{.raises: [], tags: [].}
Examples:
-import - ospaths, unittest - -check: - "/foo/bar/baz/log.txt".unixToNativePath.relativePath( - "/foo/bar".unixToNativePath) == "baz/log.txt".unixToNativePath - "foo/bar/baz/log.txt".unixToNativePath.relativePath("foo/bar".unixToNativePath) == - "baz/log.txt".unixToNativePath- -
proc execAction(cmd: string; nostderr = false): string {...}{. - raises: [OSError, Exception, ValueError], +- +
-Execute an external command - supported at compile time
+Checks if command exits successfully before returning. If not, an error is raised.
+- +
-Create a directory at cmopile time
+The os module is not available at compile time so a few crucial helper functions are included with nimterop.
+- +Copy a file from source to destination at compile time
-- +Move a file from source to destination at compile time
-- +
proc extractZip(zipfile, outdir: string) {...}{.raises: [OSError, Exception, ValueError], tags: [ - ExecIOEffect, ReadIOEffect, RootEffect].}- +Extract a zip file using powershell on Windows and unzip on other systems to the specified output directory
-- +
proc downloadUrl(url, outdir: string) {...}{.raises: [OSError, Exception, ValueError], tags: [ - ReadDirEffect, ExecIOEffect, ReadIOEffect, RootEffect].}- +
-Download a file using powershell on Windows and curl on other systems to the specified output directory
+If a zip file, it is automatically extracted after download.
+- +Hard reset the git repository at the specified directory
-- +
proc gitCheckout(file, outdir: string) {...}{.raises: [OSError, Exception, ValueError], tags: [ - ExecIOEffect, ReadIOEffect, RootEffect, TimeEffect].}- +
-Checkout the specified file in the git repository specified
+This effectively resets all changes in the file and can be used after cImport() if required.
+- +
- -Pull the specified git repository to the output directory
+plist is the list of specific files and directories or wildcards to sparse checkout. Multiples can be specified one entry per line.
+- + +
proc configure(path, check: string) {...}{.raises: [OSError, Exception, ValueError], tags: [ - ReadDirEffect, ExecIOEffect, ReadIOEffect, RootEffect].}- +
+ +Run the GNU configure command to generate all Makefiles or other build scripts in the specified path
+If a configure script is not present and an autogen.sh script is present, it will be run before attempting configure.
+check is a file that will be generated by the configure command. This is required to prevent configure from running on every build. It is relative to the path and should not be an absolute path.
+flags are any flags that should be passed to the configure command.
+ + +- +
proc cmake(path, check, flags: string) {...}{.raises: [OSError, Exception, IOError, Defect, + ValueError], tags: [ReadDirEffect, ExecIOEffect, ReadIOEffect, RootEffect].}- + +
+ +Run the cmake command to generate all Makefiles or other build scripts in the specified path
+path will be created since typically cmake is run in an empty directory.
+check is a file that will be generated by the cmake command. This is required to prevent cmake from running on every build. It is relative to the path and should not be an absolute path.
+flags are any flags that should be passed to the cmake command. Unlike configure, it is required since typically it will be the path to the repository, typically .. when path is a subdir.
+ + +- +
proc make(path, check: string; flags = "") {...}{.raises: [ValueError, OSError, Exception, + IOError, Defect], tags: [ReadDirEffect, ExecIOEffect, ReadIOEffect, RootEffect].}- + +
@@ -1368,7 +1007,7 @@ function main() {Run the make command to build all binaries in the specified path
+check is a file that will be generated by the make command. This is required to prevent make from running on every build. It is relative to the path and should not be an absolute path.
+flags are any flags that should be passed to the make command.
+
proc nimteropRoot(): string {...}{.raises: [], tags: [].}
proc nimteropRoot(): string {...}{.raises: [], tags: [].}
proc nimteropBuildDir(): string {...}{.raises: [], tags: [].}
proc nimteropBuildDir(): string {...}{.raises: [], tags: [].}
proc nimteropSrcDir(): string {...}{.raises: [], tags: [].}
proc nimteropSrcDir(): string {...}{.raises: [], tags: [].}
proc toastExePath(): string {...}{.raises: [], tags: [].}
proc toastExePath(): string {...}{.raises: [], tags: [].}
proc incDir(): string {...}{.raises: [], tags: [].}
proc incDir(): string {...}{.raises: [], tags: [].}
proc testsIncludeDir(): string {...}{.raises: [], tags: [].}
proc testsIncludeDir(): string {...}{.raises: [], tags: [].}
template enumOp(op, typ, typout)
template enumOp(op, typ, typout)
template defineEnum(typ)
template defineEnum(typ)