macOS Big Sur changes for developers: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(macOS only)
2	2
3	3		## User interface changes
4	4
5	5		macOS 11 Big Sur introduces many user interface changes that update the appearance of applications and make them more iOS-like. It also adds support for familiar iOS features — such as SF Symbols and text styles.
6	6
7	7		### Icons and Images
8	8
9	9		macOS 11 refreshes icon design throughout the system and also introduces multipurpose feature icons that can represent items or functions in sidebars and tables. It also adopts iOS SF Symbols. macOS 11 automatically maps AppKit shared images — such as Action, Unlocked, and Share — to specific symbols. In some cases, a symbol might not have the same size or alignment as the AppKit image it replaces, so check your layout.
10	10
11	11		![](/wiki-images/3/3e/SF_Symbols.png)
12	12
13	13		### Application icons
14	14
15	15		In macOS 11, application icons combine a rounded-rectangle shape, a front-facing perspective, and a consistent drop shadow.
16	16
17	17		![](/wiki-images/8/8e/MacOS11_app_icons1.png)
18	18
19	19		The new design does not preclude judicious expressiveness. For example, the Preview, Xcode, and TextEdit icons continue to combine depictions of the physical objects that best convey the applicationʼs core purpose, while incorporating the new shape, perspective, and shadow.
20	20
21	21		![](/wiki-images/f/f2/MacOS11_app_icons2.png)
22	22
23	23		### Document Icons
24	24
25	25		To compose a document icon, the system combines your application icon with the familiar folded-corner icon shape. If your application opens or creates a large number of document types, you can also supply a custom centre image or background appearance to help people distinguish them.
26	26
27	27		![](/wiki-images/c/c8/MacOS11_doc_icons.png)
28	28
29	29		### Feature Icons
30	30
31	31		A feature icon can represent an item (or category of items), a technology, or a type of information in a table view or in the content sidebar of a preferences window. A feature icon typically uses the macOS 11 rounded rectangle shape to contain a simple, unambiguous glyph, but it can also use custom shapes and colors. For help designing a feature icon, download the production template included in the [Apple Design Resources for macOS](https://developer.apple.com/design/resources/#macos-apps).
32	32
33	33		\| \| \|
34	34		\|----\|----\|
35	35		\| macOS 11 \| macOS 10.15 \|
36	36		\| ![](/wiki-images/a/ae/MacOS11_feature_icon.png) \| ![](/wiki-images/d/d5/MacOS10_feature_icon.png) \|
37	37
38	38		### Application Accent Colours
39	39
40	40		In macOS 11, you can specify an accent colour to customize the appearance of your applicationʼs buttons, selection highlighting, and sidebar glyphs. The system applies your accent colour when the current value in the user's General \> Accent colour preferences is multicolour.
41	41
42	42		If users set the Accent colour preferences to a value other than multicolour, the system applies their chosen colour to the relevant items throughout your application, replacing your accent colour. The exception is a sidebar glyph that uses a fixed colour you specify. Because a fixed-colour sidebar glyph uses a specific colour to provide meaning, the system does not override its colour when users change the value of Accent colour preferences. To learn more, see Sidebars.
43	43
44	44		The iCloud glyph remains teal, even when the other glyphs use orange.
45	45
46	46		![](/wiki-images/e/e1/IClould_glyph.png)
47	47
48	48		### Windows and Views
49	49
50	50		Throughout macOS 11, windows adopt visual cues from iOS interfaces. For example, windows integrate the sidebar, toolbar, and content areas, use an increased corner radius, and display lightweight controls.
51	51
52	52		![](/wiki-images/6/64/Macos11_window_view.png)
53	53
54	54		#### Toolbars and Title Bars
55	55
56	56		By default, toolbars are taller, window titles can display inline with controls, and toolbar items no longer include a bezel.
57	57
58	58		\| \| \|
59	59		\|----\|----\|
60	60		\| macOS 11 \| macOS 10.15 \|
61	61		\| ![](/wiki-images/1/13/MacOS11_tool-title_bar.png) \| ![](/wiki-images/b/bc/MacOS10_tool-title_bar.png) \|
62	62
63	63		To match the default toolbar’s increased height, toolbar items automatically use the large control size. The exception is an integrated toolbar-title bar area — such as the one in a Safari window — which continues to use the regular control size. To accommodate the new default size, you’ll probably need to adjust the layout of your toolbar.
64	64
65	65		\| \| \|
66	66		\|----\|----\|
67	67		\| macOS 11 \| macOS 10.15 \|
68	68		\| ![](/wiki-images/6/6f/MacOS11_tool_bar.png) \| ![](/wiki-images/e/ef/MacOS10_tool_bar.png) \|
69	69
70	70		Continuing to use the [minSize](https://developer.apple.com/documentation/appkit/nstoolbaritem/1531777-minsize) and [maxSize](https://developer.apple.com/documentation/appkit/nstoolbaritem/1526451-maxsize) APIs to set the size of a toolbar item can clip the control, because the current values don’t account for the larger default size. Use constraints if you need to specify minimum or maximum sizes for a toolbar control.
71	71
72	72		When horizontal space is limited, the toolbar can display the Search button in place of the search bar. When users click the Search button, the bar expands; when they click elsewhere in the window, the search bar collapses and the toolbar displays the button again.
73	73
74	74		![](/wiki-images/3/3d/MacOS11_toolbar_search.png)
75	75
76	76		In a preferences window, the toolbar can use SF Symbols, but the title position remains above the toolbar buttons. When needed for clarity, individual toolbar buttons can include colour. To indicate the active preference pane, the window applies a system-provided selection appearance to the selected toolbar button.
77	77
78	78		\| \| \|
79	79		\|----\|----\|
80	80		\| macOS 11 \| macOS 10.15 \|
81	81		\| ![](/wiki-images/1/1b/MacOS11_prefs_toolbar.png) \| ![](/wiki-images/e/ef/MacOS10_prefs_toolbar.png) \|
82	82
83	83		If your window includes multiple panes, you can align different subsets of toolbar items with each pane, so that as people resize the window, each set of items remains above its associated view.
84	84
85	85		#### Sidebars
86	86
87	87		In macOS 11, a sidebar extends to the full height of the window. Within the sidebar, default item spacing, row height, and glyph size all increase, and the selected-item highlight uses a rounded-corner appearance.
88	88
89	89		\| \| \|
90	90		\|----\|----\|
91	91		\| macOS 11 \| macOS 10.15 \|
92	92		\| ![](/wiki-images/e/e5/MacOS11_sidebar.png) \| ![](/wiki-images/6/6a/MacOS10_sidebar.png) \|
93	93
94	94		A sidebar’s row height, text, and glyph size depend on its overall size, which can be small, medium, or large. You can set the size programmatically, but users can also change it by selecting a different sidebar icon size in General preferences. The table below shows the differences in default sidebar metrics between macOS 11 and previous versions of macOS.
95	95
96	96		<thead>
97	97
98	98		</thead>
99	99		<tbody>
100	100
101	101		</tbody>
102	102
103	103		Using SF Symbols is the easiest way to create sidebar glyphs that use the new metrics. Alternatively, you can use PDF template images to create sidebar glyphs; if you must use bitmap images, be sure to create them in small, medium, and large sizes, at both @1x and @2x resolutions.
104	104
105	105		By default, sidebar glyphs use the current accent colour (to learn more, see Application Accent Colours). If you need to clarify the meaning of an individual sidebar glyph, you can give it a fixed color that persists regardless of the user’s Accent colour preferences. Don’t use the ability to specify a fixed colour to stylize your application as a whole. In macOS, people expect to see their chosen accent colour throughout all the applications they use.
106	106
107	107		#### Table Views
108	108
109	109		In macOS 11, table views are larger overall, using taller rows, a larger font size, and more space between items to increase visual separation within and around table content. macOS 11 introduces three table-view styles to define different appearances that work well in specific window areas: inset, full-width, and automatic. For developer guidance, see [NSTableView.style](https://developer.apple.com/documentation/appkit/nstableview/3622475-style).
110	110
111	111		The inset style adds insets to the expanded spaciousness of macOS 11 tables. Because the inset style increases the visual space around the content, it works well in tables that fill the area between other views — such as sidebars and toolbars — and echoes the changes in sidebar appearance.
112	112
113	113		![](/wiki-images/9/95/MacOS11_tableview_inset.png)
114	114
115	115		The classic, full-width table style remains available, but automatically includes the required content padding at the beginning and end of each row. The full-width style works best for tables that already have a visual margin around them, such as a table embedded in a preferences pane.
116	116
117	117		![](/wiki-images/a/a0/MacOS11_tableview_classic.png)
118	118
119	119		The automatic style means the system uses the table view’s position in the view hierarchy to help determine its appearance.
120	120
121	121		To create more spacious tables, macOS 11 uses several new table-view metrics. In the diagrams that follow, you can see how the layout of a table row differs between macOS 11 and macOS 10.15 and earlier.
122	122
123	123		\| \| \|
124	124		\|----\|----\|
125	125		\| macOS 11 \| macOS 10.15 \|
126	126		\| ![](/wiki-images/9/91/MacOS11_tableview_layout.png) \| ![](/wiki-images/7/7d/MacOS10_tableview_layout.png) \|
127	127
128	128		The following table lists the values for the table-row layout areas shown above.
129	129
130	130		\| Table-view metric \| macOS 11 \| macOS 10.15 and earlier \|
131	131		\|----\|----\|----\|
132	132		\| Recommended row height \| 24pt \| 17pt \|
133	133		\| Minimum row height for text-only rows \| 18pt \| 17pt \|
134	134		\| Inset at leading and trailing row edges \| 10pt (inset style); 0pt (other styles) \| – \|
135	135		\| Padding at leading and trailing row edges \| 6pt \| – \|
136	136		\| Intercell spacing \| (17,0) \| (3,2) \|
137	137		\| Text size (style) \| 13pt (Body) \| 11pt \|
138	138
139	139		In addition to the values listed in the table above, inset-style tables in macOS 11 also include a 10pt vertical inset before the first row and after the last row.
140	140
141	141		As you adjust the layout of your table content to follow the new metrics:
142	142
143	143		- Make sure your icons or glyphs can fit into a 16pt × 16pt area when you use the recommended 24pt row height
144	144		- Consider adding 6 points of space between items within a row to ensure a spacious table appearance
145	145		- If you don’t update your application, the appearance of your tables doesn’t change when your application runs in macOS 11. The exception is a table that implements a sidebar. If you identify the table style as a source list, the system automatically applies the new sidebar appearance. For guidance, see Sidebars; for developer guidance, see [NSTableView.style.sourceList](https://developer.apple.com/documentation/appkit/nstableview/style/sourcelist).
146	146
147	147		> Tip: TIP In macOS 11, a table's width continues to equal the width of its rows, but the new padding and insets prevent columns and cells from covering the entire row. The system also uses the specified style to determine the space to add to row background features, like selection appearance or alternating row colors. If you need to provide content that completely covers a row — such as a custom background appearance — add it to the row instead of the cells.
148	148
149	149		#### Sheets
150	150
151	151		Sheets no longer unfurl from the bottom edge of the parent window’s toolbar. In macOS 11, a sheet is a rounded rectangle view that floats on top of the dimmed parent window.
152	152
153	153		\| \| \|
154	154		\|----\|----\|
155	155		\| macOS 11 \| macOS 10.15 \|
156		-	~~\| ![](/wiki-images/6/6f/MacOS11_sheet.png) \| <img src="macOS10_sheet.png" title="macOS10_sheet.png" width="600" /> \|~~
	156	+	\| ![](/wiki-images/6/6f/MacOS11_sheet.png) \| ![](/wiki-images/8/8b/MacOS10_sheet.png) \|
157	157
158	158		#### Alerts
159	159
160	160		Alerts are cardlike rectangles that use the same corner radius as all windows in macOS 11. Within an alert, most content is center aligned.
161	161
162	162		![](/wiki-images/1/1f/MacOS11_alert.png)
163	163
164	164		You can also use red text to emphasize a destructive action in an alert.
165	165
166	166		![](/wiki-images/8/88/MacOS11_alert_red.png)
167	167
168	168		### Menus
169	169
170	170		macOS 11 introduces visual changes to menus and menu content. If you use standard menus and menu items, you get the following default appearances automatically:
171	171
172	172		- Menu item titles use the same 13-point font size as sidebars and window content areas.
173	173		- Menu separator lines are 1 point thick and inset from the sides.
174	174		- The selection highlight for a menu item is a rounded rectangle that’s inset from the edges of the menu.
175	175
176	176		\| \| \|
177	177		\|----\|----\|
178	178		\| macOS 11 \| macOS 10.15 \|
179	179		\| ![](/wiki-images/f/f7/MacOS11_menu.png) \| ![](/wiki-images/2/2b/MacOS10_menu.png) \|
180	180
181	181		### Controls
182	182
183	183		Refreshed AppKit controls — such as checkboxes, pop-up buttons, push buttons, and segmented controls — emphasize simplicity and boldness, similar to iOS controls while maintaining familiar appearances. When you use standard AppKit controls in your application, you shouldn’t have to adjust your interface to adopt the new appearances. The exception is the slider, which is taller.
184	184
185	185		\| Slider \| Size \| macOS 11 (default) \| macOS 10.15 and earlier (default) \|
186	186		\|----\|----\|----\|----\|
187	187		\| Without tick marks \| Regular \| 28pt \| 19pt \|
188	188		\| \| Small \| 20pt \| 15pt \|
189	189		\| \| Mini \| 17pt \| 13pt \|
190	190		\| With tick marks \| Regular \| 28pt \| 24pt \|
191	191		\| \| Small \| 20pt \| 18pt \|
192	192		\| \| Mini \| 17pt \| 15pt \|
193	193
194	194		<thead>
195	195
196	196		</thead>
197	197		<tbody>
198	198
199	199		</tbody>
200	200
201	201		<thead>
202	202
203	203		</thead>
204	204		<tbody>
205	205
206	206		</tbody>
207	207
208	208		Beginning in macOS 11, the track of a slider with tick marks aligns with the center of the thumb.
209	209
210	210		### Typography
211	211
212	212		Beginning in macOS 11, SF Pro is available as a variable font. The variable font format delivers a single package that includes the glyphs for all supported weights — such as regular, bold, and ultralight — in both uprights and italics. The variable format also supports optical sizing, which is a way to interpolate between glyphs to create size-specific versions of SF Pro to fit every design. Optical sizing replaces the need for the fixed-range Text and Display variants of SF Pro.
213	213
214	214		macOS 11 also introduces support for the full range of text styles, such as body, headline, and callout. Dynamic Type is not available in macOS 11. For guidance, see [Typography](https://developer.apple.com/design/human-interface-guidelines/macos/visual-design/typography/).
215	215
216	216		### Widgets
217	217
218	218		A widget elevates a small amount of useful content from your application. In macOS 11, you can create widgets in small, medium, and large sizes; people choose the size they want when they add your widget to Notification Center.
219	219
220	220		You can also create widgets for iOS and iPadOS. For guidance, see [Widgets](https://developer.apple.com/design/human-interface-guidelines/ios/system-capabilities/widgets/); for developer guidance, see [WidgetKit](https://developer.apple.com/documentation/widgetkit).
221	221
222	222		## Removed features
223	223
224	224		- Kernel extensions using certain KPIs deprecated in macOS 10.15 Catalina no longer load. Refer to the [Apple support page](https://developer.apple.com/support/kernel-extensions) for details.
225	225
226	226		## Deprecations
227	227
228	228		- The default initializer on the auto-generated model interface has been deprecated in favor of init(configuration:). Use init(configuration:) or the newly introduced .load() method and handle model load errors as appropriate. (macOS 11.0.1)
229	229
230	230		- The function hv_vcpu_run(_:) is deprecated. (macOS 11.0.1)
231	231
232	232		- The VNIdentifiedPointsObservation class is deprecated. Use VNRecognizedPointsObservation instances instead. (macOS 11.0.1)
233	233
234	234		- Support for the Developer Transition Kit is no longer available as of macOS Big Sur 11.3. (macOS 11.3)
235	235
236	236		- Don’t use the iOS MinimumOSVersion information property list key to declare the minimum release of macOS in which your app runs. Use LSMinimumSystemVersion instead. (macOS 11.3)
237	237
238	238		## New features
239	239
240	240		#### Security
241	241
242	242		macOS Big Sur 11 improves system security by requiring an administrator password when a certificate trust settings change is made in the admin trust domain. Running as the root user alone is no longer sufficient to modify certificate trust. User trust domain settings continue to require confirmation by entering the password for the user’s account. This change may affect you if one of the following is true:
243	243
244	244		- You have written scripts which call `/usr/bin/security add-trusted-cert -d ...` as root.
245	245		- Your process runs as root and calls the SecTrustSettingsSetTrustSettings function to trust a certificate.
246	246		- Workflows that add trust settings in the admin trust domain, such as for an enterprise root certificate, may require modification if the user can’t authenticate as an administrator at the time settings are changed.
247	247		- Workaround: Use Apple Configurator 2 to create and install a configuration profile containing your root certificate.
248	248
249	249		#### Kernel
250	250
251	251		- The `kern.argmax` limit has been increased, allowing programs to receive longer argument lists.
252	252		- Darwin `kevent` now allows non-parent processes to register for NOTE_EXITSTATUS, which delivers the same values as the `wait()` family of functions in the event data. Refer to the `wait4()` man page for more information. This event is subject to the following security checks:
253	253		- The requesting process is allowed to send signals by sandbox restrictions.
254	254		- The requesting process and the target process are running as the same user or the requesting process has root privileges.
255	255
256	256		#### Safari
257	257
258	258		- Support for Web Extensions is now available. Existing Chrome and Firefox extensions can be converted for Safari using xcrun safari-web-extension-converter and distributed through the App Store for use in Safari 14.
259	259
260	260		#### Time Machine
261	261
262	262		- APFS-formatted backup volumes are now supported for faster, more compact, and more reliable backups. New local and network Time Machine backup destinations are formatted as APFS by default. Time Machine will continue backing up to existing HFS backup volumes.
263	263
264	264		#### Virtualisation
265	265
266	266		- The Hypervisor framework now requires the com.apple.security.hypervisor entitlement.
267	267		- A new Virtualization framework provides high-level APIs to run Linux in a virtual machine.
268	268
269	269		#### Built-in dynamic linker cache
270	270
271	271		New in macOS Big Sur 11, the system ships with a built-in dynamic linker cache of all system-provided libraries. As part of this change, copies of dynamic libraries are no longer present on the filesystem. Code that attempts to check for dynamic library presence by looking for a file at a path or enumerating a directory will fail. Instead, check for library presence by attempting to dlopen() the path, which will correctly check for the library in the cache.
272	272
273	273		As the libraries are no longer present on the filesystem, it makes it difficult to disassemble them! Fortunately, there are ways to extract the system libraries from the cache. One way is provided by Apple itself: the `dyld_shared_cache_util` tool command-line tool. Unfortunately, this tool does not come installed with macOS Big Sur. However, the tool is open source - see [dyld_shared_cache_util](https://opensource.apple.com/source/dyld/dyld-519.2.1/launch-cache/) and for the "fixed to compile as is" Xcode project source see [dyld-shared-cache-big-sur](https://github.com/antons/dyld-shared-cache-big-sur).
274	274
275	275		### Other differences: Intel vs aarch64
276	276
277	277		- Timing: Any code which uses Mach Absolute time when run in Rosetta translation is given Mach ticks equivalent to one every nanosecond as happens on an Intel processor; whereas aarch64 native Mach ticks are incremented every 41.67 nanoseconds instead.
278	278
279	279		## ARM64/AArch64/Apple Silicon Support
280	280
281	281		macOS 11 Big Sur is the first macOS version that supports Apple's AArch64 processors on the desktop. FPC trunk supports targeting this platform.
282	282
283	283		The following instructions assume that you are working on an AArch64 Mac, that you have already installed FPC 3.2.2 for Intel, and that the Xcode.app bundle is located in the /Applications folder. You can place it elsewhere and adjust the paths accordingly so long as there are no spaces in the path.
284	284
285	285		> Note: If you have only installed the standalone Command Line Tools and not the full Xcode package, you will need to replace `/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin`` with ``/Library/Developer/CommandLineTools/usr/bin` and `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk`` with ``/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk`
286	286
287	287		1. Compile a native AArch64 compiler from the FPC trunk source
288	288		:
289	289
290	290		make distclean make FPC=ppcx64 OPT="-ap -FD/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin -XR/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" CPU_TARGET=aarch64 -j 4 FPMAKEOPT="-T 4" all \> build.log
291	291
292	292		1. Copy the created native compiler to a safe place (the delete + copy is to avoid issues with a code signature caching bug in the OS - see [[Code Signing for macOS\|Updating a signed file]] for an explanation)
293	293		:
294	294
295	295		rm -f ppca64 ; cp compiler/ppca64 .
296	296
297	297		1. Build a complete native FPC distribution for Darwin/AArch64
298	298		:
299	299
300	300		make distclean make FPC=\$PWD/ppca64 OPT="-ap -FD/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin -XR/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" -j 4 FPMAKEOPT="-T 4" OVERRIDEVERSIONCHECK=1 all \> build.log
301	301
302	302		1. Install the built toolchain globally (under /usr/local)
303	303		:
304	304
305	305		sudo make FPC=\$PWD/ppca64 OPT="-ap -FD/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin -XR/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" install
306	306
307	307		1. Enable the fpc binary to find the AArch64 compiler (ppca64). You only need to do this once, even if you build/install newer build later on (unless the version number of trunk would change)
308	308		:
309	309
310	310		sudo ln -sf /usr/local/lib/fpc/3.3.1/ppca64 /usr/local/bin
311	311
312	312		1. Create a file called ".fpc.cfg" (note the starting ".") in your home directory with the following contents
313	313		:
314	314		2. include /etc/fpc.cfg
315	315
316	316		-FD/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin -XR/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
317	317
318	318		Now you can use either fpc or ppca64 to compile AArch64 programs.
319	319
320	320		> Warning: When you wish to build a newer version later on, make sure to restart at step 1. As always, compiling the trunk sources is only supported when you start with one of the latest two FPC releases, or with a compiler built from the same trunk sources. Starting with a trunk compiler built using previous trunk sources is not and never will be supported.
321	321
322	322		## Creating a universal binary for aarch64 and x86_64
323	323
324	324		### FPC applications
325	325
326	326		Open a Terminal and use the following commands:
327	327
328	328		``` bash
329	329		fpc my_app.pas -omy_app_ARM64 -Paarch64
330	330		fpc my_app.pas -omy_app_X8664 -Px86_64
331	331		lipo -create -output my_app my_app_ARM64 my_app_X8664
332	332		strip my_app
333	333		```
334	334
335	335		You can check that you have created a universal binary with this command:
336	336
337	337		``` bash
338	338		file my_app
339	339		```
340	340
341	341		which should produce output similar to this:
342	342
343	343		```text
344	344		my_app: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64]
345	345		my_app (for architecture x86_64): Mach-O 64-bit executable x86_64
346	346		my_app (for architecture arm64): Mach-O 64-bit executable arm64
347	347		```
348	348
349	349		### Lazarus applications
350	350
351	351		- Go to Lazarus Menu, Project \> Project Options \> Compiler Options - Config and target
352	352		- Select Target CPU family "aarch64"
353	353		- Go to Lazarus Menu, Project \> Project Options \> Compiler Options - Paths - Target filename
354	354		- Rename my_app to my_app_ARM64
355	355		- Compile
356	356
357	357		- Go to Lazarus Menu, Project \> Project Options \> Compiler Options - Config and target
358	358		- Select Target CPU family "x86_64"
359	359		- Go to Lazarus Menu, Project \> Project Options \> Compiler Options - Paths - Target filename
360	360		- Rename my_app to my_app_X8664
361	361		- Compile
362	362
363	363		- Open a Terminal and execute the following commands in your my_app directory:
364	364
365	365		``` bash
366	366		lipo -create -output my_app my_app_ARM64 my_app_X8664
367	367		strip my_app
368	368		```
369	369
370	370		You now have a universal binary with which to replace the symbolic link in your final [[Application Bundle\|application bundle's]] MacOS directory. You can check that you have created a universal binary with this command:
371	371
372	372		``` bash
373	373		file my_app
374	374		```
375	375
376	376		which should produce output similar to this:
377	377
378	378		```text
379	379		my_app: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64]
380	380		my_app (for architecture x86_64): Mach-O 64-bit executable x86_64
381	381		my_app (for architecture arm64): Mach-O 64-bit executable arm64
382	382		```
383	383
384	384		### Removing duplicate resources in universal binaries
385	385
386	386		When creating universal binaries any resources will be duplicated in each executable which increases the file size of the universal binaries, sometimes quite substantially depending on the size of the resources.
387	387
388	388		The Free Pascal Compiler supports loading external resources on Darwin using the -We command line option. For usage examples, see:
389	389
390	390		- <https://gitlab.com/freepascal.org/fpc/source/-/blob/main/tests/test/units/system/tresext.pp> and
391	391		- <https://gitlab.com/freepascal.org/fpc/source/-/blob/main/tests/test/units/system/tres2ext.pp>
392	392
393	393		## Code signing - Intel vs M1
394	394
395	395		On Intel systems running Big Sur very little is required to be signed except for kernel and system extensions and related code which require special approval from Apple.
396	396
397	397		The situation is different on M1 Apple Silicon (aarch64) systems running Big Sur. There are a few situations to consider:
398	398
399	399		- Intel code running under Rosetta 2 - this does not need to be signed for practical reasons (ie the code is translated into aarch64 code for the M1 and so any signature for the Intel code would of course be invalid when applied to the aarch64 code).
400	400
401	401		- Native M1 aarch64 code will be blocked from execution unless a valid signature is attached. This signature can be as simple as an ad hoc code signature that doesn’t bear any actual identity from the secret half of an asymmetric key pair (it’s simply an unauthenticated measurement of the binary). The reason for this requirement is not to enable conventional code signature checks, but so that the executable code has a cdhash (code directory hash), which is used when macOS checks code before running it to verify that the contents of a binary have not changed since being code signed. If you don’t have an Apple developer signing certificate, an ad-hoc certificate generated on your Mac is quite sufficient. For those without developer accounts, [[Xcode]] now defaults to applying ad-hoc signing to its projects. As there is no requirement for an identity, and therefore any certificate to prove that identity, anyone can sign an application to run locally.
402	402
403	403		- Universal binaries that include both Intel code and native M1 aarch64 code will be blocked from execution unless a valid signature is attached.
404	404
405	405		Checking the status of code signing for FPC and/or FPC and Lazarus native code executables shows:
406	406
407	407		`$ codesign -dv -r- ./program`\
408	408		`Executable=/Users/trev/Documents/fpc_adhoc_test/program`\
409	409		`Identifier=program`\
410	410		`Format=Mach-O thin (arm64)`\
411	411		`CodeDirectory v=20400 size=3392 flags=0x20002(adhoc,linker-signed) hashes=103+0 location=embedded`\
412	412		`Signature=adhoc`\
413	413		`Info.plist=not bound`\
414	414		`TeamIdentifier=not set`\
415	415		`Sealed Resources=none`\
416	416		`# designated => cdhash H"6d17593d42b7b10d8af344197c48df47beda2779"`
417	417
418	418		`$ codesign -dv -r- DemoDownload.app`\
419	419		`Executable=/Users/trev/Documents/laz_resume_dload/DemoDownload.app/Contents/MacOS/DemoDownload`\
420	420		`Identifier=DemoDownload`\
421	421		`Format=app bundle with Mach-O thin (arm64)`\
422	422		`CodeDirectory v=20400 size=110533 flags=0x20002(adhoc,linker-signed) hashes=3451+0 location=embedded`\
423	423		`Signature=adhoc`\
424	424		`Info.plist=not bound`\
425	425		`TeamIdentifier=not set`\
426	426		`Sealed Resources=none`\
427	427		`# designated => cdhash H"bb0a310c980906bd6320deaabc72f543dc725bbb"`
428	428
429	429		So, it appears that the macOS linker is doing the ad hoc code signing for us and generating the all-important cdhash.
430	430
431	431		What happens if you edit the executable with the cdhash (I changed a single occurrence of Assertion to ASsertion) ?
432	432
433	433		` $ ./program `\
434	434		` Killed`
435	435
436	436		and:
437	437
438	438		Process: DemoDownload [7888]
439	439		Path: /Users/USER/Documents/*/DemoDownload.app/Contents/MacOS/DemoDownload
440	440		Identifier: com.company.DemoDownload
441	441		Version: 0.1 (1)
442	442		Code Type: ARM-64 (Native)
443	443		Parent Process: ??? [1]
444	444		Responsible: DemoDownload [7888]
445	445		User ID: 501
446	446
447	447		Date/Time: 2021-03-14 15:52:46.806 +1100
448	448		OS Version: macOS 11.2.3 (20D91)
449	449		Report Version: 12
450	450		Anonymous UUID: FDB6D79D-592D-3959-8F4F-9EC29A74836C
451	451
452	452		Time Awake Since Boot: 5300 seconds
453	453
454	454		System Integrity Protection: enabled
455	455
456	456		Crashed Thread: 0 Dispatch queue: com.apple.main-thread
457	457
458	458		Exception Type: EXC_BAD_ACCESS (Code Signature Invalid)
459	459		Exception Codes: 0x0000000000000032, 0x00000001023bd758
460	460		Exception Note: EXC_CORPSE_NOTIFY
461	461
462	462		Termination Reason: Namespace CODESIGNING, Code 0x2
463	463
464	464		Beware if you use a workflow involving tools that modify a binary after linking (eg strip or install_name_tool). In these situations you will almost certainly need to manually use codesign as an additional build phase to properly ad-hoc sign your binary.
465	465
466	466		### What does this mean for natively compiled FPC and Lazarus aarch64 binaries?
467	467
468	468		If you deploy:
469	469
470	470		1\) an unsigned binary to your endusers, they will NOT be able to execute the binary on an M1 Apple Silicon computer. Note, however, that if the binary was linked on an M1 Apple Silicon computer, the macOS linker will have ad hoc signed the binary for you.
471	471
472	472		2\) an ad hoc signed binary to your endusers, they will be able to execute the binaries on an M1 Apple Silicon computer. This is because these new signatures are not bound to the specific machine that was used to build the executable; they can be verified on any other system and will be sufficient to comply with the new default code signing requirement on Macs with Apple silicon. However, given that these signatures do not bear any valid identity, binaries signed this way cannot pass Gatekeeper.
473	473
474	474		For manual ad hoc code signing of an application bundle (note that a dash is using for the signing identity after the -s argument):
475	475
476	476		`codesign --force --deep -s - MyApp.app`
477	477
478	478		Also note that you cannot sign an application bundle where the executable is a symlink (eg an application compiled with Lazarus) unless you replace the symlink with the linked executable.
479	479
480	480		For manual ad hoc signing of a command line utility:
481	481
482	482		`codesign --force -s - MyExe`
483	483
484	484		### Code signing an x86_64 binary on an aarch64 machine
485	485
486	486		## Apple Big Sur "New Look" external links
487	487
488	488		- [WWDC2020 - New look macOS](https://developer.apple.com/videos/play/wwdc2020/10104/)
489	489		- [WWDC2019 - Introducing SF Symbols](https://developer.apple.com/videos/play/wwdc2019/206)
490	490		- [WWDC2020 - SF Symbols 2](https://developer.apple.com/videos/play/wwdc2020/10207)
491	491
492	492		## Apple Silicon external links
493	493
494	494		- [Apple: Porting Your macOS Apps to Apple Silicon](https://developer.apple.com/documentation/xcode/porting_your_macos_apps_to_apple_silicon)
495	495		- [Apple: Building a Universal macOS Binary](https://developer.apple.com/documentation/xcode/building_a_universal_macos_binary)
496	496		- [Apple: Addressing Architectural Differences in Your macOS Code](https://developer.apple.com/documentation/apple_silicon/addressing_architectural_differences_in_your_macos_code)
497	497		- [Apple: Porting Your Audio Code to Apple Silicon](https://developer.apple.com/documentation/audiounit/porting_your_audio_code_to_apple_silicon)
498	498		- [Apple: Porting Your Metal Code to Apple Silicon](https://developer.apple.com/documentation/metal/porting_your_metal_code_to_apple_silicon)
499	499		- [Apple: Installing a Custom Kernel Extension](https://developer.apple.com/documentation/apple_silicon/installing_a_custom_kernel_extension)
500	500		- [Apple: Debugging a Custom Kernel Extension](https://developer.apple.com/documentation/apple_silicon/debugging_a_custom_kernel_extension)
501	501		- [Apple: Platform Security Guide](https://support.apple.com/en-au/guide/security/welcome/web).
502	502		- [Apple: Code signing x86_64 binaries on aarch64](https://developer.apple.com/forums/thread/673323).
503	503
504	504		## Big Sur Release Notes
505	505
506	506		- [Apple: macOS Release Notes](https://developer.apple.com/documentation/macos-release-notes/).
507	507
508	508		---
509	509		From the Free Pascal wiki, page "macOS Big Sur changes for developers", as it stood on 2022-05-08 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
510	510		Category: FPC
511	511		Category: Install
512	512		Category: Lazarus
513	513		Category: Platform-sensitive development
514	514		Category: macOS

Back to history