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. 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.
+ +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 : @@ -1326,31 +908,35 @@ function main() {
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().
+ +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.
+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.
proc cAddSearchDir(dir: string) {...}{.compileTime, raises: [], tags: [].}
proc cAddSearchDir(dir: string) {...}{.compileTime, raises: [], tags: [].}
Examples:
import @@ -1362,8 +948,9 @@ Add directory dir to
proc cAddStdDir(mode = "c") {...}{.compileTime, raises: [], tags: [ReadEnvEffect].}
proc cAddStdDir(mode = "c") {...}{.compileTime, raises: [ValueError], tags: [ReadEnvEffect].}
Examples:
static : @@ -1379,34 +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.
+ +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.
+ 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.
-cPlugin() only affects calls to cImport() that follow it.
+cPlugin() only affects calls to cImport() that follow it.
Examples:
cPlugin: @@ -1428,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".} + +#define an identifer that is forwarded to the C/C++ preprocessor if called within cImport() or c2nImport() as well as to the C/C++ compiler during Nim compilation 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. + +Add an include directory that is forwarded to the C/C++ preprocessor if called within cImport() or c2nImport() as well as to the C/C++ compiler during Nim compilation using {.passC: "-IXXX".}.
-- +
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") @@ -1451,12 +1043,14 @@ Add an include directory that is forwarded to the C/C++ compiler using cCompile("path/to/dir", exclude="test2.c")- + +
macro cImport(filename: static string; recurse: static bool = false; - dynlib: static string = ""): untyped- -
-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()
+ +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:
const dynpcre = @@ -1470,17 +1064,20 @@ Add an include directory that is forwarded to the C/C++ compiler using else: "libpcre.so(.3|.1|)" -cImport("pcre.h", dynlib="dynpcre")If dynlib is not specified, the C/C++ implementation files can be compiled in with cCompile(), or the {.passL.} pragma can be used to specify the static lib to link.
+cImport("pcre.h", dynlib="dynpcre")If dynlib is not specified, the C/C++ implementation files can be compiled in with cCompile(), or the {.passL.} pragma can be used to specify the static lib to link.
+mode is purely for forward compatibility when toast adds C++ support. It can be ignored for the foreseeable future.
+flags can be used to pass any other command line arguments to toast.
- +
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.
+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.
@@ -1489,6 +1086,11 @@ Add an include directory that is forwarded to the C/C++ compiler using +
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], +- +
-Execute an external command - supported at compile time
Checks if command exits successfully before returning. If not, an error is raised.
- +
proc mkDir(dir: string) {...}{.raises: [OSError, Exception], tags: [ReadDirEffect, - ExecIOEffect, ReadIOEffect, RootEffect].}- +
-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.
+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.
- +
proc gitReset(outdir: string) {...}{.raises: [OSError, Exception], tags: [ExecIOEffect, - ReadIOEffect, RootEffect, TimeEffect].}- + Hard reset the git repository at the specified directory
-- +
proc gitCheckout(file, outdir: string) {...}{.raises: [OSError, Exception], 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 to undo any changes that were made to source files to enable successful wrapping with cImport() or c2nImport().
+This effectively resets all changes in the file and can be used to undo any changes that were made to source files to enable successful wrapping with cImport() or c2nImport().
- +
proc gitPull(url: string; outdir = ""; plist = ""; checkout = "") {...}{. - raises: [OSError, Exception, IOError], tags: [ReadDirEffect, ExecIOEffect, - ReadIOEffect, RootEffect, TimeEffect, WriteIOEffect].}- +
-Pull the specified git repository to the output directory
-plist is the list of specific files and directories or wildcards to sparsely checkout. Multiple values can be specified one entry per line. It is optional and if omitted, the entire repository will be checked out.
-checkout is the git tag, branch or commit hash to checkout once the repository is downloaded. This allows for pinning to a specific version of the code.
+plist is the list of specific files and directories or wildcards to sparsely checkout. Multiple values can be specified one entry per line. It is optional and if omitted, the entire repository will be checked out.
+checkout is the git tag, branch or commit hash to checkout once the repository is downloaded. This allows for pinning to a specific version of the code.
- -
-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.
+ +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], 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.
+ +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: [OSError, Exception], tags: [ - ReadDirEffect, ExecIOEffect, ReadIOEffect, RootEffect].}- -
@@ -1406,7 +1008,7 @@ Hard reset the git repository at the specified directoryRun 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.
+ +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)