Procs
+-
+
+
proc sanitizePath(path: string; noQuote = false; sep = $'/'): string {...}{.raises: [], tags: [].}
+- + + + + + +
proc sleep(milsecs: int) {...}{.raises: [], tags: [].}
+- + +Sleep at compile time + + + +
proc execAction(cmd: string; retry = 0; nostderr = false): string {...}{. + raises: [OSError, Exception, IOError, Defect], + tags: [ExecIOEffect, ReadIOEffect, RootEffect].}
+-
+
+
Execute an external command - supported at compile time
+Checks if command exits successfully before returning. If not, an error is raised.
+ + +
+
+ proc findExe(exe: string): string {...}{.raises: [], tags: [].}
+- + +Find the specified executable using the which/where command - supported at compile time + + + +
proc mkDir(dir: string) {...}{.raises: [OSError, Exception, IOError, Defect, ValueError], tags: [ + ReadDirEffect, ExecIOEffect, ReadIOEffect, RootEffect].}
+-
+
+
Create a directory at compile time
+The os module is not available at compile time so a few crucial helper functions are included with nimterop.
+ + +
+
+ proc cpFile(source, dest: string; move = false) {...}{. + raises: [OSError, Exception, IOError, Defect, ValueError], + tags: [ExecIOEffect, ReadIOEffect, RootEffect].}
+- + +Copy a file from source to dest at compile time + + + +
proc mvFile(source, dest: string) {...}{.raises: [OSError, Exception, IOError, Defect, + ValueError], + tags: [ExecIOEffect, ReadIOEffect, RootEffect].}
+- + +Move a file from source to dest at compile time + + + +
proc rmFile(source: string; dir = false) {...}{.raises: [OSError, Exception, IOError, Defect, + ValueError], tags: [ExecIOEffect, ReadIOEffect, RootEffect].}
+- + +Remove a file or pattern at compile time + + + +
proc rmDir(source: string) {...}{.raises: [OSError, Exception, IOError, Defect, ValueError], + tags: [ExecIOEffect, ReadIOEffect, RootEffect].}
+- + +Remove a directory or pattern at compile time + + + +
proc extractZip(zipfile, outdir: string) {...}{.raises: [OSError, Exception, IOError, Defect, + ValueError], tags: [ExecIOEffect, ReadIOEffect, RootEffect].}
+- + +Extract a zip file using powershell on Windows and unzip on other systems to the specified output directory + + + +
proc extractTar(tarfile, outdir: string) {...}{.raises: [ValueError, OSError, Exception, + IOError, Defect], tags: [ExecIOEffect, ReadIOEffect, RootEffect].}
+- + +Extract a tar file using tar, 7z or 7za to the specified output directory + + + +
proc downloadUrl(url, outdir: string) {...}{.raises: [OSError, Exception, IOError, Defect, + ValueError], tags: [ReadDirEffect, ExecIOEffect, ReadIOEffect, RootEffect].}
+-
+
+
Download a file using curl or wget (or powershell on Windows) to the specified directory
+If an archive file, it is automatically extracted after download.
+ + +
+
+ proc gitReset(outdir: string) {...}{.raises: [ValueError, OSError, Exception, IOError, Defect], + tags: [ExecIOEffect, ReadIOEffect, RootEffect].}
+- + +Hard reset the git repository at the specified directory + + + +
proc gitCheckout(file, outdir: string) {...}{.raises: [ValueError, OSError, Exception, + IOError, Defect], tags: [ExecIOEffect, ReadIOEffect, RootEffect].}
+-
+
+
Checkout the specified file in the git repository at outdir
+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: [ValueError, OSError, Exception, IOError, Defect], tags: [ReadDirEffect, + ExecIOEffect, ReadIOEffect, RootEffect, 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.
+ + +
+
+ proc findFile(file: string | Regex; dir: string; recurse = true; first = false): string
+-
+
+
Find the file in the specified directory
+file can be a string or a regex object
+Turn off recursive search with recurse and stop on first match with first. Without it, the shortest match is returned.
+ + +
+
+ proc flagBuild(base: string; flags: openArray[string]): string {...}{.raises: [ValueError], + tags: [].}
+-
+
+
Simple helper proc to generate flags for configure, cmake, etc.
+Every entry in flags is replaced into the base string and concatenated to the result.
+- E.g. +
- base = "--disable-$#" flags = @["one", "two"] +
flagBuild(base, flags) => " --disable-one --disable-two"
+ + +
+
+ proc configure(path, check: string; flags = "") {...}{. + raises: [OSError, Exception, IOError, Defect, 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.
+Next, if configure.ac or configure.in exist, autoreconf will be executed.
+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 getCmakeIncludePath(paths: openArray[string]): string {...}{.raises: [], tags: [].}
+-
+
+
Create a cmake flag to specify custom include paths
+Result can be included in the flag parameter for cmake() or the cmakeFlags parameter for getHeader().
+ + +
+
+ proc setCmakeProperty(outdir, name, property, value: string) {...}{. + raises: [IOError, ValueError], + tags: [ReadDirEffect, WriteIOEffect, ReadIOEffect].}
+-
+
+
Set a cmake property in outdir / CMakeLists.txt - usable in the xxxPreBuild hook for getHeader()
+set_target_properties(name PROPERTIES property "value")
+ + +
+
+ proc setCmakeLibName(outdir, name, prefix = ""; oname = ""; suffix = "") {...}{. + raises: [ValueError, IOError], + tags: [ReadDirEffect, WriteIOEffect, ReadIOEffect].}
+-
+
+
Set a cmake property in outdir / CMakeLists.txt to specify a custom library output name - usable in the xxxPreBuild hook for getHeader()
+prefix is typically lib oname is the library name suffix is typically .a
+Sometimes, cmake generates non-standard library names - e.g. zlib compiles to libzlibstatic.a on Windows. This proc can help rename it to libzlib.a so that getHeader() can find it after the library is compiled.
++set_target_properties(name PROPERTIES PREFIX "prefix") +set_target_properties(name PROPERTIES OUTPUT_NAME "oname") +set_target_properties(name PROPERTIES SUFFIX "suffix") +
+ + +
+
+ proc setCmakePositionIndependentCode(outdir: string) {...}{.raises: [IOError], + tags: [ReadDirEffect, ReadIOEffect, WriteIOEffect].}
+- + +Set a cmake directive to create libraries with -fPIC enabled + + + +
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 | Regex; flags = "")
+-
+
+
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.
+If make.exe is missing and mingw32-make.exe is available, it will be copied over to make.exe in the same location.
+ + +
+
+ proc getGccPaths(mode = "c"): seq[string] {...}{.raises: [ValueError], tags: [ReadEnvEffect].}
+- + + + + + +
proc getGccLibPaths(mode = "c"): seq[string] {...}{.raises: [ValueError], + tags: [ReadEnvEffect].}
+- + + + + + +
Macros
+-
+
+
macro setDefines(defs: static openArray[string]): untyped
+-
+
+
Specify -d:xxx values in code instead of having to rely on the command line or cfg or nims files.
+At this time, Nim does not allow creation of -d:xxx defines in code. In addition, Nim only loads config files for the module being compiled but not for imported packages. This becomes a challenge when wanting to ship a wrapper library that wants to control getHeader() for an underlying package.
+
+E.g. nimarchive wanting to set -d:lzmaStatic
The consumer of nimarchive would need to set such defines as part of their project, making it inconvenient.
+By calling this proc with the defines preferred before importing such a module, the caller can set the behavior in code instead.
+setDefines(@["lzmaStatic", "lzmaDL", "lzmaSetVer=5.2.4"]) + +import lzma
+ +
+
+ macro clearDefines(): untyped
+- + +Clear all defines set using setDefines(). + + + +
macro getHeader(header: static[string]; giturl: static[string] = ""; + dlurl: static[string] = ""; outdir: static[string] = ""; + conFlags: static[string] = ""; cmakeFlags: static[string] = ""; + makeFlags: static[string] = ""; altNames: static[string] = ""): untyped
+-
+
+
Get the path to a header file for wrapping with cImport() or c2nImport().
+This proc checks -d:xxx defines based on the header name (e.g. lzma from lzma.h), and accordingly employs different ways to obtain the source.
+-d:xxxStd - search standard system paths. E.g. /usr/include and /usr/lib on Linux -d:xxxGit - clone source from a git repo specified in giturl -d:xxxDL - download source from dlurl and extract if required
+This allows a single wrapper to be used in different ways depending on the user's needs. If no -d:xxx defines are specified, outdir will be searched for the header as is.
+-d:xxxSetVer=x.y.z can be used to specify which version to use. It is used as a tag name for Git whereas for DL, it replaces $1 in the URL defined.
+All defines can also be set in code using setDefines().
+The library is then configured (with cmake or autotools if possible) and built using make, unless using -d:xxxStd which presumes that the system package manager was used to install prebuilt headers and binaries.
+The header path is stored in const xxxPath and can be used in a cImport() call in the calling wrapper. The dynamic library path is stored in const xxxLPath and can be used for the dynlib parameter (within quotes) or with {.passL.}.
+-d:xxxStatic can be specified to statically link with the library instead. This will automatically add a {.passL.} call to the static library for convenience.
+conFlags, cmakeFlags and makeFlags allow sending custom parameters to configure, cmake and make in case additional configuration is required as part of the build process.
+altNames is a list of alternate names for the library - e.g. zlib uses zlib.h for the header but the typical lib name is libz.so and not libzlib.so. In this case, altNames = "z". Comma separate for multiple alternate names.
+xxxPreBuild is a hook that is called after the source code is pulled from Git or downloaded but before the library is built. This might be needed if some initial prep needs to be done before compilation. A few values are provided to the hook to help provide context:
+outdir is the same outdir passed in and header is the discovered header path in the downloaded source code.
+Simply define proc xxxPreBuild(outdir, header: string) in the wrapper and it will get called prior to the build process.
+ + +
+
+