Build System Caching
Appendix K - Build System
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:
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 FBtoC settings are:
Min OS deployment
Max OS features
Use DWARF debug format
Changing any of those settings invalidates all cached information at the next build.
Running Under Xcode Debugger
Turn off 'Load symbols lazily', and set to show Debugger at startup:
Build your app with FBtoC 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.
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.:
Xcode User Guide: Debugging
Xcode User Guide: Attaching to a Running Process
*.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 FBtoC's generic BlueLeafC.icns as the *.icns file. Hence, the compiled application will display FutureBasic/FBtoC'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. FBtoC 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"