Documenting possible LTO errors and making it easier to fix them in a FetchContent project (#422)

Build/CMakeLists.txt

@@ -14,7 +14,9 @@ option(CROSS_PLATFORM_DETERMINISTIC "Cross platform deterministic" OFF)
 # When turning this option on, the library will be compiled for ARM (aarch64-linux-gnu), requires compiling with clang
 option(CROSS_COMPILE_ARM "Cross compile to aarch64-linux-gnu" OFF)
 
-# When turning this option on, the library will be compiled with interprocedural optimizations enabled, also known as link-time optimizations or link-time code generation
+# When turning this option on, the library will be compiled with interprocedural optimizations enabled, also known as link-time optimizations or link-time code generation.
+# Note that if you turn this on you need to use SET_INTERPROCEDURAL_OPTIMIZATION() or set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON) to enable LTO specificly for your own project as well.
+# If you don't do this you may get an error: /usr/bin/ld: libJolt.a: error adding symbols: file format not recognized
 option(INTERPROCEDURAL_OPTIMIZATION "Enable interprocedural optimizations" ON)
 
 # When turning this on, in Debug and Release mode, the library will emit extra code to ensure that the 4th component of a 3-vector is kept the same as the 3rd component 
@@ -143,24 +145,28 @@ elseif ("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux" OR "${CMAKE_SYSTEM_NAME}" STREQU
 	set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -pthread")
 endif()
 
-set(CMAKE_INTERPROCEDURAL_OPTIMIZATION_RELEASE OFF)
-set(CMAKE_INTERPROCEDURAL_OPTIMIZATION_DISTRIBUTION OFF)
+# Set linker flags
+set(CMAKE_EXE_LINKER_FLAGS_DISTRIBUTION "${CMAKE_EXE_LINKER_FLAGS_RELEASE}")
 
-# On ARM, whole program optimization triggers an internal compiler error during code gen, so we don't turn it on
-if (INTERPROCEDURAL_OPTIMIZATION AND NOT ("${CMAKE_VS_PLATFORM_NAME}" STREQUAL "ARM64") AND NOT ("${CMAKE_VS_PLATFORM_NAME}" STREQUAL "ARM"))
-	include(CheckIPOSupported)
-	check_ipo_supported(RESULT IS_IPO_SUPPORTED OUTPUT IPO_CHECK_OUTPUT)
+# Enable link time optimization in Release and Distribution mode if requested and available
+function(SET_INTERPROCEDURAL_OPTIMIZATION)
+	set(CMAKE_INTERPROCEDURAL_OPTIMIZATION_RELEASE OFF PARENT_SCOPE)
+	set(CMAKE_INTERPROCEDURAL_OPTIMIZATION_DISTRIBUTION OFF PARENT_SCOPE)
 
-	if (IS_IPO_SUPPORTED)
-		set(CMAKE_INTERPROCEDURAL_OPTIMIZATION_RELEASE ON)
-		set(CMAKE_INTERPROCEDURAL_OPTIMIZATION_DISTRIBUTION ON)
-	else()
-		message(WARNING "Interprocedural optimizations are not supported: ${IPO_CHECK_OUTPUT}")
-	endif()
-endif()
+	# On ARM, whole program optimization triggers an internal compiler error during code gen, so we don't turn it on
+	if (INTERPROCEDURAL_OPTIMIZATION AND NOT ("${CMAKE_VS_PLATFORM_NAME}" STREQUAL "ARM64") AND NOT ("${CMAKE_VS_PLATFORM_NAME}" STREQUAL "ARM"))
+		include(CheckIPOSupported)
+		check_ipo_supported(RESULT IS_IPO_SUPPORTED OUTPUT IPO_CHECK_OUTPUT)
 
-# Set linker flags
-set(CMAKE_EXE_LINKER_FLAGS_DISTRIBUTION "${CMAKE_EXE_LINKER_FLAGS_RELEASE}")
+		if (IS_IPO_SUPPORTED)
+			set(CMAKE_INTERPROCEDURAL_OPTIMIZATION_RELEASE ON PARENT_SCOPE)
+			set(CMAKE_INTERPROCEDURAL_OPTIMIZATION_DISTRIBUTION ON PARENT_SCOPE)
+		else()
+			message(WARNING "Interprocedural optimizations are not supported: ${IPO_CHECK_OUTPUT}")
+		endif()
+	endif()
+endfunction()
+SET_INTERPROCEDURAL_OPTIMIZATION()
 
 # Set repository root
 set(PHYSICS_REPO_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/../)

Build/README.md

@@ -137,6 +137,16 @@ Note that you can also follow the steps in the 'Linux' section if you wish to bu
 - This will open XCode with a newly generated project
 - Build and run the project (note that this will only work in the simulator as the code signing information is not set up)
 
+## Link Errors
+
+If you receive the following error when linking:
+
+```
+/usr/bin/ld: libJolt.a: error adding symbols: file format not recognized
+```
+
+Then you have not enabled interprocedural optimizations (link time optimizations) for your own application. See the INTERPROCEDURAL_OPTIMIZATION option in CMakeLists.txt.
+
 ## Doxygen on Windows
 
 Documentation can be generated through doxygen: