macOS Big Sur changes for developers: what changed

Revision 3 to 4. 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		-	~~<thead>~~
97		-
98		-	~~</thead>~~
99		-	~~<tbody>~~
100		-
101		-	~~</tbody>~~
	96	+	\| Sidebar size \| Sidebar component \| macOS 11 (default) \| macOS 10.15 and earlier (default) \|
	97	+	\|---\|---\|---\|---\|
	98	+	\| Small \| Row height \| 24pt \| 22pt \|
	99	+	\| \| SF symbol scale \| Medium † \| – \|
	100	+	\| \| Glyph size \| 16pt × 16pt \| – \|
	101	+	\| \| Text size (style) \| 11pt (Subhead) \| 11pt \|
	102	+	\| Medium \| Row height \| 28pt \| 24pt \|
	103	+	\| \| SF symbol scale \| Medium \| – \|
	104	+	\| \| Glyph size \| 20pt × 20pt \| 18pt × 18pt \|
	105	+	\| \| Text size (style) \| 13pt (Body) \| 13pt \|
	106	+	\| Large \| Row height \| 32pt \| 32pt \|
	107	+	\| \| SF symbol scale \| Medium \| – \|
	108	+	\| \| Glyph size \| 24pt × 24pt \| 24pt × 24pt \|
	109	+	\| \| Text size (style) \| 15pt (Title 3) \| 13pt \|
	110	+	\| All \| Horizontal spacing between cells \| 17pt \| 3pt \|
	111	+	\| \| Vertical spacing between cells \| 0pt \| 2pt \|
	112	+	\| † In some cases, a small sidebar may use small-scale SF Symbols by default. \| \| \| \|
102	113
103	114		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	115
105	116		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	117
107	118		#### Table Views
108	119
109	120		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	121
111	122		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	123
113	124		![](/wiki-images/9/95/MacOS11_tableview_inset.png)
114	125
115	126		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	127
117	128		![](/wiki-images/a/a0/MacOS11_tableview_classic.png)
118	129
119	130		The automatic style means the system uses the table view’s position in the view hierarchy to help determine its appearance.
120	131
121	132		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	133
123	134		\| \| \|
124	135		\|----\|----\|
125	136		\| macOS 11 \| macOS 10.15 \|
126	137		\| ![](/wiki-images/9/91/MacOS11_tableview_layout.png) \| ![](/wiki-images/7/7d/MacOS10_tableview_layout.png) \|
127	138
128	139		The following table lists the values for the table-row layout areas shown above.
129	140
130	141		\| Table-view metric \| macOS 11 \| macOS 10.15 and earlier \|
131	142		\|----\|----\|----\|
132	143		\| Recommended row height \| 24pt \| 17pt \|
133	144		\| Minimum row height for text-only rows \| 18pt \| 17pt \|
134	145		\| Inset at leading and trailing row edges \| 10pt (inset style); 0pt (other styles) \| – \|
135	146		\| Padding at leading and trailing row edges \| 6pt \| – \|
136	147		\| Intercell spacing \| (17,0) \| (3,2) \|
137	148		\| Text size (style) \| 13pt (Body) \| 11pt \|
138	149
139	150		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	151
141	152		As you adjust the layout of your table content to follow the new metrics:
142	153
143	154		- Make sure your icons or glyphs can fit into a 16pt × 16pt area when you use the recommended 24pt row height
144	155		- Consider adding 6 points of space between items within a row to ensure a spacious table appearance
145	156		- 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	157
147	158		> 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	159
149	160		#### Sheets
150	161
151	162		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	163
153	164		\| \| \|
154	165		\|----\|----\|
155	166		\| macOS 11 \| macOS 10.15 \|
156	167		\| ![](/wiki-images/6/6f/MacOS11_sheet.png) \| ![](/wiki-images/8/8b/MacOS10_sheet.png) \|
157	168
158	169		#### Alerts
159	170
160	171		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	172
162	173		![](/wiki-images/1/1f/MacOS11_alert.png)
163	174
164	175		You can also use red text to emphasize a destructive action in an alert.
165	176
166	177		![](/wiki-images/8/88/MacOS11_alert_red.png)
167	178
168	179		### Menus
169	180
170	181		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	182
172	183		- Menu item titles use the same 13-point font size as sidebars and window content areas.
173	184		- Menu separator lines are 1 point thick and inset from the sides.
174	185		- The selection highlight for a menu item is a rounded rectangle that’s inset from the edges of the menu.
175	186
176	187		\| \| \|
177	188		\|----\|----\|
178	189		\| macOS 11 \| macOS 10.15 \|
179	190		\| ![](/wiki-images/f/f7/MacOS11_menu.png) \| ![](/wiki-images/2/2b/MacOS10_menu.png) \|
180	191
181	192		### Controls
182	193
183	194		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	195
185	196		\| Slider \| Size \| macOS 11 (default) \| macOS 10.15 and earlier (default) \|
186	197		\|----\|----\|----\|----\|
187	198		\| Without tick marks \| Regular \| 28pt \| 19pt \|
188	199		\| \| Small \| 20pt \| 15pt \|
189	200		\| \| Mini \| 17pt \| 13pt \|
190	201		\| With tick marks \| Regular \| 28pt \| 24pt \|
191	202		\| \| Small \| 20pt \| 18pt \|
192	203		\| \| Mini \| 17pt \| 15pt \|
193	204
194		-	~~<thead>~~
195		-
196		-	~~</thead>~~
197		-	~~<tbody>~~
198		-
199		-	~~</tbody>~~
200		-
201		-	~~<thead>~~
202		-
203		-	~~</thead>~~
204		-	~~<tbody>~~
	205	+	\| Slider without tick marks \| \|
	206	+	\|---\|---\|
	207	+	\| macOS 11 \| macOS 10.15 \|
	208	+	\| ![](/wiki-images/4/44/MacOS10_slider_notick.png) \| ![](/wiki-images/8/81/MacOS11_slider_notick.png) \|
205	209
206		-	~~</tbody>~~
	210	+	\| Slider with tick marks \| \|
	211	+	\|---\|---\|
	212	+	\| macOS 11 \| macOS 10.15 \|
	213	+	\| ![](/wiki-images/6/61/MacOS11_slider_ticks.png) \| ![](/wiki-images/1/18/MacOS10_slider_ticks.png) \|
207	214
208	215		Beginning in macOS 11, the track of a slider with tick marks aligns with the center of the thumb.
209	216
210	217		### Typography
211	218
212	219		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	220
214	221		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	222
216	223		### Widgets
217	224
218	225		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	226
220	227		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	228
222	229		## Removed features
223	230
224	231		- 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	232
226	233		## Deprecations
227	234
228	235		- 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	236
230	237		- The function hv_vcpu_run(_:) is deprecated. (macOS 11.0.1)
231	238
232	239		- The VNIdentifiedPointsObservation class is deprecated. Use VNRecognizedPointsObservation instances instead. (macOS 11.0.1)
233	240
234	241		- Support for the Developer Transition Kit is no longer available as of macOS Big Sur 11.3. (macOS 11.3)
235	242
236	243		- 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	244
238	245		## New features
239	246
240	247		#### Security
241	248
242	249		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	250
244	251		- You have written scripts which call `/usr/bin/security add-trusted-cert -d ...` as root.
245	252		- Your process runs as root and calls the SecTrustSettingsSetTrustSettings function to trust a certificate.
246	253		- 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	254		- Workaround: Use Apple Configurator 2 to create and install a configuration profile containing your root certificate.
248	255
249	256		#### Kernel
250	257
251	258		- The `kern.argmax` limit has been increased, allowing programs to receive longer argument lists.
252	259		- 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	260		- The requesting process is allowed to send signals by sandbox restrictions.
254	261		- The requesting process and the target process are running as the same user or the requesting process has root privileges.
255	262
256	263		#### Safari
257	264
258	265		- 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	266
260	267		#### Time Machine
261	268
262	269		- 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	270
264	271		#### Virtualisation
265	272
266	273		- The Hypervisor framework now requires the com.apple.security.hypervisor entitlement.
267	274		- A new Virtualization framework provides high-level APIs to run Linux in a virtual machine.
268	275
269	276		#### Built-in dynamic linker cache
270	277
271	278		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	279
273	280		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	281
275	282		### Other differences: Intel vs aarch64
276	283
277	284		- 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	285
279	286		## ARM64/AArch64/Apple Silicon Support
280	287
281	288		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	289
283	290		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	291
285	292		> 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	293
287	294		1. Compile a native AArch64 compiler from the FPC trunk source
288	295		:
289	296
290	297		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	298
292	299		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	300		:
294	301
295	302		rm -f ppca64 ; cp compiler/ppca64 .
296	303
297	304		1. Build a complete native FPC distribution for Darwin/AArch64
298	305		:
299	306
300	307		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	308
302	309		1. Install the built toolchain globally (under /usr/local)
303	310		:
304	311
305	312		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	313
307	314		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	315		:
309	316
310	317		sudo ln -sf /usr/local/lib/fpc/3.3.1/ppca64 /usr/local/bin
311	318
312	319		1. Create a file called ".fpc.cfg" (note the starting ".") in your home directory with the following contents
313	320		:
314	321		2. include /etc/fpc.cfg
315	322
316	323		-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	324
318	325		Now you can use either fpc or ppca64 to compile AArch64 programs.
319	326
320	327		> 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	328
322	329		## Creating a universal binary for aarch64 and x86_64
323	330
324	331		### FPC applications
325	332
326	333		Open a Terminal and use the following commands:
327	334
328	335		``` bash
329	336		fpc my_app.pas -omy_app_ARM64 -Paarch64
330	337		fpc my_app.pas -omy_app_X8664 -Px86_64
331	338		lipo -create -output my_app my_app_ARM64 my_app_X8664
332	339		strip my_app
333	340		```
334	341
335	342		You can check that you have created a universal binary with this command:
336	343
337	344		``` bash
338	345		file my_app
339	346		```
340	347
341	348		which should produce output similar to this:
342	349
343	350		```text
344	351		my_app: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64]
345	352		my_app (for architecture x86_64): Mach-O 64-bit executable x86_64
346	353		my_app (for architecture arm64): Mach-O 64-bit executable arm64
347	354		```
348	355
349	356		### Lazarus applications
350	357
351	358		- Go to Lazarus Menu, Project \> Project Options \> Compiler Options - Config and target
352	359		- Select Target CPU family "aarch64"
353	360		- Go to Lazarus Menu, Project \> Project Options \> Compiler Options - Paths - Target filename
354	361		- Rename my_app to my_app_ARM64
355	362		- Compile
356	363
357	364		- Go to Lazarus Menu, Project \> Project Options \> Compiler Options - Config and target
358	365		- Select Target CPU family "x86_64"
359	366		- Go to Lazarus Menu, Project \> Project Options \> Compiler Options - Paths - Target filename
360	367		- Rename my_app to my_app_X8664
361	368		- Compile
362	369
363	370		- Open a Terminal and execute the following commands in your my_app directory:
364	371
365	372		``` bash
366	373		lipo -create -output my_app my_app_ARM64 my_app_X8664
367	374		strip my_app
368	375		```
369	376
370	377		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	378
372	379		``` bash
373	380		file my_app
374	381		```
375	382
376	383		which should produce output similar to this:
377	384
378	385		```text
379	386		my_app: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64]
380	387		my_app (for architecture x86_64): Mach-O 64-bit executable x86_64
381	388		my_app (for architecture arm64): Mach-O 64-bit executable arm64
382	389		```
383	390
384	391		### Removing duplicate resources in universal binaries
385	392
386	393		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	394
388	395		The Free Pascal Compiler supports loading external resources on Darwin using the -We command line option. For usage examples, see:
389	396
390	397		- <https://gitlab.com/freepascal.org/fpc/source/-/blob/main/tests/test/units/system/tresext.pp> and
391	398		- <https://gitlab.com/freepascal.org/fpc/source/-/blob/main/tests/test/units/system/tres2ext.pp>
392	399
393	400		## Code signing - Intel vs M1
394	401
395	402		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	403
397	404		The situation is different on M1 Apple Silicon (aarch64) systems running Big Sur. There are a few situations to consider:
398	405
399	406		- 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	407
401	408		- 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	409
403	410		- Universal binaries that include both Intel code and native M1 aarch64 code will be blocked from execution unless a valid signature is attached.
404	411
405	412		Checking the status of code signing for FPC and/or FPC and Lazarus native code executables shows:
406	413
407	414		``` pascal
408	415		$ codesign -dv -r- ./program
409	416		Executable=/Users/trev/Documents/fpc_adhoc_test/program
410	417		Identifier=program
411	418		Format=Mach-O thin (arm64)
412	419		CodeDirectory v=20400 size=3392 flags=0x20002(adhoc,linker-signed) hashes=103+0 location=embedded
413	420		Signature=adhoc
414	421		Info.plist=not bound
415	422		TeamIdentifier=not set
416	423		Sealed Resources=none
417	424		# designated => cdhash H"6d17593d42b7b10d8af344197c48df47beda2779"
418	425		```
419	426
420	427		```text
421	428		$ codesign -dv -r- DemoDownload.app
422	429		Executable=/Users/trev/Documents/laz_resume_dload/DemoDownload.app/Contents/MacOS/DemoDownload
423	430		Identifier=DemoDownload
424	431		Format=app bundle with Mach-O thin (arm64)
425	432		CodeDirectory v=20400 size=110533 flags=0x20002(adhoc,linker-signed) hashes=3451+0 location=embedded
426	433		Signature=adhoc
427	434		Info.plist=not bound
428	435		TeamIdentifier=not set
429	436		Sealed Resources=none
430	437		# designated => cdhash H"bb0a310c980906bd6320deaabc72f543dc725bbb"
431	438		```
432	439
433	440		So, it appears that the macOS linker is doing the ad hoc code signing for us and generating the all-important cdhash.
434	441
435	442		What happens if you edit the executable with the cdhash (I changed a single occurrence of Assertion to ASsertion) ?
436	443
437	444		``` pascal
438	445		$ ./program
439	446		Killed
440	447		```
441	448
442	449		and:
443	450
444	451		Process: DemoDownload [7888]
445	452		Path: /Users/USER/Documents/*/DemoDownload.app/Contents/MacOS/DemoDownload
446	453		Identifier: com.company.DemoDownload
447	454		Version: 0.1 (1)
448	455		Code Type: ARM-64 (Native)
449	456		Parent Process: ??? [1]
450	457		Responsible: DemoDownload [7888]
451	458		User ID: 501
452	459
453	460		Date/Time: 2021-03-14 15:52:46.806 +1100
454	461		OS Version: macOS 11.2.3 (20D91)
455	462		Report Version: 12
456	463		Anonymous UUID: FDB6D79D-592D-3959-8F4F-9EC29A74836C
457	464
458	465		Time Awake Since Boot: 5300 seconds
459	466
460	467		System Integrity Protection: enabled
461	468
462	469		Crashed Thread: 0 Dispatch queue: com.apple.main-thread
463	470
464	471		Exception Type: EXC_BAD_ACCESS (Code Signature Invalid)
465	472		Exception Codes: 0x0000000000000032, 0x00000001023bd758
466	473		Exception Note: EXC_CORPSE_NOTIFY
467	474
468	475		Termination Reason: Namespace CODESIGNING, Code 0x2
469	476
470	477		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.
471	478
472	479		### What does this mean for natively compiled FPC and Lazarus aarch64 binaries?
473	480
474	481		If you deploy:
475	482
476	483		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.
477	484
478	485		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.
479	486
480	487		For manual ad hoc code signing of an application bundle (note that a dash is using for the signing identity after the -s argument):
481	488
482	489		```text
483	490		codesign --force --deep -s - MyApp.app
484	491		```
485	492
486	493		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.
487	494
488	495		For manual ad hoc signing of a command line utility:
489	496
490	497		```text
491	498		codesign --force -s - MyExe
492	499		```
493	500
494	501		### Code signing an x86_64 binary on an aarch64 machine
495	502
496	503		## Apple Big Sur "New Look" external links
497	504
498	505		- [WWDC2020 - New look macOS](https://developer.apple.com/videos/play/wwdc2020/10104/)
499	506		- [WWDC2019 - Introducing SF Symbols](https://developer.apple.com/videos/play/wwdc2019/206)
500	507		- [WWDC2020 - SF Symbols 2](https://developer.apple.com/videos/play/wwdc2020/10207)
501	508
502	509		## Apple Silicon external links
503	510
504	511		- [Apple: Porting Your macOS Apps to Apple Silicon](https://developer.apple.com/documentation/xcode/porting_your_macos_apps_to_apple_silicon)
505	512		- [Apple: Building a Universal macOS Binary](https://developer.apple.com/documentation/xcode/building_a_universal_macos_binary)
506	513		- [Apple: Addressing Architectural Differences in Your macOS Code](https://developer.apple.com/documentation/apple_silicon/addressing_architectural_differences_in_your_macos_code)
507	514		- [Apple: Porting Your Audio Code to Apple Silicon](https://developer.apple.com/documentation/audiounit/porting_your_audio_code_to_apple_silicon)
508	515		- [Apple: Porting Your Metal Code to Apple Silicon](https://developer.apple.com/documentation/metal/porting_your_metal_code_to_apple_silicon)
509	516		- [Apple: Installing a Custom Kernel Extension](https://developer.apple.com/documentation/apple_silicon/installing_a_custom_kernel_extension)
510	517		- [Apple: Debugging a Custom Kernel Extension](https://developer.apple.com/documentation/apple_silicon/debugging_a_custom_kernel_extension)
511	518		- [Apple: Platform Security Guide](https://support.apple.com/en-au/guide/security/welcome/web).
512	519		- [Apple: Code signing x86_64 binaries on aarch64](https://developer.apple.com/forums/thread/673323).
513	520
514	521		## Big Sur Release Notes
515	522
516	523		- [Apple: macOS Release Notes](https://developer.apple.com/documentation/macos-release-notes/).
517	524
518	525		---
519	526		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).
520	527		Category: FPC
521	528		Category: Install
522	529		Category: Lazarus
523	530		Category: Platform-sensitive development
524	531		Category: macOS

Back to history