Skip to content

Commit 6f5db63

Browse files
danil-pavlovdanil-pavlov
authored
feat: binary options (#4974)
1 parent 4f0d376 commit 6f5db63

File tree

3 files changed

+340
-32
lines changed

3 files changed

+340
-32
lines changed

‎docs/kr.tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,7 @@
202202
<toc-element toc-title="Integration with ARC" accepts-web-file-names="native-ios-integration.html" topic="native-arc-integration.md"/>
203203
<toc-element toc-title="Migration guide" topic="native-migration-guide.md"/>
204204
</toc-element>
205+
<toc-element toc-title="Binary options" topic="native-binary-options.md"/>
205206
<toc-element topic="native-debugging.md"/>
206207
<toc-element toc-title="Reference and tips">
207208
<toc-element toc-title="Target support" topic="native-target-support.md"/>

‎docs/topics/native/native-binary-options.md

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
[//]: # (title: Kotlin/Native binary options)
2+
3+
This page lists helpful Kotlin/Native binary options that you can use to configure Kotlin/Native [final binaries](https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-build-native-binaries.html)
4+
and the ways to set up binary options in your project.
5+
6+
## How to enable
7+
8+
You can enable binary options in the `gradle.properties` file, your build file, or pass them as compiler arguments.
9+
10+
### In Gradle properties
11+
12+
You can set binary options in your project's `gradle.properties` file using the `kotlin.native.binary` property. For example:
13+
14+
```none
15+
kotlin.native.binary.gc=cms
16+
kotlin.native.binary.latin1Strings=true
17+
```
18+
19+
### In your build file
20+
21+
You can set binary options for your project in your `build.gradle.kts` file:
22+
23+
* For specific binaries using the `binaryOption` attribute. For example:
24+
25+
```kotlin
26+
kotlin {
27+
iosArm64 {
28+
binaries {
29+
framework {
30+
binaryOption("smallBinary", "true")
31+
}
32+
}
33+
}
34+
}
35+
```
36+
37+
* As `-Xbinary=$option=$value` compiler options in the `freeCompilerArgs` attribute. For example:
38+
39+
```kotlin
40+
kotlin {
41+
iosArm64 {
42+
compilations.configureEach {
43+
compilerOptions.configure {
44+
freeCompilerArgs.add("-Xbinary=smallBinary=true")
45+
}
46+
}
47+
}
48+
}
49+
```
50+
51+
### In the command-line compiler
52+
53+
You can pass binary options as `-Xbinary=$option=$value` directly in the command line when executing
54+
the [Kotlin/Native compiler](native-get-started.md#using-the-command-line-compiler).
55+
For example:
56+
57+
```bash
58+
kotlinc-native main.kt -Xbinary=enableSafepointSignposts=true
59+
```
60+
61+
## Binary options
62+
63+
> This table is not an exhaustive list of all the existing options, only the most notable ones.
64+
>
65+
{style="note"}
66+
67+
<table column-width="fixed">
68+
<tr>
69+
<td width="240">Option</td>
70+
<td width="170">Values</td>
71+
<td>Description</td>
72+
<td width="110">Status</td>
73+
</tr>
74+
<tr>
75+
<td><a href="whatsnew-eap.md#smaller-binary-size-for-release-binaries"><code>smallBinary</code></a></td>
76+
<td>
77+
<list>
78+
<li><code>true</code></li>
79+
<li><code>false</code> (default)</li>
80+
</list>
81+
</td>
82+
<td>Decreases the binary size for release binaries.</td>
83+
<td>Experimental since 2.2.20</td>
84+
</tr>
85+
<tr>
86+
<td><a href="whatsnew-eap.md#support-for-stack-canaries-in-binaries"><code>stackProtector</code></a></td>
87+
<td>
88+
<list>
89+
<li><code>yes</code></li>
90+
<li><code>strong</code></li>
91+
<li><code>all</code></li>
92+
<li><code>no</code> (default)</li>
93+
</list>
94+
</td>
95+
<td>Enables stack canaries: use <code>yes</code> for vulnerable functions, <code>all</code> for all functions, and <code>strong</code> to use a stronger heuristic.</td>
96+
<td>Available since 2.2.20</td>
97+
</tr>
98+
<tr>
99+
<td><a href="native-memory-manager.md#disable-allocator-paging"><code>pagedAllocator</code></a></td>
100+
<td>
101+
<list>
102+
<li><code>true</code> (default)</li>
103+
<li><code>false</code></li>
104+
</list>
105+
</td>
106+
<td>Controls paging of allocations (buffering). When <code>false</code>, the memory allocator reserves memory on a per-object basis.</td>
107+
<td>Experimental since 2.2.0</td>
108+
</tr>
109+
<tr>
110+
<td><a href="native-memory-manager.md#enable-support-for-latin-1-strings"><code>latin1Strings</code></a></td>
111+
<td>
112+
<list>
113+
<li><code>true</code></li>
114+
<li><code>false</code> (default)</li>
115+
</list>
116+
</td>
117+
<td>Controls support for Latin-1-encoded strings to reduce application binary size and adjust memory consumption.</td>
118+
<td>Experimental since 2.2.0</td>
119+
</tr>
120+
<tr>
121+
<td><a href="native-memory-manager.md#track-memory-consumption-on-apple-platforms"><code>mmapTag</code></a></td>
122+
<td><code>UInt</code></td>
123+
<td>Controls memory tagging, necessary for memory consumption tracking on Apple platforms. Values <code>240</code>-<code>255</code> are available (default is <code>246</code>); <code>0</code> disables tagging.</td>
124+
<td>Available since 2.2.0</td>
125+
</tr>
126+
<tr>
127+
<td><code>disableMmap</code></td>
128+
<td>
129+
<list>
130+
<li><code>true</code></li>
131+
<li><code>false</code> (default)</li>
132+
</list>
133+
</td>
134+
<td>Controls the default allocator. When <code>true</code>, uses the <code>malloc</code> memory allocator instead of <code>mmap</code>.</td>
135+
<td>Available since 2.2.0</td>
136+
</tr>
137+
<tr>
138+
<td><code>gc</code></td>
139+
<td>
140+
<list>
141+
<li><code>pmcs</code> (default)</li>
142+
<li><code>stwms</code></li>
143+
<li><a href="native-memory-manager.md#optimize-gc-performance"><code>cms</code></a></li>
144+
<li><a href="native-memory-manager.md#disable-garbage-collection"><code>noop</code></a></li>
145+
</list>
146+
</td>
147+
<td>Controls garbage collection behavior:
148+
<list>
149+
<li><code>pmcs</code> uses parallel mark concurrent sweep</li>
150+
<li><code>stwms</code> uses simple stop-the-world mark and sweep</li>
151+
<li><code>cms</code> enables concurrent marking that helps decrease GC pause time</li>
152+
<li><code>noop</code> disables garbage collection</li>
153+
</list>
154+
</td>
155+
<td><code>cms</code> is Experimental since 2.0.20</td>
156+
</tr>
157+
<tr>
158+
<td><a href="native-memory-manager.md#garbage-collector"><code>gcMarkSingleThreaded</code></a></td>
159+
<td>
160+
<list>
161+
<li><code>true</code></li>
162+
<li><code>false</code> (default)</li>
163+
</list>
164+
</td>
165+
<td>Disables parallelization of the mark phase in garbage collection. May increase GC pause time on large heaps.</td>
166+
<td>Available since 1.7.20</td>
167+
</tr>
168+
<tr>
169+
<td><a href="native-memory-manager.md#monitor-gc-performance"><code>enableSafepointSignposts</code></a></td>
170+
<td>
171+
<list>
172+
<li><code>true</code></li>
173+
<li><code>false</code> (default)</li>
174+
</list>
175+
</td>
176+
<td>Enables tracking GC-related pauses in the project for debugging in Xcode Instruments.</td>
177+
<td>Available since 2.0.20</td>
178+
</tr>
179+
<tr>
180+
<td><code>preCodegenInlineThreshold</code></td>
181+
<td><code>UInt</code></td>
182+
<td>
183+
<p>Configures inlining optimization pass in the Kotlin IR compiler, which comes before the actual code generation phase (disabled by default).</p>
184+
<p>The recommended number of tokens (code units parsed by the compiler) is 40.</p>
185+
</td>
186+
<td>Experimental since 2.1.20</td>
187+
</tr>
188+
<tr>
189+
<td><a href="native-arc-integration.md#deinitializers"><code>objcDisposeOnMain</code></a></td>
190+
<td>
191+
<list>
192+
<li><code>true</code> (default)</li>
193+
<li><code>false</code></li>
194+
</list>
195+
</td>
196+
<td>Controls deinitialization of Swift/Objective-C objects. When <code>false</code>, deinitialization happens on a special GC thread instead of the main one.</td>
197+
<td>Available since 1.9.0</td>
198+
</tr>
199+
<tr>
200+
<td><a href="native-arc-integration.md#support-for-background-state-and-app-extensions"><code>appStateTracking</code></a></td>
201+
<td>
202+
<list>
203+
<li><code>enabled</code></li>
204+
<li><code>disabled</code> (default)</li>
205+
</list>
206+
</td>
207+
<td>
208+
<p>Controls timer-based invocation of the garbage collector when the application runs in the background.</p>
209+
<p>When <code>enabled</code>, GC is called only when memory consumption becomes too high.</p>
210+
</td>
211+
<td>Experimental since 1.7.20</td>
212+
</tr>
213+
<tr>
214+
<td><code>bundleId</code></td>
215+
<td>
216+
<list>
217+
<li><code>String</code></li>
218+
</list>
219+
</td>
220+
<td>Sets bundle ID (<code>CFBundleIdentifier</code>) in the <code>Info.plst</code> file.</td>
221+
<td>Available since 1.7.20</td>
222+
</tr>
223+
<tr>
224+
<td><code>bundleShortVersionString</code></td>
225+
<td>
226+
<list>
227+
<li><code>String</code></li>
228+
</list>
229+
</td>
230+
<td>Sets short bundle version (<code>CFBundleShortVersionString</code>) in the <code>Info.plst</code> file.</td>
231+
<td>Available since 1.7.20</td>
232+
</tr>
233+
<tr>
234+
<td><code>bundleVersion</code></td>
235+
<td>
236+
<list>
237+
<li><code>String</code></li>
238+
</list>
239+
</td>
240+
<td>Sets bundle version (<code>CFBundleVersion</code>) in the <code>Info.plst</code> file.</td>
241+
<td>Available since 1.7.20</td>
242+
</tr>
243+
<tr>
244+
<td><code>sourceInfoType</code></td>
245+
<td>
246+
<list>
247+
<li><code>libbacktrace</code></li>
248+
<li><code>coresymbolication</code> (Apple targets)</li>
249+
<li><code>noop</code> (default)</li>
250+
</list>
251+
</td>
252+
<td>
253+
<p>Adds file locations and line numbers to exception stack traces.</p>
254+
<p><code>coresymbolication</code> is only available for Apple targets and enabled by default for macOS and Apple simulators in debug mode.</p>
255+
</td>
256+
<td>Experimental since 1.6.20</td>
257+
</tr>
258+
<!-- <tr>
259+
<td><code>objcExportReportNameCollisions</code></td>
260+
<td>
261+
<list>
262+
<li><code>true</code></li>
263+
<li><code>false</code> (default)</li>
264+
</list>
265+
</td>
266+
<td>When <code>enabled</code>, reports warnings in case name collisions occur during Objective-C export.</td>
267+
<td></td>
268+
</tr>
269+
<tr>
270+
<td><code>objcExportErrorOnNameCollisions</code></td>
271+
<td>
272+
<list>
273+
<li><code>true</code></li>
274+
<li><code>false</code> (default)</li>
275+
</list>
276+
</td>
277+
<td>When <code>true</code>, issues errors in case name collisions occur during Objective-C export.</td>
278+
<td></td>
279+
</tr>
280+
<tr>
281+
<td><code>debugCompilationDir</code></td>
282+
<td><code>String</code></td>
283+
<td>Specifies the directory path to use for debug information in the compiled binary.</td>
284+
<td></td>
285+
</tr>
286+
<tr>
287+
<td><code>fixedBlockPageSize</code></td>
288+
<td><code>UInt</code></td>
289+
<td>Controls the page size for fixed memory blocks in the memory allocator. Affects memory allocation performance and fragmentation.</td>
290+
<td></td>
291+
</tr>
292+
<tr>
293+
<td><code>gcMutatorsCooperate</code></td>
294+
<td>
295+
<list>
296+
<li><code>true</code></li>
297+
<li><code>false</code> (default)</li>
298+
</list>
299+
</td>
300+
<td>Controls cooperation between mutator threads and the garbage collector.</td>
301+
<td></td>
302+
</tr>
303+
<tr>
304+
<td><code>auxGCThreads</code></td>
305+
<td><code>UInt</code></td>
306+
<td>Specifies the number of auxiliary threads to use for garbage collection.</td>
307+
<td></td>
308+
</tr>
309+
<tr>
310+
<td><code>sanitizer</code></td>
311+
<td>
312+
<list>
313+
<li><code>address</code></li>
314+
<li><code>thread</code></li>
315+
</list>
316+
</td>
317+
<td>Enables runtime sanitizers for detecting various issues like memory errors, data races, and undefined behavior.</td>
318+
<td>Experimental</td>
319+
</tr> -->
320+
</table>
321+
322+
> For more information on stability levels, see the [documentation](components-stability.md#stability-levels-explained).
323+
>
324+
{style="tip"}
325+
326+
## What's next
327+
328+
Learn how to [build final native binaries](https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-build-native-binaries.html).

0 commit comments

Comments
 (0)