From a666cab01032d12c10b7d2d61bf8f641566a30c4 Mon Sep 17 00:00:00 2001 From: Sebastien Pouliot Date: Tue, 10 Dec 2024 09:57:36 -0500 Subject: [PATCH] chore: Apply suggestions from review Co-authored-by: Andres Pineda <1900897+ajpinedam@users.noreply.github.com> --- .../uno-publishing-desktop-macos-advanced.md | 14 +++++----- doc/articles/uno-publishing-desktop-macos.md | 26 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/doc/articles/uno-publishing-desktop-macos-advanced.md b/doc/articles/uno-publishing-desktop-macos-advanced.md index 07334d7a1a0e..c1e5728cc599 100644 --- a/doc/articles/uno-publishing-desktop-macos-advanced.md +++ b/doc/articles/uno-publishing-desktop-macos-advanced.md @@ -61,7 +61,7 @@ You can create a basic `Info.plist` file yourself, using any text editor. The co ``` -You can edit the `Info.plist` file, add any required entries (for permissions), and let other fields empty. The basic, empty fields will be filled automatically by the `msbuild` task based on your project. +You can edit the `Info.plist` file, add any required entries (for permissions), and leave other fields empty. The basic, empty fields will be filled automatically by the `msbuild` task based on your project. Then from the CLI run: @@ -102,7 +102,7 @@ dotnet publish -f net8.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:U ### Trimming -App bundles that are distributed should be self-contained applications that depends only on the OS to execute. However bundling the dotnet runtime, base class libraries and Uno Platform libraries produce a rather large application size. +App bundles that are distributed should be self-contained applications that depend only on the OS to execute. However bundling the dotnet runtime, base class libraries and Uno Platform libraries produce a rather large application size. To reduce the size of the app bundle you can enable dotnet's [trimming](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trimming-options#enable-trimming) when publishing the app, using `-p:PublishTrimmed=true`. The full command from the CLI would be: @@ -115,11 +115,11 @@ dotnet publish -f net8.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:P ### Optional files -`dotnet publish` include several files that are not strictly required to execute your application. To reduce the app bundle size most of those files are **not** included, by default, inside the app bundles. +`dotnet publish` includes several files that are not strictly required to execute your application. To reduce the app bundle size most of those files are **not** included, by default, inside the app bundles. #### Including dotnet `createdump` tool -Useful for debugging, the `createdump` executable is rarely used by the consumers of the application and, by default, is not included in the app bundle. +Although useful for debugging, the `createdump` executable is rarely used by the application's consumers and, by default, is not included in the app bundle. If you wish to include `createdump` inside your app bundle add the `-p:UnoMacOSIncludeCreateDump=true` on the CLI. @@ -149,9 +149,9 @@ dotnet publish -f net8.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:U #### Including assemblies debugging symbols (.pdb) files -dotnet debugging symbols (`.pdb`) are generally included in released applications since it helps to provide better stack trace and help developers resolving issues. As such they are, by default, included inside the app bundle. +dotnet debugging symbols (`.pdb`) are generally included in released applications since they help to provide better stack traces and help developers resolve issues. As such, they are, by default, included inside the app bundle. -If you wish to remove them anyway you can do so by adding the `-p:UnoMacOSIncludeDebugSymbols=false` on the CLI. +If you wish to remove them anyway, you can do so by adding the `-p:UnoMacOSIncludeDebugSymbols=false` on the CLI. ```bash dotnet publish -f net8.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:UnoMacOSIncludeDebugSymbols=false @@ -169,7 +169,7 @@ dotnet publish -f net8.0-desktop -p:SelfContained=true -p:PackageFormat=dmg -p:U ### Additional Customization -Further disk image customization is possible but can be tricky since it requires modification to the `.DS_Store` binary file inside the disk image (a lot of trials and errors). If more control is required (e.g. icon positioning, background image...) we recommend the use of 3rd party tools created specifically for this purpose. Some free/open source examples are: +Further disk image customization is possible but can be tricky since it requires modification to the `.DS_Store` binary file inside the disk image (many trials and errors). If more control is required (e.g. icon positioning, background image...) we recommend using 3rd party tools created specifically for this purpose. Some free/open source examples are: - [create-dmg](https://github.com/sindresorhus/create-dmg) - [dmgbuild](https://dmgbuild.readthedocs.io/en/latest/) diff --git a/doc/articles/uno-publishing-desktop-macos.md b/doc/articles/uno-publishing-desktop-macos.md index 573f8be59299..67ee788a24a7 100644 --- a/doc/articles/uno-publishing-desktop-macos.md +++ b/doc/articles/uno-publishing-desktop-macos.md @@ -40,14 +40,14 @@ To ensure the integrity of the app bundle Apple requires you to digitally sign y dotnet publish -f net8.0-desktop -r osx-arm64 -p:SelfContained=true -p:PackageFormat=app -p:CodesignKey={{identity}} ``` -You can use the special identity `-` to produce an adhoc signature. This basically tells macOS's [Gatekeeper](https://support.apple.com/en-us/102445) that the file is safe to use **locally**, however this does not help for distributing the app bundle. +You can use the special identity `-` to produce an adhoc signature. This basically tells macOS's [Gatekeeper](https://support.apple.com/en-us/102445) that the file is safe to use **locally**, however, it does not help distribute the app bundle. > [!NOTE] > Beside needed access to the Internet the code signing process slows down the builds. For local testing of your app you do not need to sign the app bundle. #### How to find your identity -If you have not already you need to create your [developer certificates](https://developer.apple.com/help/account/create-certificates/create-developer-id-certificates/). Once you have created on your Mac computer them you can find your identities, from the CLI, by running: +If you have not already, you need to create your [developer certificates](https://developer.apple.com/help/account/create-certificates/create-developer-id-certificates/). Once you have created them, on your Mac computer, you can find your identities from the CLI, by running: ```bash security find-identity -v @@ -91,10 +91,10 @@ From the CLI run: dotnet publish -f net8.0-desktop -r {{RID}} -p:SelfContained=true -p:PackageFormat=pkg -p:CodesignKey={{identity}} -p:PackageSigningKey={{installer_identity}} ``` -Where the following changes to the previous command are +Where the following changes to the previous command are: -- modifying `PackageFormat` to `pkg` to produce the package. This package will include the the app bundle inside it, so the `CodesignKey` argument is still required; -- adding `-p:PackageSigningKey={{installer_identity}}` to specify which identity should be used to sign the package. Unlike app bundles the signing step requires the use of a `Developer ID Installer: *` identity. +- modifying `PackageFormat` to `pkg` to produce the package. This package will include the app bundle inside it, so the `CodesignKey` argument is still required; +- adding `-p:PackageSigningKey={{installer_identity}}` to specify which identity should be used to sign the package. Unlike app bundles, signing requires a `Developer ID Installer: *` identity. The resulting installer will be located at `bin/Release/net8.0-desktop/{{RID}}/publish/{{APPNAME}}.pkg`. @@ -103,9 +103,9 @@ The resulting installer will be located at `bin/Release/net8.0-desktop/{{RID}}/p #### Notarize the package -Having both the app bundle (.app) and installer (.pkg) signed is not quite enough. As the package is a binary that you'll share with customers it needs to be notarized by Apple. +Having both the app bundle (.app) and installer (.pkg) signed is insufficient. As the package is binary and you'll share it with customers, Apple must also notarize it. -The first step is the store your Apple Account credentials inside the key store. This makes all the further commands (and notarization) much simpler. From the CLI run: +The first step is to store your Apple Account credentials inside the key store. This makes all the further commands (and notarization) much simpler. From the CLI run: ```bash xcrun notarytool store-credentials {{notarytool-credentials}} --apple-id john.appleby@platform.uno --team-id XXXXXXXXXX --password aaaa-bbbb-cccc-dddd @@ -130,7 +130,7 @@ Credentials saved to Keychain. To use them, specify `--keychain-profile "notarytool-credentials"` ``` -Once this (one time) setup is done you can notarize the disk image while building the app. From the CLI run: +Once this (one-time) setup is done, you can notarize the disk image while building the app. From the CLI run: ```bash dotnet publish -f net8.0-desktop -r {{RID}} -p:SelfContained=true -p:PackageFormat=dmg -p:CodesignKey={{identity}} -p:PackageSigningKey={{installer_identity}} -p:UnoMacOSNotarizeKeychainProfile={{notarytool-credentials}} -bl @@ -158,8 +158,8 @@ dotnet publish -f net8.0-desktop -r {{RID}} -p:SelfContained=true -p:PackageForm Where the following changes to the original command are -- modifying `PackageFormat` to `dmg` to produce the disk image. This image will include the the app bundle inside it, so the `CodesignKey` argument is still required; -- adding `-p:DiskImageSigningKey={{identity}}` to specify which identity should be used to sign the package. Like app bundles the signing step requires the use of a `Developer ID Application: *` identity. +- modifying `PackageFormat` to `dmg` to produce the disk image. This image will include the app bundle inside it, so the `CodesignKey` argument is still required; +- adding `-p:DiskImageSigningKey={{identity}}` to specify which identity should be used to sign the package. Like app bundles, the signing step requires using a `Developer ID Application: *` identity. The resulting disk image will be located at `bin/Release/net8.0-desktop/{{RID}}/publish/{{APPNAME}}.dmg`. @@ -167,7 +167,7 @@ The resulting disk image will be located at `bin/Release/net8.0-desktop/{{RID}}/ Like an installer (.pkg) a disk image is the outermost container that you'll share with customers and, as such, needs to be notarized by Apple. -The first step is the store your Apple Account credentials inside the key store. This makes all the further commands (and notarization) much simpler. From the CLI run: +The first step is to store your Apple Account credentials inside the key store. This makes all the further commands (and notarization) much simpler. From the CLI run: ```bash xcrun notarytool store-credentials {{notarytool-credentials}} --apple-id john.appleby@platform.uno --team-id XXXXXXXXXX --password aaaa-bbbb-cccc-dddd @@ -192,7 +192,7 @@ Credentials saved to Keychain. To use them, specify `--keychain-profile "notarytool-credentials"` ``` -Once this (one time) setup is done you can notarize the disk image while building the app. From the CLI run: +Once this (one-time) setup is done, you can notarize the disk image while building the app. From the CLI run: ```bash dotnet publish -f net8.0-desktop -r {{RID}} -p:SelfContained=true -p:PackageFormat=dmg -p:CodesignKey={{identity}} -p:DiskImageSigningKey={{identity}} -p:UnoMacOSNotarizeKeychainProfile={{notarytool-credentials}} -bl @@ -211,7 +211,7 @@ Once completed you can distribute the notarized disk image. ### Mac App Store > [!IMPORTANT] -> Application distributed on the Mac App Store are required to execute under a [sandbox](https://developer.apple.com/documentation/security/app-sandbox?language=objc) which impose additional limits on how applications can interact with the computer. +> Applications distributed on the Mac App Store are required to execute under a [sandbox](https://developer.apple.com/documentation/security/app-sandbox?language=objc), which imposes additional limits on how applications can interact with the computer. An app bundle (.app) can be submitted to Apple's [App Store](https://www.apple.com/app-store/) using the [transporter app](https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds) from a computer running macOS.