Compilation
In addition to a specialized text editor, PowerBASIC for Windows ships with a compiler that converts the PowerBASIC source code into an EXE or a DLL. The compiler is a separate program but is called from within the text editor.

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	#DEBUG CODE, #DEBUG DISPLAY, #DEBUG ERROR, #DEBUG PRINT
Compile Constraints	#DIM, #COM, #COMPILE #COMPILER, #OPTION, #PBFORMS
Performance	#ALIGN, #OPTIMIZE, #REGISTER, #MESSAGES, #STACK, #TOOLS
Inclusion	#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.

#ALIGN - align instruction to boundary
#BLOAT - force program to specified disk image size
#COM - provide information for COM Type Library
#COMPILE - specify EXE or DLL compilation
#COMPILER - specify compiler
#DEBUG CODE - suppress debugging code generation
#DEBUG DISPLAY - display untrapped run-time error messages
#DEBUG ERROR - control generation of error checking code
#DEBUG PRINT - print to IDE debugger output window
#DIM - require variable declaration before use
#DEF - determine if equate has been defined
#IF/#ELSEIF/#ELSE/#ENDIFs - select code for compilation
#INCLUDE - insert source code from text file
#MESSAGES - select messages to be sent to control callbacks
#OPTIMIZE - choose faster execution or smaller code size
#OPTION - set minimum Windows version requirements
#PBFORMS - mark code generated by PB/Forms
#REGISTER - control register variables
#RESOURCE - embed resource file
#STACK - set stack size
#TOOLS - include integrated development tool code
#UTILITY - allow external reading of #UTILITY line content

Compiler Directives Reference
This section goes beyond the one line description above, giving additional information on using the compiler directives.

#ALIGN - align next instruction to a boundary

Syntax:
```
    #Align boundary    'boundary is a power of 2, between 2 and 256
```
Use to place code for maximum speed.
#BLOAT - force program to specified disk image size

Syntax:
```
    #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 - provide information for COM Type Library

    #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 - specify EXE or DLL compilation

    #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 - specify compiler

    #COMPILER PBWIN 9
    #COMPILER PBWIN 8, PBWIN 9
           - target compiler
           - version must be in #.## format

Optional. If not provided, a compile is attempted.

#DEBUG - suppress debugging code generation
```
    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 - require variable declaration before use
```
    #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 - determine if equate has been defined

    #%DEF(%equate)       ' returns TRUE or FALSE

#IF/#ELSEIF/#ELSE/#ENDIF - select code for compilation
This is called conditional compilation.

    #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.

%PB_EXE

#INCLUDE - insert source code from text file
Used to break large files into small ones, or to use a managed common file.
```
    #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 - select messages to be sent to control callbacks
```
    #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 - choose faster execution or smaller code size
```
    #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 - set minimum Windows version requirements

    #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 - mark code generated by PB/Forms
```
    #PBFORMS ... DO NOT USE!  Generated by PBForms app.
```
These compiler directives are created by PBForms and should not be used or modified.

#REGISTER - control register variables

    #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.

#RESOURCE - embed resource file
```
    #RESOURCE "resources.pbr"
```
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 - set maximum stack size
```
    #STACK 2048     '1024 KB is default
```
Applies to EXE files only. Must be in multiples of 64Kb
#TOOLS - include integrated development tool code
```
    #TOOLS ON           '  #TOOLS +
    #TOOLS OFF          '  #TOOLS -
```
Disables Trace, Profile, and CallStk. Eliminates compiled code associated with these tools.
#UTILITY - allow external reading of #UTILITY line content
```
    #UTILITY   
```
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.