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

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

-d:xxxConan - download headers and binary from Conan.io using conanuri with

format pkgname[/version[@user/channel][:bhash]]

-d:xxxJBB - download headers and binary from BinaryBuilder.org using jbburi with

format pkgname[/version]

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. The user can opt to download the sources to outdir using any other method such as git sub-modules, vendoring or pointing to a repository that was already cloned.

If multiple -d:xxx defines are specified, precedence is Std and then Git, DL, Conan or JBB. This allows using a system installed library if available before falling back to manual building. The user would need to specify both -d:xxxStd and one of the other methods.

-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, Conan and JBB, it replaces $1 in the URL if specified. Specifying -d:xxxSetVer without a $1 will download that version for Conan and JBB if available. If no version is specified, the latest release of the package is downloaded. For Conan, -d:xxxSetVer can also be used to set additional

URI information:

-d:xxxSetVer=1.9.0@bincrafters/stable:bhash

If conanuri or jbburi are not defined and Conan or JBB is selected, the header filename is used instead.

All defines can also be set in code using setDefines() and checked for using isDefined() which checks for defines set from both -d and 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, or using -d:xxxConan or -d:xxxJBB which download pre-built 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 cPassL(). Any dependency libraries downloaded by Conan or JBB are returned in const xxxLDeps as a seq[string].

libdir can be used to instruct getHeader() to copy shared libraries and their dependencies to that directory. This prevents any runtime failures if outdir gets removed or its contents changed. By default, libdir is set to the output directory where the program binary will be created. The values of xxxLPath and xxxLDeps will reflect this new location. libdir is ignored for Std mode.

-d:xxxStatic can be specified to statically link with the library instead. This will automatically add a cPassL() call to the static library for convenience. Note that -d:xxxConan and -d:xxxJBB download all dependency libs as well and the xxxLPath will include paths to all of them separated by space in the right order for linking.

Note also that Conan currently builds all OSX binaries on 10.14 so older versions of OSX will complain if statically linking to these binaries. Further, all Conan binaries for Windows are built with Visual Studio so static linking the .lib files with gcc or clang might lead to incompatibility issues if the library uses Visual Studio specific compiler features.

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.

conanFlags and jbbFlags allow changing the Conan.io and BinaryBuilder.org defaults:

• skip=pkg1,pkg2 skips the specified packages which are required dependencies of the package in question. This enables downloading those dependencies from other sources if required.

jbbFlags allows two additional customizations:

• giturl=customUrl changes the default https://github.com/JuliaBinaryWrappers to another Git URL. If no hostname is specified, https://github.com is assumed.
• url=customUrl uses regular HTTP instead of Git and looks for Artifacts.toml and Project.toml files at that location. $1 or $# are replaced with the version if specified.

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. However, it is libzlib.dll on Windows if built with cmake. In this case, altNames = "z,zlib". Comma separate for multiple alternate names without spaces.

The original header name is not included by default if altNames is set since it could cause the wrong lib to be selected. E.g. SDL2/SDL.h could pick libSDL.so even if altNames = "SDL2". Explicitly include it in altNames like the zlib example when required.

buildTypes specifies a list of ordered build strategies to use when building the downloaded source files. Default is [btCmake, btAutoconf]

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.