ProjectXC

Contents

Introduction

ProjectXC currently includes several templates for creating Xcode projects:

• osx-simple - an Objective Pascal project for OS X that uses native Cocoa user interface controls

• osx-simple-new - a derivative of osx-simple that supports only 64-bit and macOS 10.10 or later; projects require framework units from here; recommended for most projects

• osx-laz - a Pascal project for debugging a Lazarus app in Xcode

Setting Up

1. Free Pascal compiler

   Install version 3.0.0 or later.

   freepascal.org

2. ProjectXC source code

   projectxc-src.zip

3. Compile makeproj command line program

   Tip: If you're only interested in Lazarus integration, you can skip this step.

   In a Terminal window:

   fpc makeproj

   To view the makeproj syntax, run it without any parameters:

   ./makeproj

4. Install ExportToXcode package in Lazarus (optional)

   In Lazarus, choose Package | Open Package File and select exporttoxcode.lpk in the ProjectXC lazide folder.

   Click Compile, then click Use | Install.

   Once Lazarus has been rebuilt and restarted, you can use the Export to Xcode command on the Tools menu.

Creating an Xcode Objective Pascal Project

./makeproj osx-simple ~/MyXcodeProjects/test1

Change ~/MyXcodeProjects to point to an existing folder where you want the test1 project folder to be created.

Now open test1.xcodeproj in Xcode and choose Product | Run to compile and run it.

Adding the UI (Outlets and Actions) to an Objective Pascal App

1. Simple, not document-based
2. Uses a storyboard for UI design, not a xib file
3. Does not use Core Data
4. Includes "dummy" Objective C files that are only used for designing the user interface.

• In Xcode, expand your new project's folders in the Navigator panel on the left.
• Select Main.storyboard to open the UI in its designer.
• Select the View Controller's View.
• Drag and drop a button on the View.

• To access the button's properties in code, you'll need to add an outlet for it, as follows:
• Click the button in the upper right to show the Assistant editor so you can edit two files at once.
• In the right editor, select ViewController.h from the menu at the top.
• Make sure the View's button is selected and not its inner NSButtonCell. If in doubt, click the Quick help button (question mark) at the top of the Utilities panel on the right. Make sure it shows NSButton.
• Click the Connections button at the top of the Utilities panel.
• Click the New Referencing Outlet's button and drag and drop it to where indicated in ViewController.h. When prompted, enter button.

• To respond to the button's click event in code, you'll need to add an action for it, as follows:
• Click the Sent Actions action's button and drag and drop it to where indicated in ViewController.h. When prompted, enter buttonClick.
• Now add the equivalent Pascal code to ViewControllerU.pas. Tip: Copy the commented Pascal code in ViewController.h and paste it where indicated in ViewControllerU.pas, removing the "//". Your code should look something like the screenshot below.

• Choose Product | Run, then click the button to change its title to Clicked!.

Xcode Tips

1. Debugging in Xcode. See this link.

2. Pascal syntax highlighting. See this link.

3. Objective Pascal helper units. See this download.

Creating an Xcode Project for a Lazarus Project

Before You Start

1. Make sure you've set your Lazarus project's target file name. Enter this on the Project | Project Options | Paths tab in Lazarus.

   Tip: Lazarus also uses this to name your app's .app bundle. In general, the target name should be in mixed-case, NOT lower-case.

2. If you want Xcode to be able to jump to syntax errors in your Pascal code, enter the -vbr switch on the Project | Project Options | Custom Options tab in Lazarus. This switch causes the Free Pascal compiler to output all error messages in a standard format (Rhide/GCC) that Xcode understands.

   Note: Unfortunately, Lazarus itself does not understand messages in this standard format, so you'll probably want to remove this switch when you're compiling your project in Lazarus.

3. Compile your Lazarus project successfully at least once so that Lazarus creates your app's .app bundle and its Info.plist file.

4. If you want Xcode to be able to display your Pascal source using syntax highlighting, follow the instructions here.

Create the Xcode Project

1. With makeproj, run makeproj in a Terminal window, specifying the template to use, the Xcode project to create, and the Lazarus project info file to base it on. For example:

   ./makeproj osx-laz ~/MyXcodeProjects/test2 ~/MyLazProjects/test2/test2.lpi

2. With Lazarus, choose Tools | Export to Xcode. By default, the Xcode Project Name box will be filled in with your Lazarus project's target file name. Edit this if you want, then choose an existing folder where the Xcode project folder will be created. Finally, click the Export button.

• A ReadMe.txt file. Review this the first time you create an Xcode project.

• A dummy "C" file (main.c). You can ignore this file. It's just used so that Xcode creates a complete .app bundle so we don't have to.

• A reference to your Lazarus .app bundle's Info.plist file. This file serves as the "master" Info.plist file for both projects. You can edit it here by clicking on it or in Xcode's Info tab.

• References to your Lazarus project's Pascal source files. The files themselves were not added to the Xcode project, just references to your Lazarus project's files (so you don't have duplicate files). You can view and edit these files in Xcode; changes you make in Xcode will be reflected in Lazarus.

FAQs: Using Xcode with your Lazarus Project

1. How does this work?

   Like most IDEs, Xcode runs a series of command line tools when it builds a project. The osx-laz template includes a build script that runs the Lazarus lazbuild console app to do the actual compiling of your Lazarus project. If the Free Pascal compiler that lazbuild runs detects a syntax error in your code, Xcode will jump to the line where the error occurred, assuming you added the -vbr switch to your Lazarus project as described above.

   The rest of the build process is standard Xcode, for example creating the .app bundle (under ~/Library/Developer/Xcode/DerivedData) and signing the app (with codesign).

2. What version of Xcode do I need?

   ProjectXC was tested with Xcode 8.2.1, Lazarus 1.8.0 RC1 and Free Pascal 3.0.2 on El Capitan (OS X 10.11).

3. Does Xcode modify my Lazarus project?

   Except for edits that you might make to your Pascal source files or Info.plist file, Xcode won't make changes to your Lazarus project files.

4. Can I debug my Lazarus app in Xcode?

   Yes, you can set breakpoints the same way you would in any Xcode project. For more information, see this link.

5. How do I use my Lazarus project's build modes in Xcode?

   Lazarus build modes correspond roughly to Xcode schemes. For example, if you have a Debug build mode and a Release build mode in your Lazarus project, you can try this:

   • In Xcode, go to Product | Schemes | Manage Schemes and rename the default scheme to Debug, then add a new scheme and name it Release, setting its Build Configuration to Release.
   • Scroll to the bottom of Xcode's Release Settings tab and enter this under LAZBUILD_OPTIONS for Debug:
     --build-mode=Debug
     And this under LAZBUILD_OPTIONS for Release:
     --build-mode=Release

   Now when you select the Debug scheme and build your Xcode project, it will run lazbuild with the Debug build mode. When you select the Release scheme and build your Xcode project, it will run lazbuild with the Release build mode.

6. Can I switch LCL widgetsets in Xcode?

   Yes, specify the widgetset to use in the LAZBUILD_OPTIONS setting. For example, to build your Lazarus project with the Cocoa widgetset, enter this:

   --widgetset=cocoa

   To build a 64-bit Cocoa app, add these switches as well to LAZBUILD_OPTIONS:

   --compiler=/usr/local/bin/ppcx64 --cpu=x86_64

   You can also use a different lazbuild than the one installed with Lazarus. Just change the LAZBUILD_PATH setting. If you have more than one installation of Lazarus, you can also specify a different configuration path to use in the LAZBUILD_OPTIONS, for example:

   --pcp=~/.lazarus-svn

7. Can Xcode sign my Lazarus app?

   Yes, enable signing on the General tab the same as any Xcode project.

8. Can I compile my Xcode project from the command line?

   Yes, use xcodebuild the same as with any Xcode project.

9. Can I have my projects open in Lazarus and Xcode simultaneously?

   Yes, in general you should be able to do that.

   Note that when you save edits in Lazarus, Xcode will immediately update the code in its editor. Lazarus isn't quite that smart, but it will prompt you to reload the modified file when you save edits in Xcode.

10. Will this improve my app's user interface, make it more Mac-like?

    No, if you want that, create a project with the Objective Pascal template above. You won't use Lazarus at all in that case. You can use non-UI units from a Lazarus project, but none of its form design files or form code units.

11. How do I fix my app's lower-case app menu name?

    This is caused by Lazarus not setting the Info.plist's CFBundleName correctly.

    Example 1: You have a Lazarus project myapp.lpi whose target file name is "My App" and you create the Xcode project like this:

    ./makeproj osx-laz "~/MyXcodeProjects/My App" ~/MyLazProjects/myapp/myapp.lpi

    Both Lazarus and Xcode will use the correct mixed-case name for the .app bundle and executable file, but the app menu will be lower-case. To fix, edit the Bundle name in Xcode's Info panel.

    Example 2: You used the same name for the Xcode project as the Lazarus project:

    ./makeproj osx-laz ~/MyXcodeProjects/myapp ~/MyLazProjects/myapp/myapp.lpi

    By default Xcode will use the project name for the .app bundle and executable file, so in addition to the fix in example 1, change the Xcode project's target from "myapp" to "My App".

12. What if I need to delete the Xcode project?

    Your Lazarus project won't be affected.

    Note that if you added files to the Xcode project (not just references) or enabled things that only Xcode can do (for example, copy files to the .app bundle's Resources folder when building the app), you will lose these changes.

13. Can I move the Xcode project folder?

    Yes, the Xcode project uses absolute paths to the Lazarus project's files.

14. Can I move the Lazarus project folder?

    Yes, but with consequences. The Xcode project uses absolute paths to the Lazarus project's files. You will lose the ability to view and edit the Info.plist and Pascal source files in Xcode, although you can still build once you've updated the LAZ_PROJECT_DIR setting in Xcode's Build settings.

    If possible, delete the Xcode project (see question above), move the Lazarus project, then create the Xcode project again.

macpgmr (at) icloud (dot) com

First posted Oct. 25, 2015; last edited July 29, 2017.