FutureBasic Logo

<<    Index    >> FutureBasic

Appendix K - Build System   appendix



Build System Caching

During compilation, data is cached in the source directory's build_temp folder. Reusing this data in subsequent builds allows some steps of compilation to be skipped. Builds subsequent to the first one are therefore faster. The caches affect the compilation phase only, not translation.

The caches are maintained as files in build_temp. If build_temp or its files are missing, the files are regenerated. If certain critical compilation settings are changed, the cached information is invalidated, and automatically regenerated during the next build.

Two kinds of cached information are maintained, specifically precompiled FutureBasic (version 5 onwards) code and header information from the MacOS X frameworks.

Precompiled FutureBasic code

The compiled code is in a series of *.o files in build_temp. Each *.o file contains binary code derived from one or more FutureBasic source files. For example:

_0_TranslatedRuntime.o
...
_15_Loop_Statemen,Conditional.o
...
_19_Init,Main_,FBtoC,FBtoC.o

A *.o file is compiled from its matching C source (*.c and *.h files). If these are both unchanged since the last build, compilation can be skipped.

Special indicator files are used to vouch for the integrity of *.o files; their long names (like _0_TranslatedRuntime.c_9aee936b...1b85b8e50_10023_149.vch) encode the md5 checksum of the matching C source along with the current compiler settings.

Header information from the MacOS X frameworks

Also known as a precompiled header or pch, this cache is controlled by the settings checkbox 'Use precompiled header'.

The cache, in a format private to the compiler, is in the folder build_temp/FBtoCPrefix.h.gch/

Both forms of caching are most effective when repeated builds for a single architecture and with the same settings are built. This is typically the case during program development, for which fast compilation is especially desirable. The recommended development settings are:

Architecture = Current Mac
Use precompiled header = Yes
Optimization = None

If, on the other hand, certain settings are changed, the entire program (and pch if enabled) must be recompiled.

The relevant build settings are:

Architecture
Min OS deployment
Max OS features
Use DWARF debug format
Debug level
Optimization.

Changing any of those settings invalidates all cached information at the next build.


Running Under Xcode Debugger

Xcode preferences

Turn off 'Load symbols lazily', and set to show Debugger at startup:

Build settings

Build your app with build settings 'Debug level: fn names and line #'.

If possible, turn off the checkbox 'Allow dim a%, a&, a#, a$'. This makes variable names in C easier to read.

Debugging

After the build, choose File > Debug Last App.

FBtoC sets up an Xcode project to debug your app as a "custom executable" (see Debugging Arbitrary Applications With Xcode)

All going well, you get full source-code debugging, with symbolic break-points etc.:

Reference

Xcode User Guide: Debugging
Xcode User Guide: Attaching to a Running Process


Includes

*.icns file from 'icns' resource (to <app>/Contents/Resources)
If an 'icns' resource exists in a project resource file, the 'icns' resource is saved as a file in /Contents/Resources. This is automatic and does not require the use of the include resource statement. The file name is derived from the resID of the 'icns' resource, eg. 128.icns. This is the same method used by MakeBundle.

Info.plist (in <app>/Contents/)
FutureBasic automatically copies a generic Info.plist into the compiled bundle's Contents directory. That generic Info.plist template can be found in FutureBasic at: build_goodies/BuiltApplication.app/Contents/Info.plist.in

A consequence of using that generic template is that it indicates FutureBasic's generic BlueLeafC.icns as the *.icns file. Hence, the compiled application will display FutureBasic's generic BlueLeaf icon.

The user may override the default behavior based on "Info.plist.in" by including a user-supplied Info.plist file in the FutureBasic source folder. The translator will automatically find the user-supplied Info.plist and use that, thus overriding its default behavior.

In that case, the user will also have to include a *.icns file corresponding to that pointed to by CFBundleIconFile in the custom Info.plist. The user's custom *.icns file can be copied to the compiled application bundle with 'include resources':

include resources "AppIcon.icns"