05-06-2024, 07:03 AM
It's very much a non-answer, but I'd say if you don't already know what the settings do then you probably shouldn't be touching them 
They're not intended for typical users, rather for someone who already knows what they're trying to do and just needs a somewhat easy way to set their settings.
That said, some general descriptions:
> Compile program with C++ optimization flag
This applies the C++ `-O2` optimization level to your compile code (and QB64 runtime). This will result in faster code (a lot faster), but significantly slower compilation times and much higher memory usage during compilation. There's also some remaining questions around stability, though I'd say at this point we run all our testing with `-O2` and don't notice any issues.
Ideally at some point this flag becomes unnecessary because we will apply `-O2` by default, but we don't do it currently due to the slow down and memory usage I noted. We have been refactoring the runtime though and the refactored parts get -O2 applied even without setting this flag.
> Strip C++ symbols from executable
This reduces executable size at the cost of debugging ability. This is not related to `$Debug` functionality, but debugging your program using a debugger like `gdb`, if you strip the symbols then the debugger can't show you function or variable names.
Note that on Windows and Linux, if you set this setting then the removed symbols (and debug information, if checked) are stored in a separate `.sym` file in `./internal/temp`. It's possible to load this file into a debugger like `gdb` to gain back symbols and debug information even if they were stripped from the executable.
> Add C++ Debug Information
Also related to using a debugger like `gdb`, this adds 'extra' information beyond just the symbol names to your executable. This increases the executable size, but the debugger will be able to show you even more information about the running your code (Ex. step through the C++ source, display local variables, etc.).
> C++ Compiler Flags
> C++ Linker Flags
These allow you to directly add extra flags during compilation of the generated C++ for your program. This requires a lot of knowledge to use because not all flags are valid for our code, and also any settings here are completely untested. You could however use this to apply extra optimization flags if you think they're relevant, or maybe specify extra include file paths (though I'm not sure how that works out with `Declare Library`, but regardless), or set some global `#define` flags. There's also some executable settings like stack size that you can control.
If you're setting anything in these boxes then you're on completely your own, there's no guarantee that whatever you're doing will continue to work in the future.
> Max C++ Compiler Processes
This one is probably the most relevant. The compilation of the C++ code for your program (mostly the runtime) is done in parallel by spawning multiple C++ compilers at a time. This setting controls how many of those compilers are allowed to run at one time. There are limits to how far you can take this because your actual compiled QB64 code is all in one `.cpp` file and thus cannot be compiled in parallel, but generally speaking a higher number here means faster compilation but also higher CPU and memory usage during compilation. The default of 3 is somewhat conservative, but generally speaking after the first compilation (where many of the separate runtime `.cpp` files will get compiled) numbers higher than 3 really won't do anything anyway.
They're not intended for typical users, rather for someone who already knows what they're trying to do and just needs a somewhat easy way to set their settings.That said, some general descriptions:
> Compile program with C++ optimization flag
This applies the C++ `-O2` optimization level to your compile code (and QB64 runtime). This will result in faster code (a lot faster), but significantly slower compilation times and much higher memory usage during compilation. There's also some remaining questions around stability, though I'd say at this point we run all our testing with `-O2` and don't notice any issues.
Ideally at some point this flag becomes unnecessary because we will apply `-O2` by default, but we don't do it currently due to the slow down and memory usage I noted. We have been refactoring the runtime though and the refactored parts get -O2 applied even without setting this flag.
> Strip C++ symbols from executable
This reduces executable size at the cost of debugging ability. This is not related to `$Debug` functionality, but debugging your program using a debugger like `gdb`, if you strip the symbols then the debugger can't show you function or variable names.
Note that on Windows and Linux, if you set this setting then the removed symbols (and debug information, if checked) are stored in a separate `.sym` file in `./internal/temp`. It's possible to load this file into a debugger like `gdb` to gain back symbols and debug information even if they were stripped from the executable.
> Add C++ Debug Information
Also related to using a debugger like `gdb`, this adds 'extra' information beyond just the symbol names to your executable. This increases the executable size, but the debugger will be able to show you even more information about the running your code (Ex. step through the C++ source, display local variables, etc.).
> C++ Compiler Flags
> C++ Linker Flags
These allow you to directly add extra flags during compilation of the generated C++ for your program. This requires a lot of knowledge to use because not all flags are valid for our code, and also any settings here are completely untested. You could however use this to apply extra optimization flags if you think they're relevant, or maybe specify extra include file paths (though I'm not sure how that works out with `Declare Library`, but regardless), or set some global `#define` flags. There's also some executable settings like stack size that you can control.
If you're setting anything in these boxes then you're on completely your own, there's no guarantee that whatever you're doing will continue to work in the future.
> Max C++ Compiler Processes
This one is probably the most relevant. The compilation of the C++ code for your program (mostly the runtime) is done in parallel by spawning multiple C++ compilers at a time. This setting controls how many of those compilers are allowed to run at one time. There are limits to how far you can take this because your actual compiled QB64 code is all in one `.cpp` file and thus cannot be compiled in parallel, but generally speaking a higher number here means faster compilation but also higher CPU and memory usage during compilation. The default of 3 is somewhat conservative, but generally speaking after the first compilation (where many of the separate runtime `.cpp` files will get compiled) numbers higher than 3 really won't do anything anyway.