Blitz:Compiling

Compiling your program is very easy in Blitz Basic / AmiBlitz. The integration of the editor and compiler streamlines the process so you don't have to worry about linking libraries or creating make files. All compiling activities are accessed from the Compiler menu in the editor, and the default settings are suitable for starting off so you don't need to worry about them for making your first "Hello World"!

Testing Your Program

The first compiling function you'll probably use is the Compile and Run option. This option compiles your program and runs it from within the Blitz environment. Your program is compiled and assembled in memory, and then executed just like any other program except it doesn't exist as a program on disk.

By default, the Blitz debugger is enabled, and will also be run with your program. This allows you catch many problems and monitor your program's execution, but does slow it down quite a bit as a result. With the debugger disabled (see Compiler Options below), your program will run at the same speed as it would if it was a stand-alone executable.

A Shell window is opened for your program to use for its default input and output, so you can use it as if it was started from the AmigaDOS Shell.

If your program has already been compiled and run, there is also a Run menu item which simply re-executes the last compiled version of your program. This saves the compile time but doesn't take into account any changes to the source since the last time it was compiled.

Note: This function does not behave correctly under OS4 and often crashes, presumably due to whatever tricks it uses not being compatible with the 68k emulation. I haven't tested it under MorphOS yet...

AmiBlitz also provides a Save, Compile and Run option which is useful for saving your source file before compiling and running it, just in case your program crashes and causes you to lose any unsaved source code changes.

Startup Parameters

When testing a program, occasionally you might need to check how it behaves given certain file arguments through the Shell. These parameters can be set for testing using the Set CLI Parameters menu item. Simply enter the required arguments here and test your program. These arguments are saved when you save your project.

Working Directory

By default, when testing, your program is run as if it's in the Blitz directory. This might not work well if your program expects to have certain other files with it, e.g. graphics files to load for a game. To set the directory to test your program from to a different location, you need to create an executable first using the Create Executable... menu option. Once that is done, your test program will use the directory you chose in which to create the executable as its own directory too. This will remain the case until you create a new executable in a different location. Don't worry if the program isn't ready to be made into an executable just yet, it'll still work :)

Creating Executables

Once your program is ready to be made into a stand-alone executable, choose the Create Executable... menu item (Create File in the original Blitz Basic 2.1 TED). This will ask you to select a location and filename for your executable program. Blitz will then compile it and build your executable automatically, ready to try out in the "real world"!

Note: You should always disable the debugger before creating your executable. The debugger includes special extra instructions in the file to communicate with the debugger, and these cause the executable to be much larger than it would be otherwise. It will also crash under OS4!

Creating Minimised Executables

AmiBlitz includes an extra option for optimizing executables. This scans the code more thoroughly to remove any unneeded instructions, and so creates a smaller executable file. The downside of this is that is usually takes much longer as the compiler often has to make multiple passes instead of just one or two. Selecting the Create Minimised Executable menu item will create a new, smaller executable in the location selected by the Create Executable... function. This probably only needs to be used for the final release version of your program once all testing is complete.

Compiler Settings

Compiler Settings Window

Open the Compiler Settings window using the appropriate option in the Compiler menu. This gives many options for controlling how your program is built. This settings window will look different for older versions of Blitz, but the general options included are mostly the same.

The default settings will be fine for starting out, but as your programs advance, some of the options will become more useful. The settings are saved with your source code, so changes made here will be remembered the next time you open that particular program. The main options are explained below:

General Settings

Create Icons for Executable Files

Enabling this item will make Blitz add an icon to any stand-alone executable files you create. It's not a very pretty icon (it's based on the OS 1.x palette), but it works fine for testing...

Make Smaller Code

This option causes the compiler to make extra passes through the code to remove any unnecessary parts. It results in the program taking a little less memory when running, but increases the compile time, so possibly only of use if you're short on RAM.

Active Function Optimizer

This option is only available in AmiBlitz 3. Not sure about the specifics of what it does...

Add Debug info to Executable Files

This includes debug symbols in the executable files created. This can be useful for some advanced debugging, as the symbol near the problem-causing instruction can be reported by certain executable debugging tools. It will make executables a little bigger but won't affect performance.

Create .dbg File

This option enables the creation of a debug file in the same directory as the executable created. This file includes a list of line numbers from your source code along with an offset value that represents where this instruction's equivalent 68k code is located within the executable. This is useful because certain crash reports can include the "hunk offset", which can be compared with the values in this file to see roughly where in your source the error occurred.

String Buffer size

This is the number of bytes Blitz allocates for doing string operations. Normally the default value is plenty for almost any purpose, but if you're carrying out large operations, you might have to increase this to avoid errors.

Stack Size

This is the stack allocated for the program when running from within Blitz. Again, the default value should be fine, but if you use many recursive procedures or large lists you may need to increase this setting. Executables will have their own stack setting in their program icon so this setting has no effect outside of Blitz.

Debugger Settings

Runtime Error Debugger

Enables or disables the debugger for programs compiled and run from Blitz.

Auto Run

Enable this option to have a compiled and run program start automatically. If this is disabled, the program will stop immediately before the first instruction to allow you to step or trace from the very start.

Interrupt checking

Enables the debugger checking within interrupts in your program. Normally this is fine to leave on, but in come cases can cause problems, e.g. if the debugger causes your interrupt to run too slowly that it causes problems.

Assembler Checking

Tells the debugger to also check inline assembler for errors.

Overflow Checking

This checks your code for any variable overflows that may occur. Variables overflow when the number they contain is too large for them, and wraps around to the opposite end of the scale. This won't cause crashes in itself, but can lead to undesirable behavior, and crashes later on if the incorrect results of some function or calculation are used e.g. for a memory address. Normally this is a good thing to check, but occasionally it can cause the debugger to stop your program unnecessarily. This is because Blitz treats all variables as signed, but some functions require unsigned values. Internally there is no binary difference, but these situations will trigger an overflow error so this option can be disabled to avoid these false errors.

Max Objects

This is a list of all the different Blitz objects available, along with a maximum number for each. Creating an object with an ID higher than the relevant maximum will cause an error that the debugger will catch, but will cause a crash without the debugger and in executable files. If required, a new maximum number of objects can be entered here. There's no point in entering high numbers if you don't need them however; it will just use a little more memory at run time.

Resident Files

This is a list of all resident files included in your current project. Resident files are pre-compiled lists of definitions, such as constants, structs and macros. See the Resident Files section for more information.