Skip to content

Commit 2bb3126

Browse files
craastadcraastad
authored
Add Flutter macOS build and release guide (#5893)
1 parent 0919fab commit 2bb3126

File tree

3 files changed

+264
-0
lines changed

3 files changed

+264
-0
lines changed

‎src/_data/sidenav.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,8 @@
350350
permalink: /docs/deployment/android
351351
- title: Build and release an iOS app
352352
permalink: /docs/deployment/ios
353+
- title: Build and release a macOS app
354+
permalink: /docs/deployment/macos
353355
- title: Build and release a Linux app
354356
permalink: /docs/deployment/linux
355357
- title: Build and release a web app

‎src/docs/deployment/macos.md‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
---
2+
title: Build and release a macOS app
3+
description: How to release a Flutter app to the macOS App Store.
4+
short-title: macOS
5+
---
6+
7+
This guide provides a step-by-step walkthrough of releasing a
8+
Flutter app to the [App Store][appstore].
9+
10+
## Preliminaries
11+
12+
Before beginning the process of releasing your app,
13+
ensure that it meets
14+
Apple's [App Review Guidelines][appreview].
15+
16+
In order to publish your app to the App Store,
17+
you must first enroll in the
18+
[Apple Developer Program][devprogram].
19+
You can read more about the various
20+
membership options in Apple's
21+
[Choosing a Membership][devprogram_membership] guide.
22+
23+
## Register your app on App Store Connect
24+
25+
Manage your app's life cycle on
26+
[App Store Connect][appstoreconnect] (formerly iTunes Connect).
27+
You define your app name and description, add screenshots,
28+
set pricing, and manage releases to the App Store and TestFlight.
29+
30+
Registering your app involves two steps: registering a unique
31+
Bundle ID, and creating an application record on App Store Connect.
32+
33+
For a detailed overview of App Store Connect, see the
34+
[App Store Connect][appstoreconnect_guide] guide.
35+
36+
### Register a Bundle ID
37+
38+
Every macOS application is associated with a Bundle ID,
39+
a unique identifier registered with Apple.
40+
To register a Bundle ID for your app, follow these steps:
41+
42+
1. Open the [App IDs][devportal_appids] page of your developer account.
43+
1. Click **+** to create a new Bundle ID.
44+
1. Enter an app name, select **Explicit App ID**, and enter an ID.
45+
1. Select the services your app uses, then click **Continue**.
46+
1. On the next page, confirm the details and click **Register**
47+
to register your Bundle ID.
48+
49+
### Create an application record on App Store Connect
50+
51+
Register your app on App Store Connect:
52+
53+
1. Open [App Store Connect][appstoreconnect_login] in your browser.
54+
1. On the App Store Connect landing page, click **My Apps**.
55+
1. Click **+** in the top-left corner of the My Apps page,
56+
then select **New App**.
57+
1. Fill in your app details in the form that appears.
58+
In the Platforms section, ensure that iOS is checked.
59+
Since Flutter does not currently support tvOS,
60+
leave that checkbox unchecked. Click **Create**.
61+
1. Navigate to the application details for your app and select
62+
**App Information** from the sidebar.
63+
1. In the General Information section, select the Bundle ID
64+
you registered in the preceding step.
65+
66+
For a detailed overview,
67+
see [Add an app to your account][appstoreconnect_guide_register].
68+
69+
## Review Xcode project settings
70+
71+
This step covers reviewing the most important settings
72+
in the Xcode workspace.
73+
For detailed procedures and descriptions, see
74+
[Prepare for app distribution][distributionguide_config].
75+
76+
Navigate to your target's settings in Xcode:
77+
78+
1. In Xcode, open `Runner.xcworkspace` in your app's `ios` folder.
79+
1. To view your app's settings, select the **Runner** project in the Xcode
80+
project navigator. Then, in the main view sidebar, select the **Runner**
81+
target.
82+
1. Select the **General** tab.
83+
84+
Verify the most important settings.
85+
86+
In the **Identity** section:
87+
88+
`App Category`
89+
: The app category under which your app will be listed on the Mac App Store. This cannot be none.
90+
91+
`Bundle Identifier`
92+
: The App ID you registered on App Store Connect.
93+
94+
In the **Deployment info** section:
95+
96+
`Deployment Target`
97+
: The minimum macOS version that your app supports. Flutter supports macOS 10.11 and later.
98+
99+
In the **Signing & Capabilities** section:
100+
101+
`Automatically manage signing`
102+
: Whether Xcode should automatically manage app signing
103+
and provisioning. This is set `true` by default, which should
104+
be sufficient for most apps. For more complex scenarios,
105+
see the [Code Signing Guide][codesigning_guide].
106+
107+
`Team`
108+
: Select the team associated with your registered Apple Developer
109+
account. If required, select **Add Account...**,
110+
then update this setting.
111+
112+
The **General** tab of your project settings should resemble
113+
the following:
114+
115+
![Xcode Project Settings](/images/releaseguide/macos_xcode_settings.png){:width="100%"}
116+
117+
For a detailed overview of app signing, see
118+
[Create, export, and delete signing certificates][appsigning].
119+
120+
## Updating the app's version number
121+
122+
The default version number of the app is `1.0.0`.
123+
To update it, navigate to the `pubspec.yaml` file
124+
and update the following line:
125+
126+
`version: 1.0.0+1`
127+
128+
The version number is three numbers separated by dots,
129+
such as `1.0.0` in the example above, followed by an optional
130+
build number such as `1` in the example above, separated by a `+`.
131+
132+
Both the version and the build number may be overridden in Flutter's
133+
build by specifying `--build-name` and `--build-number`,
134+
respectively.
135+
136+
In macOS, `build-name` uses `CFBundleShortVersionString`
137+
while `build-number` uses `CFBundleVersion`.
138+
Read more about iOS versioning at [Core Foundation Keys][]
139+
on the Apple Developer's site.
140+
141+
## Add an app icon
142+
143+
When a new Flutter app is created, a placeholder icon set is created.
144+
This step covers replacing these placeholder icons with your
145+
app's icons:
146+
147+
1. Review the [macOS App Icon][appicon] guidelines.
148+
1. In the Xcode project navigator, select `Assets.xcassets` in the
149+
`Runner` folder. Update the placeholder icons with your own app icons.
150+
1. Verify the icon has been replaced by running your app using
151+
`flutter run -d macos`.
152+
153+
## Create a build archive
154+
155+
This step covers creating a build archive and uploading
156+
your build to App Store Connect.
157+
158+
During development, you've been building, debugging, and testing
159+
with _debug_ builds. When you're ready to ship your app to users
160+
on the App Store or TestFlight, you need to prepare a _release_ build.
161+
At this point, you might consider [obfuscating your Dart code][]
162+
to make it more difficult to reverse engineer. Obfuscating
163+
your code involves adding a couple flags to your build command.
164+
165+
In Xcode, configure the app version and build:
166+
167+
1. In Xcode, open `Runner.xcworkspace` in your app's `macos` folder.
168+
1. Select **Runner** in the Xcode project navigator, then select the
169+
**Runner** target in the settings view sidebar.
170+
1. In the Identity section, update the **Version** to the user-facing
171+
version number you wish to publish.
172+
1. In the Identity section, update the **Build** identifier to a unique
173+
build number used to track this build on App Store Connect.
174+
Each upload requires a unique build number.
175+
176+
Finally, create a build archive and upload it to App Store Connect:
177+
178+
<ol markdown="1">
179+
<li markdown="1">
180+
181+
Open Xcode and select **Product > Archive**. Run `flutter build macos` to produce a build archive.
182+
183+
</li>
184+
<li markdown="1">
185+
186+
Click the **Validate App** button. If any issues are reported,
187+
address them and produce another build. You can reuse the same
188+
build ID until you upload an archive.
189+
190+
</li>
191+
<li markdown="1">
192+
193+
After the archive has been successfully validated, click
194+
**Distribute App**. You can follow the status of your build in the
195+
Activities tab of your app's details page on
196+
[App Store Connect][appstoreconnect_login].
197+
198+
</li>
199+
</ol>
200+
201+
You should receive an email within 30 minutes notifying you that
202+
your build has been validated and is available to release to testers
203+
on TestFlight. At this point you can choose whether to release
204+
on TestFlight, or go ahead and release your app to the App Store.
205+
206+
For more details, see
207+
[Upload an app to App Store Connect][distributionguide_upload].
208+
209+
## Distribute to registered devices
210+
211+
[TestFlight][] is not available for distributing macOS apps
212+
to internal and external testers. See [distribution guide][distributionguide_macos]
213+
to prepare an archive for distribution to designated Mac computers.
214+
215+
## Release your app to the App Store
216+
217+
When you're ready to release your app to the world,
218+
follow these steps to submit your app for review and
219+
release to the App Store:
220+
221+
1. Select **Pricing and Availability** from the sidebar of your app's
222+
application details page on
223+
[App Store Connect][appstoreconnect_login] and complete the
224+
required information.
225+
1. Select the status from the sidebar. If this is the first
226+
release of this app, its status is
227+
**1.0 Prepare for Submission**. Complete all required fields.
228+
1. Click **Submit for Review**.
229+
230+
Apple notifies you when their app review process is complete.
231+
Your app is released according to the instructions you
232+
specified in the **Version Release** section.
233+
234+
For more details, see
235+
[Distribute an app through the App Store][distributionguide_submit].
236+
237+
## Troubleshooting
238+
239+
The [Distribute your app][distributionguide] guide provides a
240+
detailed overview of the process of releasing an app to the App Store.
241+
242+
243+
[appicon]: https://developer.apple.com/design/human-interface-guidelines/macos/icons-and-images/app-icon/
244+
[appreview]: https://developer.apple.com/app-store/review/
245+
[appsigning]: https://help.apple.com/xcode/mac/current/#/dev154b28f09
246+
[appstore]: https://developer.apple.com/app-store/submissions/
247+
[appstoreconnect]: https://developer.apple.com/support/app-store-connect/
248+
[appstoreconnect_guide]: https://developer.apple.com/support/app-store-connect/
249+
[appstoreconnect_guide_register]: https://help.apple.com/app-store-connect/#/dev2cd126805
250+
[appstoreconnect_login]: https://appstoreconnect.apple.com/
251+
[codesigning_guide]: https://developer.apple.com/library/content/documentation/Security/Conceptual/CodeSigningGuide/Introduction/Introduction.html
252+
[Core Foundation Keys]: https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
253+
[devportal_appids]: https://developer.apple.com/account/ios/identifier/bundle
254+
[devprogram]: https://developer.apple.com/programs/
255+
[devprogram_membership]: https://developer.apple.com/support/compare-memberships/
256+
[distributionguide]: https://help.apple.com/xcode/mac/current/#/dev8b4250b57
257+
[distributionguide_config]: https://help.apple.com/xcode/mac/current/#/dev91fe7130a
258+
[distributionguide_macos]: https://help.apple.com/xcode/mac/current/#/dev295cc0fae
259+
[distributionguide_submit]: https://help.apple.com/xcode/mac/current/#/dev067853c94
260+
[distributionguide_upload]: https://help.apple.com/xcode/mac/current/#/dev442d7f2ca
261+
[obfuscating your Dart code]: /docs/deployment/obfuscate
262+
[TestFlight]: https://developer.apple.com/testflight/

‎src/images/releaseguide/macos_xcode_settings.png‎

143 KB
Loading

0 commit comments

Comments
 (0)