Xcode

Building Unix/Linux Applications with Xcode

These instructions relate to using Xcode version 26.2 (17C52). It describes how you can use Xcode as an IDE for Unix/Linux C/C++ projects that have a Makefile.

Xcode can also be used for integrated debugging, but the code must be compiled with debug symbols otherwise Xcode debugging appears not to work, with no error messages or other help. Debugging is often easier if optimisations have also been disabled, by passing -O0 (capital letter O followed by zero) to the linker. E.g. typically for C++, passing the -g (Generate source-level debug information) and -O0 to Clang g++ is achieved by setting CXXFLAGS when running GNU ./configure, e.g.

./configure CXXFLAGS='-g -O0'

It may be easier to use the LLDB debugger (which is used by Xcode) from the command line to troubleshoot any issues with debugging. Once it works from the command line, it should work within Xcode. Some notes for quickly getting started with LLDB are in another section below.

  1. After launching Xcode, choose the option to create a new project, or select File > New > Project from the menu.

  2. Choose the External Build System template from the Other tab.

  3. Enter a product name.

  4. Select the build tool as /usr/bin/make.

  5. Click Finish.

  6. Select the folder under which the new project will be created with a folder name largely matching the provided project name and created the project.

  7. The project is created with a default target and probably a default source code file.

  8. Use Finder to drag the folder containing the sources to the source folder of the project. Xcode will automatically prompt to Choose options for adding these files. Choose an Action of Reference files in place and chose Groups as Create groups. Check the target box.

  9. You can remove the references to any irrelevant files, e.g. the Makefile.

  10. Select the newly created target.

  11. On the Info tab, select the directory containing the original source code's Makefile.

  12. Leave Pass build settings in environment selected.

  13. If necessary, on the Build Settings tab, add a PATH variable to include any binaries required to complete the build, e.g.

    PATH       :/opt/local/bin

    Note: This value is appended to system's path without a path separator, so it needs to start with a path separator. The path can be set for the entire project or just the target.

  14. Once you have built the application with Product > Build, edit the scheme, select Run Debug then the Info tab and change the value of Executable to the location of the recently built executable by selecting the Other… option.

  15. On the Arguments tab of the scheme editor, add any arguments the application needs on launch.

  16. Run the application from Xcode menu with Product > Run.

The Product > Clean Build Folder… option does not run the clean target of the Makefile. It seems you have to duplicate the target and specify on the Info tab of the new target an argument of clean replacing the $(ACTION) variable. Then create a new scheme (Product > Scheme > New Scheme…) setting it's target as the newly created target. Although one would have thought there was a way of passing different targets to the make file via the ACTION variable, it eluded me.

Minimum Deployment Issue

After building the application, it failed to execute displaying the following error:

MacBook Air runs macOS 15.7.3, which is lower than myapp’s minimum
deployment target of 26.2. Change your project’s minimum deployment target or
upgrade MacBook Air’s version of macOS.

The MACOSX_DEPLOYMENT_TARGET value needs to be manually added as a User Defined Setting within the project's Build Settings by clicking the plus sign on the list.

make clean && make allowed the application to run.

Debugging from the Command Line with LLDB

Launching the debugger

$ lldb $TARGET -- $ARGS

where $TARGET is the executable to be debugged and optionally, $ARGS are arguments to pass to the executable.

alternatively:

$ lldb
(lldb) file $TARGET
(lldb) process launch -- $ARGS

Commands Quick Reference

(lldb) breakpoint set --name main
(lldb) breakpoint set --file main.cpp --line 42
(lldb) b main.cpp:42
(lldb) breakpoint list
(lldb) br l
(lldb) breakpoint delete 1
(lldb) br del 1
(lldb) display foo
(lldb) undisplay foo
(lldb) help source list
(lldb) help bt
(lldb) bt
(lldb) break write --file breakpoints.json
(lldb) break delete
(lldb) break read --file breakpoints.json
(lldb) history
(lldb) source list --count 9 --line 42
(lldb) frame info

Wait for Remote Process

(lldb) process attach --name ${PROCESS_NAME} --waitfor

Troubleshooting

Supported versions of macOS and Xcode versions

Resources

-- Frank Dean - 26 May 2024

Related Topics: InstallingMacPorts, MacOSXOpenJDK, MacOSXTips, iOSDevelopment, watchOSDevelopment