Pragma Directives

CKSP allows you to control key compiler settings directly in your source code using #pragma directives. These settings apply project-wide (i.e., across all imported files).

Precedence

Command-line options always override any #pragma directives.

`#pragma output_path`

Specify the location of the compiled output:

#pragma output_path("path/to/file.txt")

output_path file extension

Note that the file extension must be *.txt.

0.0.8 You can use #pragma output_path multiple times in your project, to add output paths. This way you can generate multiple output files from a single compilation.

Migration from SublimeKSP

To facilitate the transition from SublimeKSP and use this #pragma directive with both compilers, I have added a temporary workaround: simply prefix the directive with a single-line comment (with no whitespace between the slashes and #pragma). For example, by writing //#pragma output_path(...) cksp will recognize and process the directive, while SublimeKSP will ignore it. This approach is especially helpful for projects migrating between compilers or maintaining compatibility with both.

1 2	`{#pragma save_compiled_source Samples/resources/scripts/my_script.txt} //#pragma output_path("Samples/Resources/scripts/my_script.txt")`

In this example, the first line uses SublimeKSP syntax and is ignored by cksp, while the second line is recognized by cksp but ignored by SublimeKSP.

`#pragma optimize`

0.0.7

Override the global optimization level for the project. This is useful for debugging, performance tuning or reducing compile times. The optimization level can be set by using one of the following arguments to the #pragma optimize directive:

#pragma optimize("none")

No optimizations are applied.

#pragma optimize("simple")

Simple optimizations are applied, including constant folding and dead-code elimination.

#pragma optimize("standard")

This is the default optimization level, which includes optimizations like constant folding, constant propagation, constant expression propagation, variable pruning and dead-code elimination.

#pragma optimize("aggressive")

This is the most aggressive optimization level, which includes all optimizations from the standard level and applying more iterations of the optimization passes. This increases compile times.

`#pragma pass_by`

0.0.7

Lets you define the default parameter passing behavior for function arguments in CKSP.

By default, CKSP passes function parameters by value, meaning that the function works with a copy of the passed variable and changes do not affect the original variable outside the function.

Using #pragma pass_by, you can switch the default behavior to pass by reference, where the function operates directly on the original variable, allowing modifications to be reflected outside the function.

#pragma pass_by("value")

or

#pragma pass_by("reference")

The available options are:

"value" (default) Function parameters are passed as independent copies.
"reference" Function parameters reference the original variables. Any changes in the function will affect the original variables.

Migration from SublimeKSP

This directive was introduced to provide more control over parameter passing which might be important when migrating code from SublimeKSP to CKSP. In SublimeKSP, all function arguments are implicitly passed by reference. When using the directive:

#pragma pass_by("reference")

at the top of your project will preserve the same semantics without having to manually adjust each function definition.

Overriding per Parameter

Regardless of the global #pragma pass_by setting, you can still explicitly specify passing parameters by reference for individual function parameters in their type annotations using ref.

`#pragma combine_callbacks`

0.0.8

Enables or disables the combination of duplicate callbacks into a single callback in the order they were defined and imported. This available option is a boolean value.

#pragma combine_callbacks(true)

By default, this feature is disabled and the compiler will raise an error if duplicate callbacks are detected and a warning if duplicate on ui_control callbacks with the same variable are found.

Using Command-Line Arguments Instead

When running cksp from the command line, you can specify the described #pragma directives as command-line arguments. This allows you to set the output path and optimization level without modifying the source code. Any command-line option always takes precedence over the corresponding #pragma directive found in the source files. For instance, if both a #pragma optimize("aggressive") directive and the -O1 flag are provided, the compiler will apply the command-line optimization level (simple) and ignore the pragma.

The following options correspond to the available #pragma directives:

Flag	Effect
`-O0`, `--optimize none`	Disables all optimizations.
`-O1`, `--optimize simple`	Enables a minimal set of optimizations, such as constant folding and dead code elimination.
`-O2`, `--optimize standard`	Enables the standard optimization pipeline (default).
`-O3`, `--optimize aggressive`	Applies the most aggressive optimization passes, potentially increasing compile times.
`-P <mode>`, `--pass-by <mode>`	Defines the default parameter passing mode. Valid values are `value` and `reference`.
`-c`, `--combine-callbacks`	Enables automatic combination of duplicate callbacks into a single callback.
`--no-combine-callbacks`	Explicitly disables callback combination, even if a pragma enables it.
`-o <file>`, `--output <file>`	Specifies an output file. This option may be repeated multiple times to generate several output files in a single compilation.

Multiple or No Output Paths

An -o/--output flag always takes precedence over any #pragma output_path. If neither CLI nor pragma is used, cksp defaults to standard optimization and <input_dir>/out.txt as output.

If multiple -o flags are provided, the compiler will generate one output for each path in the order they are listed. The first specified output is considered the primary output file and is used by legacy systems or tools expecting a single output.