Free Pascal Xcode integration kit 2.2.0

Table of Contents

1. Introduction
2. How to use
3. Customising
4. Known problems
5. Removing older templates
6. Troubleshooting and FAQs

1. Introduction

This package contains Xcode templates for use with the Free Pascal Compiler 2.2.0 and later (include 2.2.0).

Two templates are included:
	•	FPC Carbon Application 2.2.0: sets up a Pascal Carbon application project with resources and nibs
	•	FPC-C-C++ Carbon Application 2.2.0: sets up a Carbon application project with resources and nibs, and mixed Pascal, C and C++ source files
	•	FPC Standard Tool 2.2.0: sets up a Pascal command line tool project

The projects have been tested with Xcode 2.4.1 and a prerelease version of Xcode 2.5, but should work with later versions. Previous Xcode versions are unsupported, and the templates will definitely not work with Xcode versions prior to 2.3. The templates work for both the PowerPC and Intel versions of the compiler. Creating a universal binary is currently only supported on Intel Macs.

2. How to use

	a.	Create a new Project
	b.	Under the heading "Pascal", choose one of the templates mentioned above
	c.	Once the project is created, either modify the template files, or remove them and add your own files (note: if you add main program with a different name, see the Customising section below on how to adapt the project)

When distributing your compiled program, you do not have to distribute the libfpc.a file which is generated as part of the build process. The needed parts are linked into your program.

3. Customising

Command line options:

The template passes some default command line switches to the compiler. You can customise these if you want:

	a.	Double click on the project icon at the top of the file browser
	b.	Go to the Build tab
	c.	Select the configuration you want to edit (Debug, Release or All Configurations) from the top pop-up menu
	d.	Select the Customized Settings collection from the second pop-up menu
	e.	Changes to FPC_COMMON_OPTIONS are common for Debug and Release builds, and those to FPC_SPECIFIC_OPTIONS are configuration-specific (so don't edit this one when All Configurations is selected, or you will overwrite the options for both configurations with a single set -- this may e.g. remove debug information of the Debug build)

For an overview of all possible command line switches and what they do, have a look at the User's Manual (installed in /Developer/Documentation/Free Pascal Compiler), Chapter 5.

Main program file:

The previous templates automatically detected the main program file. Due to issues with caching this information (and properly removing it again when cleaning the project or adding a new main program file), this is no longer done. Therefore, the main program file now has to be specified explicitly in the project settings.

Should you change the name of the main program file, you can change it as follows (the same is in the previous templates)

	a.	Double click on the project icon at the top of the file browser
	b.	Go to the Build tab
	c.	Select the All Configurations from the top pop-up menu
	d.	Select the Customized Settings collection from the second pop-up menu
	e.	Change the FPC_MAIN_FILE setting to the name of your main program file, including the extension.

4. Known problems

	•	Mixing C and Pascal: Due to the way we integrate with Xcode (because of various Xcode bugs), we have to turn off the generation of debug information in Xcode for the Pascal target (FPC still generates debugging info though). This means that if you mix C and Pascal in the same target, the C files will always be compiled without debugging information. You can solve this by compiling the C files in a separate target into a static or dynamic library and linking that library with your Pascal code. An example is shown in the FPC-C-C++ Carbon Application template.
	•	"Menus" unit: Free Vision is  a set of units compatible with Borland's Turbo Vision package. These units provide a way to create programs with some sort of GUI in a Terminal window (i.e., in text mode). One of these units is called "menus", which also happens to be the name of a unit in Apple's Universal Interfaces. To avoid conflicts, we exclude the Free Vision units from Xcode projects. A similar problem may occur if one of your units is called "memory"; the easiest solution is to rename any such units.
	•	Viewing global variables in the Xcode debugger: the globals browser often does not work. You can view global variables instead by choosing Debug→Tools→Expression... and then typing the name of the global variable
	•	Problems with View Value As… and View Memory…: Xcode assumes that the underlying debugger (gdb) is in C mode at all times. When using the aforementioned commands, it therefore sends C-expressions to the debugger, which it doesn't understand when inside Pascal code (because then it expects Pascal expressions). A tedious workaround in case you need this functionality at some point is to choose Debug→Console Log, and then type set lang c on the gdb prompt, followed by return/enter. To switch the debugger back type set lang auto.
	•	Problems with view strings and non-zero based arrays in the debugger: Xcode does not appear to ask the debugger to display strings and arrays, but has its own display routines for these data structures. It does not have any knowledge of Pascal strings, nor of non-zero based arrays (these do not exist in C), and will therefore display all arrays as if they were zero-based, and Pascal strings as a record (in which the nested array is displayed incorrectly because of the array problem). You can again work around this by going to the gdb console as in the previous item and typing p string_variable resp. p array_variable.

5. Removing older templates

Depending on which versions of FPC you previously installed, and which extra templates you installed, you may end up with a lot of (potentially outdated) Pascal project templates in Xcode. All these templates can be found in /Library/Application Support/Apple/Developer Tools/Project Templates/Pascal

Below, you can find a list of some templates you may find there, where they come from, and in what situations they may be usable:

	•	FPC Carbon App calling C and vice versa: template by Erling Johansen on which FPC-C-C++ Carbon Application 2.2.0 is based, still works with FPC 2.1.5
	•	FPC Carbon App hello world: template by Erling Johansen, still works with FPC 2.1.5. FPC Carbon Application 2.2.0 is similar, but uses the Pascal sources and resources from the Carbon project that was shipped with previous FPC versions
	•	FPC Carbon Application and FPC Standard Tool: FPC 2.0.4 templates for a Pascal Carbon application resp Standard Tool. They still work as well with FPC 2.2.0 as they did with FPC 2.0.4, but contain some errors (see Version History section below)
	•	Free Pascal Tool (XCode 2.1+) and Xcode221 Pascal Carbon template: precursors of the FPC 2.0.4 templates. May or may not work with 2.2.0, but definitely not recommended.
	•	Pascal Carbon Application, Pascal CGI, and Pascal Tool: Xcode 1.x templates, no longer work with current Xcode versions.

6. Troubleshooting and FAQs

1) Q: What can I do when getting the following error after building:

powerpc-apple-darwin8-gcc-4.0.1: warning: '-x assembler-with-cpp' after last input file has no effect
powerpc-apple-darwin8-gcc-4.0.1: no input files
powerpc-apple-darwin8-gcc-4.0 failed with exit code 1

• A: Short answer: click on the disclosure triangle next to the Targets group, then next to the target with the same name as your project, and then next to its "Compile Sources" phase. Remove any sources from that phase which are not actually used by your program.

Long answer: the projects work in two phases. First, FPC is used to compile all sources from Pascal to assembler code. Next, Xcode calls gcc to assemble the resulting files, links them together and builds the application bundle (Xcode refuses to link if we let FPC directly generates object code). If you remove a unit from the uses clause of your program, FPC will no longer compile this unit. Subsequently, there will be no assembler code for gcc to assemble, and Xcode will pass an "empty filename" to gcc, causing the error displayed above.

7. Contact information

For help with Mac Pascal programming (and generic Pascal programming):
  http://www.pascal-central.com/maillist.html

For FPC-specific questions (and help with generic Pascal programming):
  http://lists.freepascal.org/mailman/listinfo/fpc-pascal

Questions or remarks regarding the templates themselves can be sent to either list.

8. Version history

• 2.2.0 (28 August 2007):
	⁃	Run ranlib on the generated libfpc*.a libraries to avoid errors with certain versions of ld later on (and it is the correct thing to do)
	⁃	Project names now can contain spaces
	⁃	Added section with common questions (one for now)

• 2.1.4 (9 May 2007):
	⁃	First public release

• 2.1.2 (2 May 2007):
	⁃	New templates based on improved versions submitted by Erling Johansen:
	⁃	Cleaning no longer leaves stray caching information (with the downside that the main program file can no longer be auto-detected)
	⁃	Building is faster if there are a lot of files in the project (with the downside that unit search paths can no longer be auto-detected)
	⁃	Compilation and assembling  can no longer sometimes occur in parallel; this used to occasionally result in new builds not containing all latest changes
	⁃	Several new notes about Xcode problems when debugging Pascal programs
	⁃	Support in the templates for PowerPC64 and x86_64 (not yet in any released compiler, so compiling for either of these will not yet work)
	⁃	Notes about older project templates

• 2.0.4 (22 August 2006):
	⁃	Fixed problems with spaces in directory names when creating the fpcrtl.a library (thanks to Ingemar Ragnemalm for discovering this issue)
	⁃	Fixed encoding of English.lproj/InfoList.plist (set to UTF-16 now) (thanks to Dale Jensen for noting this)

• 2.0.4-rc3 (29 July 2006):
	⁃	Fixed creating a universal version of the fpcrtl target
	⁃	Exclude Free Vision when building the fpcrtl target because its "menus" unit conflicts with the menus unit of the Universal Interfaces (thanks to Dale Jensen for discovering both bugs)
	⁃	Note about the "menus" unit problem in the "Known problems" section
	⁃	Tested with Xcode 2.1

• 2.0.4-rc2 (19 July 2006):
	⁃	Ignore include files ending in .inc
	⁃	Print the full path name of files in error messages so Xcode can always find them
	⁃	Support for manually specifying the main program file (FPC_MAIN_FILE)

• 2.0.4-rc1 (9 July 2006):
	⁃	Completely rewritten version by Jonas Maebe for compatibility with newer Xcode versions

• 1.1 (23 May 2005)
	⁃	Initial public version by Dr. Rolf Jansen for Xcode 1.1