Wattleglen Calc Compiler
(c) Mark McIlroy 2024

Version 5.60
20 July 2024


1. Introduction

The Wattleglen Calc Compiler is a compiler that compiles Calc code, written according to the language definition in the book 'The Calc Programming Language' by the author.

The compiler is supplied as a stand-alone executable file which runs on Linux systems. Also included is a C language version of the compiler so that it can be used on other platforms.

The compiler produces C code as its output. This can be compiled on any platform that has a C compiler, and linked with the Calc libraries and C standard libraries to produce an executable file.

A runtime environment is not required for either the compiler or the final user executable.




2. Files supplied

The compiler is named calc_compile.exe

The compiler produces a C program which needs to be linked with the following files:


calc_lib.c 
calc_stdlib.c 
calc_stdlib_c.c 
bst_tree_c_version.c 
bst_tree_c_version_calc_interface.c

calc_mysql.c		or calc_no_db.c
calc_lib.o 
forms_library.c


-lm					Link in the C maths library
-lmariadb			Link in the MySQL library


Example usage:

	calc_compile.exe x.calc :ox.c :Ilibraries :I/path/to/user/program/header/files

	gcc x.c -o x.exe calc_lib.c calc_stdlib.c calc_stdlib_c.c calc_mysql.c forms_library.c bst_tree_c_version.c bst_tree_c_version_calc_interface.c -lm -lmariadb




3. Command line options

The command line options to the compiler start with ':' and should not have spaces in them, spaces are used to separate each option.

The command line options are:


:oXXXX					The name of the output C file that is to be generated (required).
:IXXXX					A path that contains 'include' files. Multiple :IXXXX options can be specified, at least 1 is required .

:ep								Generate an execution profile in the file 'exec_profile.txt'.
:ascii_only						Runtime option, use on calc-generated exe files (including the compiler) to make them run faster.
:is_webpage						Include this option if the user executable is intended to generate a web page.
:memory_report					Print a report of the memory usage of the compiler. Use this option on the user executable to view the stack usage.
:show_execution_trace			Print a trace of the program execution.
:no_output_comments				Do not print comments in the produced C program. 
:no_array_bounds_checks			Remove array bounds checks to improve speed.
:no_runtime_checks				Remove runtime checks to improve speed.
:show_additional_warnings		Show non-critical warnings.
:no_show_warnings				Don't print warnings.
:dont_initialise_variables		Don't initialise variables for improved speed.
:stop_on_warnings				Stop make process on warning messages.
:show_large_strings_warnings	Show sections of code that involve copying large strings or resizable arrays.
:max_string_constants=XXXX
:max_user_defined_types_per_compile=XXXX
:max_function_table_items_per_compile=XXXX
:osource_code_language_file=xxxxxx		Specify the language of the source code file.


		
4. Web pages

A user program that is intended to generate a web page should be compiled with the :iswebpage command line option.

When the program is run, it must have two parameters.

The first parameter is a path to a file that contains get and post data from the previous web page. This file can be empty but it must exist.

The second parameter is a path to the file which is used to redirect to a different web page. This parameter can be a dot '.' meaning the current directory.

For example:


./sample_program1.exe get_and_post/x.txt .



5. Database connectivity

The package includes an interface to MySQL. To use this interface, compile and link in calc_mysql.c to the user executable.

If database access is not required, compile and link in the file calc_no_db.c instead.

If access to another database system is required, and interface will be needed that has the same functions as the calc_mysql.c file.



6. Memory management

Using the default internal sizes, the compiler requires approximately 200Mb of memory. The defaults should be sufficient to compile most Calc source code files.

To check the memory usage of a user source file, compile the file with the :memory_report command line option.

To increase or reduce the compiler memory requirements, use the following command line options:


	:max_functions_per_compile=XXXXXX
	:max_function_parameters_per_function=XXXXXX
	:max_lines_per_source_file=XXXXXX
	:max_source_files_per_compile=XXXXXX
	:max_tokens_in_input=XXXXXX
	:max_user_defined_types_per_compile=XXXXXX
	:max_function_table_items_per_compile=XXXXXX


To check the run-time memory usage of a user file, run the user executable with the :memory_report command line option.

The main parameter that can be altered in the run-time is the memory stack allocation, which is used for function parameters, local variables and expression evaluation.

To alter the stack size in the user executable use the :st=XXXXXX command line option when compiling the main source file (the XXXXXX is the stack size in bytes).



7. Program memory usage.

Simple variables using this compiler occupy 24 bytes each. Arrays and struct types take up 24 bytes times the number of items in the structure,
resizable arrays also have a small additional overhead.

'int' types are 8 byte integers, 'doubles' are double-precision floats and 'decimal' types have two decimal places.

Strings may be up to the size of an 8 byte integer in length.



8. Multiple files


To combine multiple source code files into a single Calc project, follow this procedure:

a)	Include a 

module_name xxxx

statement at the top of each source code file, with a different name for each file.


b)	In the main file, include a:

module_type “main” 


statement at the top of the file and a function:

function int main( int argc, array of string [100] argv )
{
….
}.


c) 	In every other source code file, include a:

module_type “secondary” 

statement at the top of the file.


d)	In the main file, include a 

link_module modulename1 

statement at the top of the file for each of the secondary files.


e) Debugging module linking

An 'undefined reference to XXXXX_setup_tables' link error means that you have included a link_module statement for a module or library but you have not included the file in the C compile/link command.

An 'undefined reference to XXXXX_link_variable means that you have not included a link_module statement in the main Calc file for a module that is linked into the project. Include a link_module statement in the main Calc file, with the module name of the linked module (this name should match the XXXXX in the error message).

An 'undefined reference to `main' means that you have not included a 'main()' function within your code or linked the Calc project into a C program that has a 'main()' function.

A `multiple definition of `_user_function_f1' error mean that you've included a function named 'f1()' in more that one Calc source file in the project.

A 'multiple definition of `var_set_s' etc' error means that you've defined a 'module_type "main"' in more than one source code file within the system.

Multiple undefined references may mean that you haven't included a file with 'module_type "main"' in your system.



9. Foreign languages

The Wattleglen compiler supports Calc source code written in foreign languages.

Use the :osource_code_language_file=xxxxxx command line option to specify the language that the source code is written in.

If your preferred language is not available follow this procedure:

a) Copy the file english.calclanguage to XXXXX.calclanguage where XXXXX is the name of the new language.

b) Edit the new file and change the English words after the 'token_text' column to the foreign language equivalent. The foreign words may contain apostrophes but not spaces.



10. Using the Execution Profiler

To generate an execution profile, compile all Calc files in the project using the :ep option.

When the program is run it will generate a 'exec_profile_XXX.csv' file.

This file will contain the number of times each function in the project is called, 
and the number of times statements in each function are executed ('ticks').

This file will assist the programmer in improving run times by identifying where in the program code
the most execution time is being used.



11. Performance

By default Calc programs include extensive debugging checks. For example, y = x[i] will check the value 
of 'i' to ensure that it is not negative or greater than the size of the array index.

For maximum speed for in-house applications that will not be distributed, specify 
the :no_runtime_checks and :no_array_bounds_checks options on the calc_compile.exe command line and 
turn on maximum optimisation on the C compiler command line.




12. Forms library

The module 'forms_library' contains functions for basic HTML forms.

If linked in the following functions must be present in your application code:


function void additional_screen_initialisations( string id, bool newrecord, string form_name, string table_name, array [MAX_SCREEN_FIELDS] of screen_field screen_fields, int num_screen_fields, db_connection cxn )
{
}

function void generate_custom_fields( bool newrecord, string form_name, string field_name, bool right_side_pane, array [MAX_SCREEN_FIELDS] of screen_field screen_fields, int num_screen_fields, db_connection cxn )
{
}

function void additional_validations( int id, string form_name, bool newrecord, string validation_errors, array [MAX_SCREEN_FIELDS] of screen_field screen_fields, int num_screen_fields, db_connection cxn )
{
}

function void additional_changes_before_database_save( int id, bool newrecord, string form_name, string table_name, array [MAX_SCREEN_FIELDS] of screen_field screen_fields, int num_screen_fields, db_connection cxn )
{
}


  
