FutureBasic Logo

 <<    Index    >> FutureBasic
include   statement


Syntax
include { @"<path>" | "<path>" | alisResID }

Description
When the compiler encounters an include statement, it looks for a text file indicated by "<path>" or alisResID, reads the FutureBasic statements contained in that file, and effectively inserts those statements into the source code stream. "<path>" can be either a full or partial pathname; if you use a partial pathname, it's assumed to be relative to the folder containing the "parent" source file (i.e., the source file that has the include statement). "<path>" may refer either to a text file, or to an alias file whose target is a text file. alisResID must be the resource ID number of an "alis" resource whose target is a text file. This resource should exist in the resource fork of the "parent" source file.
include files may be "nested"; that is, an include'd file may contain references to other include files.

Example
Suppose we create a file "Assign.incl" which contains the following lines of text:
a = 3
b = 7

Now suppose we write a program like this:
dim x(100)
include @"Assign.incl"
c = a + b

When we compile this program, the result will be identical to this:
dim x(100)
a = 3
b = 7
c = a + b

Special treatment for C source and C header files (*.c and *.h):

include @"SomeFile.c"
include @"SomeFile.h"
Such files are copied to the build_temp folder. A #include statement is inserted in the translated FutureBasic code. This feature provides an alternative to #if def _PASSTHROUGHFUNCTION for mixing C with FutureBasic code.

Special treatment for C static libraries (*.a):

include @"MyLib.a"

The include statement copies the library file to the build_temp folder; you must also place the name of the library file in the preferences 'More compiler options' field [this causes it to be linked]. The example below is for a library MyLib that exports one symbol (MyLibFunction).

include @"MyLib.a"
BeginCDeclaration
// let the compiler know about the function
void MyLibFunction( void ); // in lieu of .h file
EndC
// let FB's translator know about the function
toolbox MyLibFunction
MyLibFunction // call the function

include resources "SomeFile.someextension"

The file indicated is copied from the FutureBasic source folder to the application's Contents/Resources/ directory, unless the extension is .nib in which case it is copied to Contents/Resources/en.lproj/.
This statement is the standard way to copy your sound (for example *.aiff), and image (for example *.icns) files into the application package. Nib files are handled by this statement, as an alternative to dragging them to your project window in FutureBasic version 5.

include library

MacOS X frameworks may be specified with the 'include library' statement, which has two forms:

include library @"Framework/Header.h"
include library @"Framework" // optional short form, expanded internally to: include library "Framework/Framework.h"

// tell the compiler the framework and header
include library @"AddressBook/AddressBookUI.h"
// tell the translator the functions
toolbox fn ABPickerCreate = ABPickerRef
...

The effect of include library is to insert the appropriate #include preprocessor directive in the translated C file, and to pass the appropriate linker command to the compiler.

Notes
The <path> parameter can be either a CFString literal or Pascal string literal.

FutureBasic's Project Manager is generally a more convenient way to combine the source code from several different files. However, there are some advantages to using the include statement, such as the ability to conditionally include files.
FutureBasic does not allow a given file to be included more than once in the source stream. If a second include reference is made to a given file, that include statement will be ignored.