You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This command will produce a `png.klib` compiled library and
78
-
`png-build/kotlin` directory containing Kotlin source code for the library.
79
-
80
-
If the behavior for a certain platform needs to be modified, you can use a format like
81
-
`compilerOpts.osx` or `compilerOpts.linux` to provide platform-specific values
82
-
to the options.
83
-
84
-
Note that the generated bindings are generally platform-specific, so if you are developing for
85
-
multiple targets, the bindings need to be regenerated.
86
-
87
-
After the generation of bindings, they can be used by the IDE as a proxy view of the
88
-
native library.
89
-
90
-
For a typical Unix library with a config script, the `compilerOpts` will likely contain
91
-
the output of a config script with the `--cflags` flag (maybe without exact paths).
92
-
93
-
The output of a config script with `--libs` will be passed as a `-linkedArgs``kotlinc`
94
-
flag value (quoted) when compiling.
95
-
96
-
### Select library headers
97
-
98
-
When library headers are imported to a C program with the `#include` directive,
99
-
all of the headers included by these headers are also included in the program.
100
-
So all header dependencies are included in generated stubs as well.
101
-
102
-
This behavior is correct but it can be very inconvenient for some libraries. So
103
-
it is possible to specify in the `.def` file which of the included headers are to
104
-
be imported. The separate declarations from other headers can also be imported
105
-
in case of direct dependencies.
106
-
107
-
#### Filter headers by globs
108
-
109
-
It is possible to filter headers by globs using filter properties from the `.def` file.
110
-
They are treated as a space-separated list of globs.
111
-
112
-
* To include declarations from headers, use the `headerFilter` property. If the included header matches any of the globs,
113
-
the declarations are included in the bindings.
114
-
115
-
The globs are applied to the header paths relative to the appropriate include path elements,
116
-
for example, `time.h` or `curl/curl.h`. So if the library is usually included with `#include <SomeLibrary/Header.h>`,
117
-
it would probably be correct to filter headers with the following filter:
118
-
119
-
```none
120
-
headerFilter = SomeLibrary/**
121
-
```
122
-
123
-
If `headerFilter` is not provided, all the headers are included. However, we encourage you to use `headerFilter`
124
-
and specify the glob as precisely as possible. In this case, the generated library contains only the necessary
125
-
declarations. It can help avoid various issues when upgrading Kotlin or tools in your development environment.
126
-
127
-
* To exclude specific headers, use the `excludeFilter` property.
128
-
129
-
It can be helpful to remove redundant or problematic headers and optimize compilation,
130
-
as declarations from the specified headers are not included into the bindings.
131
-
132
-
```none
133
-
excludeFilter = SomeLibrary/time.h
134
-
```
135
-
136
-
> If the same header is both included with `headerFilter`, and excluded with `excludeFilter`, the latter will have a higher
137
-
> priority. The specified header will not be included into the bindings.
138
-
>
139
-
{style="note"}
140
-
141
-
#### Filter headers by module maps
142
-
143
-
Some libraries have proper `module.modulemap` or `module.map` files in their
144
-
headers. For example, macOS and iOS system libraries and frameworks do.
145
-
The [module map file](https://clang.llvm.org/docs/Modules.html#module-map-language)
146
-
describes the correspondence between header files and modules. When the module
147
-
maps are available, the headers from the modules that are not included directly
148
-
can be filtered out using the experimental `excludeDependentModules` option of the
149
-
`.def` file:
150
-
151
-
```c
152
-
headers = OpenGL/gl.h OpenGL/glu.h GLUT/glut.h
153
-
compilerOpts = -framework OpenGL -framework GLUT
154
-
excludeDependentModules = true
155
-
```
156
-
157
-
When both `excludeDependentModules` and `headerFilter` are used, they are
158
-
applied as an intersection.
159
-
160
-
### C compiler and linker options
161
-
162
-
Options passed to the C compiler (used to analyze headers, such as preprocessor definitions) and the linker
163
-
(used to link final executables) can be passed in the definition file as `compilerOpts` and `linkerOpts`
164
-
respectively. For example:
165
-
166
-
```c
167
-
compilerOpts = -DFOO=bar
168
-
linkerOpts = -lpng
169
-
```
170
-
171
-
Target-specific options only applicable to the certain target can be specified as well:
172
-
173
-
```c
174
-
compilerOpts = -DBAR=bar
175
-
compilerOpts.linux_x64 = -DFOO=foo1
176
-
compilerOpts.macos_x64 = -DFOO=foo2
177
-
```
178
-
179
-
With such a configuration, C headers will be analyzed with `-DBAR=bar -DFOO=foo1` on Linux and
180
-
with `-DBAR=bar -DFOO=foo2` on macOS .
181
-
Note that any definition file option can have both common and the platform-specific part.
182
-
183
-
#### Linker errors
184
-
185
-
Linker errors might occur when a Kotlin library depends on C or Objective-C libraries, for example, using the [CocoaPods integration](native-cocoapods.md).
186
-
If dependent libraries aren't installed locally on the machine or configured explicitly in the project build script,
187
-
the "Framework not found" error occurs.
188
-
189
-
If you're a library author, you can help your users resolve linker errors with custom messages.
190
-
To do that, add a `userSetupHint=message` property to your `.def` file or pass the `-Xuser-setup-hint` compiler option to `cinterop`.
191
-
192
-
### Add custom declarations
193
-
194
-
Sometimes it is required to add custom C declarations to the library before
195
-
generating bindings (e.g., for [macros](#macros)). Instead of creating an
196
-
additional header file with these declarations, you can include them directly
197
-
to the end of the `.def` file, after a separating line, containing only the
198
-
separator sequence `---`:
199
-
200
-
```c
201
-
headers = errno.h
202
-
203
-
---
204
-
205
-
staticinlineintgetErrno() {
206
-
return errno;
207
-
}
208
-
```
209
-
210
-
Note that this part of the `.def` file is treated as part of the header file, so
211
-
functions with the body should be declared as `static`.
212
-
The declarations are parsed after including the files from the `headers` list.
213
-
214
-
### Include a static library in your klib
215
-
216
-
Sometimes it is more convenient to ship a static library with your product,
217
-
rather than assume it is available within the user's environment.
218
-
To include a static library into `.klib` use `staticLibrary` and `libraryPaths`
0 commit comments