From 61609454d602d4a7b5c312e59b06909c9b3519a2 Mon Sep 17 00:00:00 2001 From: Carlos Esquerdo Bernat Date: Fri, 6 Sep 2024 19:02:58 +0200 Subject: [PATCH] docs: add a section for the `-compress` flag (#22169) --- doc/docs.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/doc/docs.md b/doc/docs.md index adca0264c1372b..20b8f7fd4d52f2 100644 --- a/doc/docs.md +++ b/doc/docs.md @@ -6725,15 +6725,16 @@ performance, memory usage, or size. | Tuning Operation | Benefits | Drawbacks | |--------------------------|---------------------------------|---------------------------------------------------| -| `@[inline]` | Performance | Increased executable size | -| `@[direct_array_access]` | Performance | Safety risks | -| `@[packed]` | Memory usage | Potential performance loss | -| `@[minify]` | Performance, Memory usage | May break binary serialization/reflection | +| `@[inline]` | Performance | Increased executable size | +| `@[direct_array_access]` | Performance | Safety risks | +| `@[packed]` | Memory usage | Potential performance loss | +| `@[minify]` | Performance, Memory usage | May break binary serialization/reflection | | `_likely_/_unlikely_` | Performance | Risk of negative performance impact | | `-skip-unused` | Performance, Compile time, Size | Potential instability | | `-fast-math` | Performance | Risk of incorrect mathematical operations results | | `-d no_segfault_handler` | Compile time, Size | Loss of segfault trace | | `-cflags -march=native` | Performance | Risk of reduced CPU compatibility | +| `-compress` | Size | Harder to debug, extra dependency `upx` | | `PGO` | Performance, Size | Usage complexity | ### Tuning operations details @@ -6920,6 +6921,22 @@ with identical hardware. - When distributing the software to users with potentially older CPUs. +#### `-compress` + +This flag executes `upx` to compress the resultant executable, +reducing its size by around 50%-70%. + +**When to Use** + +- For really tiny environments, where the size of the executable on the file system, +or when deploying is important. The executable will be uncompressed at runtime, +so it will take a bit more time to start. + +**When to Avoid** + +- When you need to debug the application, or when your app's startup time +is extremely important (where 1-2ms can be meaningful for you). + #### PGO (Profile-Guided Optimization) PGO allows the compiler to optimize code based on its behavior during sample runs. This can improve