Aztec Build
Till things are brighter... I'm the Man In Black.
- Johnny Cash
Aztec Build Process
The Aztec Build system is responsible for compiling Aztec source code and then integrating and linking that bytecode with the Aztec Class Framework. Even when an Aztec binary executable (.azcode) is going to be executed by the Virtual Machine, the Build system still gets involved to link the compiled code with the Class Framework and prepare it for execution.
The Aztec Compiler can be run in three separate modes.
♦ The compiler can be run standalone to create binary executable byte code and write it to a file using the “-comp” command line option.
♦ This operation creates an Aztec executable file with the extension ".azcode". Any number of source files can be compiled, both on the command line and using "CompilerLoadModule()", but a single ".azcode" file will be generated which will contain the executable code from all of the source files.
♦ In '-comp' mode, if a specified source file name has no extension, and no match is found, the system adds ".aztec" to the source file and tries to compile again.
♦ Aztec Compiler can be run using “-exec” option which compiles the source code module(s) and automatically passes the resultant byte code to the Virtual Machine for execution.
♦ In '-exec' mode, if a specified source file name has no extension, and no match is found, the system adds ".azcode" and tries again. Finally, if no match, it then tries ".aztec".
♦ The compiler can also be run during the execution of an Aztec Script. The Script class provides three separate families of methods to dynamically compile new Aztec source code at run-time. The Compiler is available on demand at run-time based on the use of these methods.
♦ Script.Interpret() family of methods to dynamically compile and execute Aztec source code on the fly.
♦ Script.CompileMethod() family of methods allows an existing method to be recompiled dynamically at run-time. The new code is automatically integrated into the Virtual Machine and Metadata system, and subsquent calls to that method will automatically execute the new code. The new source code can come from an Aztec string or a file.
♦ Script.LoadModule() family of methods allows an entirely new Aztec source code module to be compiled at run-time and integrated into the Virtual Machine and Metadata system. new code can consist of new classes and types, new methods and new data. New instance methods can be attached to an existing class if the class is marked as 'dynamic'. This set of methods allows code to dynamically grow classes at run-time. Any changes to existing "virtual method tables" are processed dynamically and updated within the Virtual Machine. The new source code can come from an Aztec string or a file.
The Aztec Engine decides how to use the compiler based on the operation mode (Execute, Compile, Interpret, etc.). The compiler processes the source code based on the language syntax and class framework as described in this Aztec Programming Language web site.
All source files which are compiled during a single execution of the Aztec Compiler are considered to be in the same 'unit' for identifier visibility purposes. This includes source files specified on the command line (using '-compile' or '-exec') and source files loaded using the CompilerLoadModule() method. They are all included in the same unit. Each separate call to Script.LoadModule() at run-time is a new unit.
As described in detail in the Executing Compile-Time Logic page, the compiler performs six separate processing steps for each source module. This allows identifiers across multiple modules to automatically see each other (depending on the visibility settings), and it also provides the infrastructure for performing very flexible logic during Step 4 of the compile process.
Command Line Parameters for Build
The compiler uses a system path to search for source files and executable files during the Build process. The path is a string that consists of one or more separate folders, separated by semicolon ( ; ) character. The “-path” option on the Aztec command line specifies the initial system path, and new folders can be added to the path dynamically using the CompilerUsePath() method. This method can be used during the initial compile process and during a run-time compile session using one of the Script.LoadModule() methods.
♦ For each source file the compiler tries to load, it looks for the file in each of the directories specified with the '-path' option until it finds a match.
♦ If the source file name contains one or more directories ('\' character) or a disk drive name ('c:'), the name is used as-is, and the directories specified using '-path' are ignored.
♦ If the source file name is used with no extension, and the file is not found in a given directory, extensions of ".aztec" and ".azcode" are both tried.
♦ If the file is found with both ".aztec" and ".azcode" extensions, the ".azcode" file is used if the Engine is running in Execute mode and ".aztec" is used if running in Compile mode.
♦ A compile error occurs if it's not found.
The compiler provides access to Engine command line “-flag” entries using the CompilerFlag() method for compile-time logic (e.g. Aztec -flag red green -exec SourceFile).
Aztec Space attributes can be modified on the command line using “-space” (Set Current), “-use” (Add to Search List) and “-remove” (Remove from Search List).
By default, every data identifier must be explicitly defined (using the data<> statement) in order to be used in an expression. The "-implicit" command line option allows the use of local variables within methods without explicitely defining them. The compiler performs the data definition implicitly using a data type based on the context in which the identifier is used. The data identifier must then be used in a consistent manner (relative to data type) throughout the method.
The Aztec Compiler supports "short circuit" boolean logic by default. If a boolean expression has two operands, the second part of the expression may not always be evaluated, if the result of the operation can be determined by knowing the result of the first operand. The following short circuit rules are implemented by default, during compile-time logic and during run-time expression evaluation.
♦ For the expression ( A & B ), the B term will not be evaluated if the A term is false.
♦ For the expression ( A | B ), the B term will not be evaluated if the A term is true.
If the "B" term is an expression that contains one or more method calls, the method calls will not be performed if the conditional logic is short-circuited as described above. The Engine command line parameter "-fullexpr" turns off short circuit evaluation for all expressions evaluated during compile-time logic and for the Virtual Machine bytecode generated by the compiler. With "-fullexpr" turned on, the method calls in the B term above are guaranteed to be called, regardless of the value of the A term.
When the Build system determines the entry point for the start of the Script, the class or method name that the system searches for is "Main" by default. The compiler searches for the starting point in the following order.
♦ A class named "Main" that is derived from "Thread". The VM creates the object automatically and invokes the Run() method to start the script.
♦ A shared method named "Main" inside a class. The VM invokes the shared method automatically to start the script.
♦ A global method named "Main". The VM invokes the global method automatically to start the script.
The "-main XXX" command line option tells the Build system to use a different name when determining the entry point for the script. The same process mentioned above is followed, but the "-main" value (e.g. "XXX") will be used instead of "Main".
♦ This feature can also be used to provide multiple entry points into a script/application in a single file.
♦ During the Build/Compile process, a valid main method must be specified, whether it is the default "Main" or one specified by "-main XXX" on the command line.
♦ If running in "-exec" mode with Aztec source code, the Build/Compiler will compile the code and then launch the Virtual Machine automatically using the main method specified.
♦ If running in "-comp" mode, the main method or class must exist during the compilation (default name or using '-main'). Whether default or user specified, the main entry point is written into the Aztec bytecode. When the bytecode is executed, the '-main' option is not needed, as the bytecode tells the VM where to start. Of course, the '-main' option can still be used to override the name that was written into the bytecoode file, and provide alternate entry points into the script.
If the "-debug" command line option is used, the compiler embeds a VM instruction before each executable statement to tell the VM the source code location corresponding to the code it's executing.
♦ By default, the VM only knows the source code location for the start of each method. This was done for efficiency reasons.
♦ The "-debug" option can be used for more accurately identifying the source code location of an exception down to the Aztec statement level.
♦ Its use will result in a small drop in run-time performance, typically on the order of 2 percent to 10 percent depending on the source code, and will produce slightly larger bytecode.
♦ More features are planned for this debug option in the future.
The "Build Log" can be displayed via the system menu available with the "-menu" command line option. This shows a detailed list of all messages which came from the compile process, including warnings and errors from the Aztec Compiler and messages manually written to the log using the CompilerWriteLog() method.
♦ There is a separate tab in the dialog for "Initial Build" versus "Run-Time Build".
