Configurations allow you to specify which source code files to include in a program, the name of the generated program file, optimization behavior, and other options.
Configurations are written as part of the source code of the program, without requiring a separate configuration, "project", or "make" file. It is possible for the configuration and entire source code of a program to be all within a single source code file. The source code may also contain multiple configurations (either variations of the same program or for different programs).
A configuration definition begins with the "Configuration" command and ends with the "EndConfiguration" command. The "Configuration" command has a parameter, the name of the configuration. After the "Configuration" command, multiple "Info" commands should appear to supply configuration information/details. For example:
Configuration Cfg1;
Info Name, "SurfWriter";
Info ProgramType, Application;
Info InitCommand, MyProgram.Initialize;
Info UserInterfaceMode, IndirectGUI;
Info Optimize, On;
EndConfiguration;
The first parameter of the "Info" command specifies the type of configuration information being supplied, and the remainder of the parameters supply that information. Valid information types are described following.
If there are 2 "Info" commands specifying the same type in the same Configuration, then the compiler produces an error message, except if it is a type that allows multiple.
2 or 4 parameters. If 2 parameters are supplied, the second parameter specifies the desired name of the program as literal text (must be enclosed in quotation marks). This program name may be displayed to the user when the program is running, or when the user queries the program file for more information.
If 4 parameters are supplied, the second parameter is a short/abbreviated version of the program name, the third parameter is the normal name, and the fourth parameter is a long/full/extended version of the program name. The short name may be displayed to the user in preference to the normal or long name when space is constrained. The long name may be displayed when the available space is more than wide enough to accommodate it. Examples:
Info Name, "SurfWriter"; Info Name, "SrfWrt", "SurfWriter", "Haxial SurfWriter Pro";
This command is mandatory. If it is omitted, the compiler produces an error message.
Line break characters in the text are illegal. The name(s) should not include version numbers.
2 parameters. The second parameter is the desired name of the compiled program file that the compiler will produce/create when the source code compiles successfully. The name is supplied as literal text (must be enclosed in quotation marks). The compiler may automatically append a file name extension to this name (such as ".kex" or ".exe"). Example:
Info FileName, "SurfWriter-Pro";
If the "Info FileName" command is omitted, then the file name defaults to using the normal name from the "Info Name" command.
Be aware that if a file already exists with the same name as an output file being generated, the compiler will overwrite it (it presumes you wanted it regenerated).
2 parameters. The second parameter is a short description of the program, as literal/quoted text. This description may be displayed to the user when the user queries the program file for more information. Short meaning 1 or 2 sentences. Example:
Info ShortDescription, "A gnarly word processor application.";
If the "Info ShortDescription" command is omitted, then the short description defaults to being empty.
2 parameters. The second parameter is a longer description of the program, as literal/quoted text. This description may be displayed to the user when the user queries the program file for more information. This description may be approximately 1 to 4 paragraphs in length.
2 parameters. The second parameter is some comment(s) about the program, as literal/quoted text. The comment text can be anything. The comment text may be displayed to the user when the user queries the program file for more information. Example:
Info Comment, "Please send suggestions for improvements "
"to surfwriter at haxial dot com.";
This command specifies the numeric version number of the program. It has 3 to 6 parameters in any of the following forms:
Info Version, major, minor; Info Version, major, minor, type; Info Version, major, minor, type, prerelease; Info Version, major, minor, micro; Info Version, major, minor, micro, type; Info Version, major, minor, micro, type, prerelease;
Where major, minor, micro, and prerelease are positive integers in the range 0 to 65535 (TUInt16), and type is one of the following identifiers.
Normal Demonstration Test Alpha Beta ReleaseCandidate
If the micro parameter is omitted, it defaults to zero. If the type parameter is omitted, it defaults to "Normal". If the type parameter is "Normal", "Demonstration", or "Test", then the prerelease parameter must be omitted. If the type parameter is "Alpha", "Beta", or "ReleaseCandidate", then the prerelease parameter must be included. Here are some valid non-equivalent examples:
Info Version, 1, 0; Info Version, 1, 22; Info Version, 1, 23, Test; Info Version, 2, 0, Beta, 16; Info Version, 1, 10, 258; Info Version, 3, 5, 0, ReleaseCandidate, 1;
The version number may be displayed to the user. To do this, it must be converted to text. Following you can see how various version numbers are converted to text. Also, the following list is ordered from lowest to highest version.
| Parameters | As Text |
|---|---|
| 0, 1, 0 | 0:1 |
| 0, 7, 0 | 0:7 |
| 0, 34, 0 | 0:34 |
| 1, 0, 0 | 1:0 |
| 1, 0, 2 | 1:0:2 |
| 1, 0, 3 | 1:0:3 |
| 1, 0, 20 | 1:0:20 |
| 1, 1, 0 | 1:1 |
| 1, 2, 0 | 1:2 |
| 1, 5, 0 | 1:5 |
| 1, 10, 0 | 1:10 |
| 1, 50, 0 | 1:50 |
| 1, 267, 0 | 1:267 |
| 1, 267, 1 | 1:267:1 |
| 2, 0, 0, Alpha, 0 | 2:0a0 |
| 2, 0, 0, Alpha, 1 | 2:0a1 |
| 2, 0, 0, Alpha, 2 | 2:0a2 |
| 2, 0, 0, Beta, 1 | 2:0b1 |
| 2, 0, 0, Beta, 10 | 2:0b10 |
| 2, 0, 0, Beta, 20 | 2:0b20 |
| 2, 0, 0, Beta, 123 | 2:0b123 |
| 2, 0, 0, ReleaseCandidate, 1 | 2:0rc1 |
| 2, 0, 0, ReleaseCandidate, 2 | 2:0rc2 |
| 2, 0, 0 | 2:0 |
| 2, 0, 10, ReleaseCandidate, 1 | 2:0:10rc1 |
| 2, 1, 0 | 2:1 |
| 2, 1, 3 | 2:1:3 |
| 2, 50, 0, Beta, 1 | 2:50b1 |
| 3, 43, 0 | 3:43 |
| 3, 44, 0, Test | 3:44t |
| 3, 44, 0 | 3:44 |
| 3, 45, 0 | 3:45 |
| 3, 45, 0, Demonstration | 3:45dm |
| 14, 7, 1 | 14:7:1 |
If the major number is zero (frex "0:23"), it indicates that the product is in the initial stages of development and is unfinished/incomplete. If the major number has progressed beyond zero (frex "1:34") and the developer wishes to temporarily re-enter an unfinished/incomplete stage for a large upgrade to the program, then a prerelease/preview type of "Alpha" or "Beta" can be used (frex "2:0b1").
The type "ReleaseCandidate" means that this version is finished and contains no bugs/problems that the developer is aware of (or no problems that the developer intends to fix in this release), and that it will soon become the normal release version (with no further changes) if no bugs/problems are discovered.
For example, if no problems are discovered in "2:0rc1" after a reasonable amount of testing/time, then the version will be changed to "2:0" without making any other changes to the program. However if a problem IS discovered before "2:0rc1" is changed to "2:0", then a "2:0rc2" version will be released that fixes that problem.
As an alternative to using "Beta" etc, the type "Test" can be used. It indicates that a version has been released as a testing/experimental/unstable version that may contain bugs and may malfunction. It has been released for the purpose of testing it to find bugs/problems.
The type "Test" is a description applied to a version number, it does not indicate a different version. In other words, there should never be 2 different versions of a program that have the same major, minor, and micro number and differ only in one being type "Normal" and the other being type "Test". For example, there should never exist a "1:7" version of a program in addition to a different "1:7t" version. Rather "1:7t" means that version "1:7" is a testing version.
The type "Demonstration" can be used if the developer wishes to release a crippled/limited demonstration/trial version of an existing version of a program. For example there may exist a "2:5dm" version in addition to the normal "2:5" version, where "2:5dm" is a crippled version of "2:5". A demonstration version of a program allows an end-user to trial a program before paying for it, and then if they are satisfied with the demonstration, they can then pay to receive the normal uncrippled version.
If a version number is displayed (converted to text) with a decimal point (".") instead of colon (":"), then it should not violate the normal/common mathematical conventions/rules, because that would cause confusion, ambiguity, and possible mistakes. For example, a number containing 2 decimal points (such as 1.2.3) violates the normal mathematical conventions (a valid number can contain only 1 decimal point), and thus should not be used (use colon instead).
A version number can reasonably be displayed using a single decimal point, but it should not violate the normal mathematical rules regarding the significance/placement of zero digits. Remember that in mathematics and common everyday numbering, 2.9 is the same number as 2.90000 and 002.900 (leading and trailing zero digits are insignificant).
Thus note that version 2.1 means 2.10, and 2.9 means 2.90, and version 2.10 is LESS THAN 2.9 (2.90). If a developer releases a version "2.9" and then later releases a version "2.10", then the version number has actually progressed BACKWARDS, and this will tend to confuse end-users because it is INCORRECT according to the normal/common system of decimal numbering.
If using a decimal point in a version number, then to avoid confusion it is best to always write the fractional portion of the version number (after the ".") using a fixed/constant number of digits, for example always 2 digits with a trailing zero digit as padding where necessary (frex "1.20", "1.00" to "1.99"). This requires some planning ahead because it means the fractional portion is limited to a maximum of 99.
If 99 versions might be insufficient, then consider always using 3 digits (with 1 or 2 padding zero digits where necessary) for a maximum of 999 (frex "1.200", "1.000" to "1.999"). The number/count of fractional digits cannot be changed after it is first used, so plan ahead, or avoid the problem entirely by instead using 2 or 3 integers with colon (":") as a separator as described above.
2 parameters. If this command is supplied, the program is identified as being a special build (not the normal build released to the general public). The second parameter is a description of the special build, as literal/quoted text. This text may be displayed to the user when the user queries the program file for more information. Example:
Info SpecialBuild, "Private build for TESTER6 to test "
"keyboard problems.";
2 parameters. If this command is supplied, the program is identified as a patched version, meaning it has been modified and is not identical to the original version of the file with the same version number. The second parameter is a description of the patch, as literal/quoted text. This text may be displayed to the user when the user queries the program file for more information. Example:
Info Patched, "Patched by HackTheWorld666 to disable "
"annoying beeping.";
2 parameters. The second parameter is literal/quoted text containing the date that the program was released (to the general public or otherwise). The date text is interpreted and converted to a binary timestamp number. The date text is not stored in the file literally. The date text must be in the format of this example:
Info ReleaseDate, "1 Apr 2008";
If this command is omitted, then the release date defaults to unknown/unspecified.
2 parameters. The second parameter is literal/quoted text containing the name of the organization, company, or business that created the program, or the author or creator. This name may be displayed to the user when the user queries the program file for more information. Example:
Info OrgName, "Haxial Software";
2 parameters. The second parameter is the website URL of the organization or company that created the program, as literal/quoted text. This URL may be displayed to the user when the user queries the program file for more information. It may also be used to form a globally unique identifier for the program (relying on the fact that domain names are registered and globally unique). Example:
Info OrgURL, "http://www.haxial.com";
2 parameters. The second parameter is the e-mail address (in URL form) of the organization or company that created the program, as literal/quoted text. This URL may be displayed to the user when the user queries the program file for more information. Example:
Info OrgEMail, "mailto:support@example.com";
2 parameters. The second parameter is literal/quoted text containing a legal notice such as a copyright and/or trademark notice for the intellectual property in the program. This notice may be displayed to the user when the user queries the program file for more information. Example:
Info LegalNotice, "<copy> 2008 Haxial Software P/L";
2 parameters. The second parameter contains the name of a language, as literal/quoted text. This identifies the language of the text in the user interface of the program. Example:
Info Language, "English";
The language name should exactly match one of the following names (case-sensitive), or it can be a language not in the following list.
- "English"
- "English UK"
- "English US"
- "English AU"
- "French"
- "German"
- "Italian"
- "Spanish"
- "Swedish"
- "Russian"
- "Japanese"
- "Korean"
- "Chinese"
- "Chinese Simplified"
- "Chinese Traditional"
- "Vietnamese"
2 parameters. This command is used to include a source code file into the collection of source code that comprises the program, that will be compiled. The second parameter is the name of the file to include, as literal/quoted text. Normally it is just the file name but it can optionally be a URL (relative or absolute). For example:
Info IncludeFile, "MoreSource.kl";
If a relative URL is supplied, it is relative to the inside of the folder containing the file containing the Configuration containing the "Info IncludeFile" command. The following example uses a relative URL:
Info IncludeFile, "../UltimaTools/SharedDefs.kl";
The "Info IncludeFile" command can appear multiple times to include multiple different files. If the exact same file name (case-insensitive) is specified twice or if the same actual file is specified twice in the same Configuration, then the compiler reports an error.
The location of the file need not be specified in this command. The compiler searches for the file name in the input folders, comprising the same folder as the file containing the Configuration, the compiler folder containing standard definitions, plus all folders specified using "Info InputFolder" and "Info InputFolderDescend" commands.
2 parameters. This command is used to add a folder to the list of input folders that are searched when looking for a source code file of a specified name. The second parameter is the relative or absolute URL of a folder. If it is a relative URL, it is relative to the inside of the folder containing the file containing the Configuration containing the "Info InputFolder" command. For example:
Info InputFolder, "../MoreSource/";
The "Info InputFolder" command can appear multiple times to specify multiple input folders. The order of these commands is significant. For example, if the same file name appears in the first input folder and also in a later input folder, then the file in the first/earlier input folder is used.
If the specified input folder has any descendent folders, they are ignored (they do not become input folders). If you want descendent folders to be included, then use the "Info InputFolderDescend" command instead.
If no "Info InputFolder" commands are used, then the only input folders are the folder containing the file containing the Configuration, and the compiler folder containing standard definitions.
Same as "Info InputFolder" except that all descendent folders of the specified folder will also become input folders.
2 parameters. This command is used to specify an output folder. The files generated by the compiler are created in the output folder. The second parameter is the relative or absolute URL of a folder. If it is a relative URL, it is relative to the folder containing the file containing the Configuration. For example:
Info OutputFolder, "output";
If there is more than 1 "Info OutputFolder" command, the compiler produces an error message. If there is no "Info OutputFolder" command, the output folder defaults to the folder containing the file containing the Configuration.
2 parameters. This command specifies what files the compiler should create/generate (on disk) from the source code. The second parameter should contain 1 or more of the following identifiers separated by spaces:
| Name | Description |
|---|---|
| Portable | Generate a portable executable program file (".kex"). |
| CPPCode | Generate C++ code file(s) for input to a C++ compiler. |
| CCode | Generate plain C code file(s) for input to a C compiler. |
| CHeader | Generate a C/C++ header (".h") file. Requires that "CPPCode" or "CCode" be specified. |
| Standalone | Generate a standalone executable program file (for example, ".exe"). |
For example:
Info Generate, CPPCode Standalone;
2 parameters. The second parameter specifies the type of program being produced. It must be one of these identifiers:
| Name | Description |
|---|---|
| Application | A general application program (default). |
| Utility | Not a fully-fledged application. For example, a command-line utility performing a helpful task. |
| Service | A program that provides a service to other programs (as opposed to interacting with the user). For example, a network server program. |
| StaticLib | A statically-linked library of code (SLL). A program links with it at compile-time. |
| DynamicLib | A dynamically-linked library of code (DLL). A program links with it at run-time. |
| Plugin | A DLL being used as a plugin module. |
| Driver | A DLL being used as a device driver (for example, a driver for a hardware device). |
For example:
Info ProgramType, Application;
If this command is omitted, the program type defaults to "Application".
2 parameters. The second parameter is the full name (including module name) of an existing Command Implementation in the program source code, that will be executed when the program is launched, for the purpose of initializing itself. For example
Info InitCommand, MyProgram.Initialize;
This command is mandatory. If it is omitted, the compiler produces an error message.
If the initialization command causes an error at runtime, and it does not catch and stop the error, then an error message will be displayed to the user and the program will be terminated.
2 parameters. The second parameter is the full name (including module name) of an existing Command Implementation in the program source code, that will be executed when the program is launched, after the aforementioned initialization command. For example:
Info StartupCommand, MyProgram.Startup;
This command is optional. If it is omitted, then the step of executing the startup command is skipped.
If the startup command causes an error at runtime, then an error message will be displayed to the user and the program will continue running (unlike the initialization command). Thus the initialization command should perform actions crucial to the running of the program, such as creating essential data structures and objects that the program cannot live without, whereas the startup command should perform non-essential actions such as reopening a document that was open when the program was last closed.
2 parameters. The second parameter specifies the mode of the user interface in the program. It must be one of these identifiers:
- Service -- Does not normally have a user interface. Frex a network server program.
- HostCLI -- Use the native Command-Line Interface (CLI) of the host (MSWin, Unix).
- DirectCLI -- This program directly creates a local CLI user interface.
- IndirectCLI -- This program communicates with a CLI manager local or remote.
- DirectGUI -- This program directly creates a local Graphical User Interface (GUI).
- IndirectGUI -- This program indirectly creates a GUI by communicating with a GUI manager local or remote.
For example:
Info UserInterfaceMode, IndirectGUI;
If this command is omitted, the user interface mode defaults to IndirectGUI. Except if an "Info ProgramType, Service;" command is supplied then the user interface mode defaults to Service.
2 parameters. The second parameter specifies the debugging level. It must be one of the following identifiers:
- Off -- Disable debugging code/checks. Do not generate extra information for a debugger.
- On -- Enable debugging code/checks. Generate extra information for a debugger.
- Aggressive -- Everything that "On" does, plus enable aggressive debugging checks.
- Verbose -- Everything that "Aggressive" does, plus enable output of extra debugging messages at runtime.
- FastCompile -- Do not generate extra information for a debugger. Compiles the program quickly but may produce inefficient code. Good for quicker testing of multiple successive source code changes.
For example:
Info Debug, Off;
If this command is omitted, it defaults to "FastCompile".
2 parameters. The second parameter specifies the level of optimization to perform. It must be one of the following identifiers:
- Off -- Disable optimizations.
- On -- Enable recommended optimizations.
- Maximum -- Enable all possible optimizations (note might cause code bloat).
- FastCompile -- Disables optimizations, compiles the program quickly but may produce inefficient code. Good for quicker testing of multiple successive source code changes.
- MinimizeSize -- Enable optimizations, except for optimizations that tend to increase the size of the compiled code. May also perform optimizations that attempt to shrink the code. Favors small size over speed.
For example:
Info Optimize, On;
Regardless of what is specified in this command, optimizations are only enabled when "Info Debug" is set to "Off". Optimizations and debugging code are incompatible.
If this command is omitted, it defaults to "Off".
2 parameters. The second parameter specifies the floating-point mode. It can be "Accurate" or "Fast". For example:
Info FloatingPoint, Fast;
2 parameters. This command specifies which Central Processing Unit (CPU) Instruction Set Architecture (ISA) the compiler should produce an executable program file for. This option affects native machine code generation only. It has no effect on generation of a portable executable program file. The second parameter must be one of the following identifiers:
- Current -- Produce an executable program file optimized for the architecture and particular model of CPU in the computer that the compiler is running in.
- x86_32 -- Produce an executable program file for the 32-bit version of the Intel x86 ISA.
- x86_32_SSE1 -- x86 32-bit with use of SSE1 instructions enabled. SSE1 instructions exist in various Intel Pentium and AMD Athlon CPUs.
- x86_32_SSE2 -- x86 32-bit with use of SSE1 and SSE2 instructions enabled. SSE2 instructions exist in the Intel Pentium 4 CPU.
- x86_64 -- Produce an executable program file for the 64-bit version of the Intel/AMD x86 ISA.
- x86_64_SSE5 -- x86 64-bit with use of SSE 1 to 5 instructions enabled.
- CIL -- Produce an executable program file containing Common Intermediate Language (CIL) bytecode.
For example:
Info CPUISA, x86_64;
If this command is omitted, it defaults to "Current".
3 parameters. Each process has a stack used to store the values of local variables and parameters at runtime. This command changes the size of the stack. The second parameter is an integer specifying the initial size (in kilobytes) of the stack. The third parameter specifies the maximum size. For example:
Info StackSize, 32, 1024;
2 parameters. When automatically generating C/C++ source code, a C "#include" directive is generated at the start of the C file. This configuration option can be used to change the file name that appears in the C "#include" directive. For example:
Info CIncludeDirective, "MyHeader.h";
That will cause the generated C/C++ source code to contain:
#include "MyHeader.h"
The "MergeConfig" command causes the information in the specified configuration to be merged into the current configuration. This is convenient for making a configuration that is a variation on another configuration. All information values in the specified configuration are copied into the current configuration, overwriting any pre-existing values. Then after the "MergeConfig" command, "Info" commands can be used to overwrite some of the values that came from the specified configuration, thus creating a variation. For example:
Configuration CfgRelease;
Info Name, "SurfWriter";
Info ProgramType, Application;
Info InitCommand, MyProgram.Initialize;
Info UserInterfaceMode, IndirectGUI;
Info Debug, Off;
Info Optimize, On;
Info IncludeFile, "SurfShop.kl";
Info IncludeFile, "SurfBoard.kl";
Info IncludeFile, "MarvoWax.kl";
EndConfiguration;
Configuration CfgDebug;
MergeConfig CfgRelease;
Info FileName, "SurfWriter-Dbg";
Info Debug, On;
Info Optimize, Off;
EndConfiguration;
If the specified configuration does not contain an "Info" command of a particular type, then the "MergeConfig" command does not change, reset, or erase that information type in the current configuration. In the following example, the "MergeConfig" command is invoked to merge the configuration named "Cfg1" into the configuration named "Cfg2". The "MergeConfig" does not change the value of "Info InitCommand" in "Cfg2" because that information type is unspecified in "Cfg1".
Configuration Cfg1;
Info Name, "Test";
EndConfiguration;
Configuration Cfg2;
Info InitCommand, MyProgram.Initialize;
MergeConfig Cfg1;
{"Info Name" in Cfg2 is now "Test".}
{"Info InitCommand" is unchanged.}
EndConfiguration;
In the case of "Info IncludeFile" and "Info InputFolder" commands (commands that can appear multiple times), "MergeConfig" copies the list of files/folders from the specified configuration and appends it to the current configuration, without overwriting/erasing the list of files/folders in the current configuration. Thus the list becomes a combination/merger of the existing and the new.
The "MergeConfig" command can be used multiple times within the same configuration to make a configuration that is a combination of the values from 2 or more other configurations.