Skip to content

Commit 44f335c

Browse files
genotrancegenotrance
committed
Doc updates
1 parent aa813bd commit 44f335c

File tree

3 files changed

+29
-3
lines changed

3 files changed

+29
-3
lines changed

‎CHANGES.md

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Refer to the documentation for `getHeader()` for details on how to use this new
1515

1616
See the full list of changes here:
1717

18-
https://github.com/nimterop/nimterop/compare/v0.5.9...v0.6.3
18+
https://github.com/nimterop/nimterop/compare/v0.5.9...v0.6.5
1919

2020
### Breaking changes
2121

@@ -27,6 +27,8 @@ https://github.com/nimterop/nimterop/compare/v0.5.9...v0.6.3
2727

2828
- 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)
2929

30+
- 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)
31+
3032
### New functionality
3133

3234
- `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
4345

4446
- 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)
4547

48+
- All `cDefine()`, `cIncludeDir()` and `cCompile()` calls now forward relevant pragmas into the generated wrapper further enabling standalone wrappers. [#239][i239]
49+
50+
- Added `cPassC()` and `cPassL()` to forward C/C++ compilation pragmas into the generated wrapper. (since v0.6.5)
51+
52+
- Added `--compile`, `--passC` and `--passL` flags to `toast` to enable the previous two improvements. (since v0.6.5)
53+
4654
### Other improvements
4755

4856
- 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
5159

5260
- `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)
5361

62+
- `cDefine()` can now accept a `seq[string]` of values. (since v0.6.5)
5463

5564
## Version 0.5.0
5665

@@ -140,4 +149,5 @@ https://github.com/nimterop/nimterop/compare/v0.4.4...v0.5.4
140149
[i197]: https://github.com/nimterop/nimterop/issues/197
141150
[i200]: https://github.com/nimterop/nimterop/issues/200
142151
[i236]: https://github.com/nimterop/nimterop/issues/236
143-
[i237]: https://github.com/nimterop/nimterop/issues/237
152+
[i237]: https://github.com/nimterop/nimterop/issues/237
153+
[i239]: https://github.com/nimterop/nimterop/issues/239

‎README.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -218,10 +218,12 @@ Options:
218218
-h, --help print this cligen-erated help
219219
--help-syntax advanced: prepend,plurals,..
220220
-k, --check bool false check generated wrapper with compiler
221+
--compile= strings {} create {.compile.} entries in generated wrapper
221222
-C=, --convention= string "cdecl" calling convention for wrapped procs
222223
-d, --debug bool false enable debug output
223224
-D=, --defines= strings {} definitions to pass to preprocessor
224-
-l=, --dynlib= string "" {.dynlib.} pragma to import symbols - Nim const string or file path
225+
-l=, --dynlib= string "" {.dynlib.} pragma to import symbols - Nim const string or
226+
file path
225227
-X=, --exclude= strings {} files or directories to exclude from the wrapped output
226228
-f=, --feature= Features {} flags to enable experimental features
227229
-I=, --includeDirs= strings {} include directory to pass to preprocessor
@@ -230,6 +232,8 @@ Options:
230232
-c, --noComments bool false exclude top-level comments from output
231233
-H, --noHeader bool false skip {.header.} pragma in wrapper
232234
-o=, --output= string "" file to output content - default: stdout
235+
--passC= strings {} create {.passC.} entries in generated wrapper
236+
--passL= strings {} create {.passL.} entries in generated wrapper
233237
-a, --past bool false print AST output
234238
--pluginSourcePath= string "" nim file to build and load as a plugin
235239
-n, --pnim bool false print Nim output

‎nimterop/cimport.nim

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -368,6 +368,8 @@ macro cDefine*(name: static[string], val: static[string] = ""): untyped =
368368
## `#define` an identifer that is forwarded to the C/C++ preprocessor if
369369
## called within `cImport()` or `c2nImport()` as well as to the C/C++
370370
## compiler during Nim compilation using `{.passC: "-DXXX".}`
371+
##
372+
## This needs to be called before `cImport()` to take effect.
371373
var str = name
372374
if val.nBl:
373375
str &= &"={val.quoteShell}"
@@ -379,6 +381,8 @@ macro cDefine*(values: static seq[string]): untyped =
379381
## `#define` multiple identifers that are forwarded to the C/C++ preprocessor
380382
## if called within `cImport()` or `c2nImport()` as well as to the C/C++
381383
## compiler during Nim compilation using `{.passC: "-DXXX".}`
384+
##
385+
## This needs to be called before `cImport()` to take effect.
382386
for value in values:
383387
let
384388
spl = value.split("=", maxsplit = 1)
@@ -390,11 +394,15 @@ macro cDefine*(values: static seq[string]): untyped =
390394
macro cPassC*(value: static string): untyped =
391395
## Create a `{.passC.}` entry that gets forwarded to the C/C++ compiler
392396
## during Nim compilation.
397+
##
398+
## This needs to be called before `cImport()` to take effect.
393399
gStateCT.passC.add value
394400
395401
macro cPassL*(value: static string): untyped =
396402
## Create a `{.passL.}` entry that gets forwarded to the C/C++ compiler
397403
## during Nim compilation.
404+
##
405+
## This needs to be called before `cImport()` to take effect.
398406
gStateCT.passL.add value
399407
400408
proc cAddSearchDir*(dir: string) {.compileTime.} =
@@ -416,6 +424,8 @@ macro cIncludeDir*(dirs: static seq[string], exclude: static[bool] = false): unt
416424
##
417425
## Set `exclude = true` if the contents of these include directories should
418426
## not be included in the wrapped output.
427+
##
428+
## This needs to be called before `cImport()` to take effect.
419429
for dir in dirs:
420430
let fullpath = findPath(dir)
421431
if fullpath notin gStateCT.includeDirs:
@@ -430,6 +440,8 @@ macro cIncludeDir*(dir: static[string], exclude: static[bool] = false): untyped
430440
##
431441
## Set `exclude = true` if the contents of this include directory should
432442
## not be included in the wrapped output.
443+
##
444+
## This needs to be called before `cImport()` to take effect.
433445
return quote do:
434446
cIncludeDir(@[`dir`], `exclude` == 1)
435447

0 commit comments

Comments
 (0)