Doc updates

CHANGES.md

@@ -15,7 +15,7 @@ Refer to the documentation for `getHeader()` for details on how to use this new
 
 See the full list of changes here:
 
-https://github.com/nimterop/nimterop/compare/v0.5.9...v0.6.3
+https://github.com/nimterop/nimterop/compare/v0.5.9...v0.6.5
 
 ### Breaking changes
 
@@ -27,6 +27,8 @@ https://github.com/nimterop/nimterop/compare/v0.5.9...v0.6.3
 
 - Nameless enum values are no longer typed to the made-up enum type name, they are instead typed as `cint` to match the underlying type. This allows using such enums without having to depend on the made-up name which could change if enum ordering changes upstream. [#236][i236] (since v0.6.1)
 
+- Static libraries installed and linked with `getHeader()` now have their `{.passL.}` pragmas forwarded to the generated wrapper. This might lead to link errors in existing wrappers if other dependencies are specified with `{.passL.}` calls and the order of linking is wrong. This can be fixed by changing such explicit `{.passL.}` calls with `cPassL()` which will forward the link call to the generated wrapper as well. (since v0.6.5)
+
 ### New functionality
 
 - `getHeader()` now detects and links against `.lib` files as part of enabling Conan.io. Not all `.lib` files are compatible with MinGW as already stated above but for those that work, this is a required capability.
@@ -43,6 +45,12 @@ https://github.com/nimterop/nimterop/compare/v0.5.9...v0.6.3
 
 - It is now possible to exclude the contents of specific files or entire directories from the wrapped output using `--exclude | -X` with `toast` or `cExclude()` from a wrapper. This might be required when a header uses `#include` to pull in external dependencies. E.g. `sciter` has a `#include <gtk/gtk.h>` which pulls in the entire GTK ecosystem which is needed for successful preprocessing but we do not want to include those headers in the wrapped output when using `--recurse | -r`. (since v0.6.4)
 
+- All `cDefine()`, `cIncludeDir()` and `cCompile()` calls now forward relevant pragmas into the generated wrapper further enabling standalone wrappers. [#239][i239]
+
+- Added `cPassC()` and `cPassL()` to forward C/C++ compilation pragmas into the generated wrapper. (since v0.6.5)
+
+- Added `--compile`, `--passC` and `--passL` flags to `toast` to enable the previous two improvements. (since v0.6.5)
+
 ### Other improvements
 
 - Generated wrappers no longer depend on nimterop being present - no more `import nimterop/types`. Supporting code is directly included in the wrapper output and only when required. E.g. enum macro is only included if wrapper contains enums. [#125][i125] (since v0.6.1)
@@ -51,6 +59,7 @@ https://github.com/nimterop/nimterop/compare/v0.5.9...v0.6.3
 
 - `cIncludeDir()` can now accept a `seq[string]` of directories and an optional `exclude` param which sets those include directories to not be included in the wrapped output. (since v0.6.4)
 
+- `cDefine()` can now accept a `seq[string]` of values. (since v0.6.5)
 
 ## Version 0.5.0
 
@@ -140,4 +149,5 @@ https://github.com/nimterop/nimterop/compare/v0.4.4...v0.5.4
 [i197]: https://github.com/nimterop/nimterop/issues/197
 [i200]: https://github.com/nimterop/nimterop/issues/200
 [i236]: https://github.com/nimterop/nimterop/issues/236
-[i237]: https://github.com/nimterop/nimterop/issues/237
+[i237]: https://github.com/nimterop/nimterop/issues/237
+[i239]: https://github.com/nimterop/nimterop/issues/239

README.md

@@ -218,10 +218,12 @@ Options:
   -h, --help                              print this cligen-erated help
   --help-syntax                           advanced: prepend,plurals,..
   -k, --check          bool      false    check generated wrapper with compiler
+  --compile=           strings   {}       create {.compile.} entries in generated wrapper
   -C=, --convention=   string    "cdecl"  calling convention for wrapped procs
   -d, --debug          bool      false    enable debug output
   -D=, --defines=      strings   {}       definitions to pass to preprocessor
-  -l=, --dynlib=       string    ""       {.dynlib.} pragma to import symbols - Nim const string or file path
+  -l=, --dynlib=       string    ""       {.dynlib.} pragma to import symbols - Nim const string or
+                                          file path
   -X=, --exclude=      strings   {}       files or directories to exclude from the wrapped output
   -f=, --feature=      Features  {}       flags to enable experimental features
   -I=, --includeDirs=  strings   {}       include directory to pass to preprocessor
@@ -230,6 +232,8 @@ Options:
   -c, --noComments     bool      false    exclude top-level comments from output
   -H, --noHeader       bool      false    skip {.header.} pragma in wrapper
   -o=, --output=       string    ""       file to output content - default: stdout
+  --passC=             strings   {}       create {.passC.} entries in generated wrapper
+  --passL=             strings   {}       create {.passL.} entries in generated wrapper
   -a, --past           bool      false    print AST output
   --pluginSourcePath=  string    ""       nim file to build and load as a plugin
   -n, --pnim           bool      false    print Nim output

nimterop/cimport.nim

@@ -368,6 +368,8 @@ macro cDefine*(name: static[string], val: static[string] = ""): untyped =
   ## `#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".}`
+  ##
+  ## This needs to be called before `cImport()` to take effect.
   var str = name
   if val.nBl:
     str &= &"={val.quoteShell}"
@@ -379,6 +381,8 @@ macro cDefine*(values: static seq[string]): untyped =
   ## `#define` multiple identifers that are 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".}`
+  ##
+  ## This needs to be called before `cImport()` to take effect.
   for value in values:
     let
       spl = value.split("=", maxsplit = 1)
@@ -390,11 +394,15 @@ macro cDefine*(values: static seq[string]): untyped =
 macro cPassC*(value: static string): untyped =
   ## Create a `{.passC.}` entry that gets forwarded to the C/C++ compiler
   ## during Nim compilation.
+  ##
+  ## This needs to be called before `cImport()` to take effect.
   gStateCT.passC.add value
 
 macro cPassL*(value: static string): untyped =
   ## Create a `{.passL.}` entry that gets forwarded to the C/C++ compiler
   ## during Nim compilation.
+  ##
+  ## This needs to be called before `cImport()` to take effect.
   gStateCT.passL.add value
 
 proc cAddSearchDir*(dir: string) {.compileTime.} =
@@ -416,6 +424,8 @@ macro cIncludeDir*(dirs: static seq[string], exclude: static[bool] = false): unt
   ##
   ## Set `exclude = true` if the contents of these include directories should
   ## not be included in the wrapped output.
+  ##
+  ## This needs to be called before `cImport()` to take effect.
   for dir in dirs:
     let fullpath = findPath(dir)
     if fullpath notin gStateCT.includeDirs:
@@ -430,6 +440,8 @@ macro cIncludeDir*(dir: static[string], exclude: static[bool] = false): untyped
   ##
   ## Set `exclude = true` if the contents of this include directory should
   ## not be included in the wrapped output.
+  ##
+  ## This needs to be called before `cImport()` to take effect.
   return quote do:
     cIncludeDir(@[`dir`], `exclude` == 1)