Within an application's source code, a programmer can place special directions for the compiler, called directives. Directives are standalone lines of text, preceded with a pound sign (#) as shown in the following examples. Directives are read by the compiler but are generally not compiled into the resulting EXE or DLL files.
The compiler directive options can be broken roughly into the following categories.
#DEBUG CODE, #DEBUG DISPLAY, #DEBUG ERROR, #DEBUG PRINT
#DIM, #COM, #COMPILE #COMPILER, #OPTION, #PBFORMS
#ALIGN, #OPTIMIZE, #REGISTER, #MESSAGES, #STACK, #TOOLS
#BLOAT, %DEF, #IF, #INCLUDE, #RESOURCE, #UTILITY
Most Used Compiler Directives
Application source code may contain special directions for the compiler, called directives. Directives are standalone line of text, preceded with a pound sign (#) as shown in in the following examples. Directives are read by the compiler, acted on, and then ignored. They are not compiled as part of the resulting EXE or DLL files.
#compile exe - create EXE #compile dll - create DLL #dim all - delcare all variables before use #include "extracode.bas" - insert code from file "extracode.bas"
Of the 21 compiler directives, these four are perhaps the most common, and at least one will be used in every program you write.
Compiler Directive Listing
Here's a complete list of the 21 compiler directives recognized by PowerBASIC. Except for the four directives listed above, most of these are used only when a programmer has a specific need or issue to resolve - very useful when needed, just not needed all that often.
Most of these allow the inclusion of one or more arguments which tailor how the directive works. See the PowerBASIC help file for additional details.
Compiler Directives Reference
This section goes beyond the one line description above, giving additional information on using the compiler directives.
#Align boundary 'boundary is a power of 2, between 2 and 256
Use to place code for maximum speed.
#BLOAT size_expression 'desire size of the compiler program
Even having read the PowerBASIC Help file, I can't find a good reason to use this. Judge for yourself.
#COM DOC description$ - string describing the COM server #COM HELP "myhelp.chm", code$ - help file name (string literal) - context code (unsigned DWORD > 0) #COM NAME "mylib", 4.2 - server name - version #COM GUID GUID$ - GUID for the application #COM TLIB ON|OFF 'direct compiler to create type library - directs compiler to create type library
#COMPILE EXE "my.exe" #COMPILE DLL "my.dll" - file name of EXE or DLL - default is source code file name (with EXE/DLL extension)
Can compile to EXE or DLL, but not both.
#COMPILER PBWIN 9 #COMPILER PBWIN 8, PBWIN 9 - target compiler - version must be in #.## format
Optional. If not provided, a compile is attempted.
DEBUG CODE ON ' Display Code + DEBUG CODE OFF ' Display Code - DEBUG DISPLAY ON ' Debug Display + DEBUG DISPLAY OFF ' Debug Display - DEBUG ERROR ON ' Debug Error + DEBUG ERROR OFF ' Debug Error - DEBUG PRINT "any text" DEBUG PRINT "more text"
Debug Code determines if compiler adds special debug code. With the code performance may be slowed. Without the code breakpoints cannot be set. Mutiple Debug Code ON/OFF statement pairs can be used to selected surround code. Applies only to a debugging session.
Debug Display controls whether a MsgBox is used to display untrapped errors.
Debug Error controls whether the compiler includes code to check for array boundary and null-pointer errors. Enable during development, disable for production apps.
Debug Print lines may be used multiple times, located anywhere within a program. Only applies during a debugging session.
#DIM ALL 'Dim all variables #DIM NONE 'Dim only arrays
"Option Explicit" can be used in place of #DIM ALL.
When #DIM ALL is used, type specifiers are not allowed in DIM statement. Also, DEFxxx statements will be ignored.
#%DEF(%equate) ' returns TRUE or FALSE
#IF %equate | #IF %DEF(%numeric_equate) | 4 ways to use #IF #IF %DEF($string_equate) | NOT is allowed following #IF #IF (expression) | ... statements #ELSEIF (repeat of 4 types in #IF above) ... statements #ELSE ... statements #ENDIF #IF %PB_EXE ' %PB_EXE is true if DLL is being created FUNCTION PBMAIN ...statements END FUNCTION #ELSE ' %PB_EXE is false if DLL is being created FUNCTION PBLIBMAIN ...statements END FUNCTION #ENDIF
In PB/Win32, the equates %PB_Win32 (True), %PB_Revision, %PB_RevLetter and %PB_EXE are pre-defined. These find frequent use in the #IF structure.
#INCLUDE "win32api.inc" #INCLUDE ONCE "dialogs.inc"
If not provided, a .bas extension is assumed. If path of file not given, compiler uses search path as set in Options Dialog. Path can also be set in command line (/l option).
Inclusion can be up to twelve levels deep (included files can have included files of their own).
ONCE is used to protect against inadvertent repeat of an #INCLUDE.
#MESSAGES COMMAND '%WM_COMMAND only #MESSAGES NOTIFY '%WM_NOTIFY and %WM_COMMAND
Default is to send both %WM_NOTIFY and %WM_COMMAND messages to control callback functions.
#OPTIMIZE SIZE 'optimize for size #OPTIMIZE SPEED 'optimize for speed (default)
WIth SPEED, compiler action includes boundary alignment of code. Speed option is especially beneficial in loops (FOR/NEXT, DO/UNTIL, ...)
#OPTION VERSION3 'Win95, NT3.1 #OPTION VERSION4 'Win95, Win98, ME, NT4.0, 'Win2000, XP, Win2003 and later #OPTION VERSION5 'Win2000, XP, Win2003 and later
Primarily ensures that compiler uses only API compatible with the selected version of Windows.
#PBFORMS ... DO NOT USE! Generated by PBForms app.
These compiler directives are created by PBForms and should not be used or modified.
#REGISTER ALL 'requests automatic allocation of all possible 'register values (Integer and Double) #REGISTER DEFAULT 'requests automatic allocation of all possible 'register values (Integer only, or Double if 'in routine cntaining no procedure references #REGISTER NONE 'disables automatic register variable assignment 'manual assignment is allowed
Variable in TO clause of Dialog Show Modal and Dialog Show State cannot be a register variable.
The resource file must be a PowerBASIC resource file. Microsoft resource file format is not accepted, but a PowerBASIC utility (PBRES.exe) is distributed with PowerBASIC which can convert the Microsoft format to a PowerBASIC resource file (*.pbr).
The PowerBASIC compiler can also compile a PowerBASIC resource file (*.pbr) directly from a resource script. However there are some limitations and PowerBASIC recommends using an external Resource Editor for creating more complex resource files.
There can be only one resource file per PowerBASIC module (EXE/DLL).
#STACK 2048 '1024 KB is default
Applies to EXE files only. Must be in multiples of 64Kb
#TOOLS ON ' #TOOLS + #TOOLS OFF ' #TOOLS -
Disables Trace, Profile, and CallStk. Eliminates compiled code associated with these tools.
Not used by compiler. #UTILITY was put in place to allow programmers to insert text that non-PowerBASIC utilities (which read the source files) can read without affecting the final size of the compiled program.
If you have any suggestions or corrections, please let me know.