Add README to macOS .dmg and "make dist-mac" target to do so.

The build instructions for Qt Creator still need to be updated
to use the new create_dmg script.

Building/MacOS/BUILD-mac.md

@@ -63,7 +63,7 @@ NOTE: Official builds are currently made with [macOS 10.14 Mojave] and Command-L
 
 2. (Optional) Package for distribution:
 
-        ~/Qt5.12.5/5.12.5/clang_64/bin/macdeployqt OSCAR.app -dmg
+        make dist-mac
 
    The dmg is at OSCAR.dmg.
 
@@ -87,7 +87,7 @@ NOTE: Official builds are currently made with [macOS 10.14 Mojave] and Command-L
     8. Set the working directory to the build directory path copied in step 1.
     9. Click OK.
 5. To compile, select Build > Build Project "oscar". The application is in OSCAR.app.
-6. To create a .dmg, select Tools > External > Deploy. The dmg is at OSCAR.dmg.
+6. To create a .dmg, select Tools > External > Deploy. The dmg is at OSCAR.dmg. **Note that the resulting .dmg will NOT include the README.**
 
 [Qt 5.12.5]: http://download.qt.io/archive/qt/5.12/5.12.5/qt-opensource-mac-x64-5.12.5.dmg
 [macOS 10.14 Mojave]: https://apps.apple.com/us/app/macos-mojave/id1398502828?ls=1&mt=12

Building/MacOS/README.rtfd/TXT.rtf

@@ -0,0 +1,69 @@
+{\rtf1\ansi\ansicpg1252\cocoartf1504\cocoasubrtf840
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;\red28\green28\blue28;\red255\green255\blue255;\red9\green47\blue157;
+\red10\green0\blue109;\red0\green0\blue0;}
+{\*\expandedcolortbl;;\cssrgb\c14510\c14510\c14510;\cssrgb\c100000\c100000\c100000;\cssrgb\c2353\c27059\c67843;
+\cssrgb\c4314\c0\c50196;\csgenericrgb\c0\c0\c0;}
+{\*\listtable{\list\listtemplateid1\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid1\'01\uc0\u8226 ;}{\levelnumbers;}\fi-360\li720\lin720 }{\listname ;}\listid1}
+{\list\listtemplateid2\listhybrid{\listlevel\levelnfc0\levelnfcn0\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{decimal\}.}{\leveltext\leveltemplateid101\'02\'00.;}{\levelnumbers\'01;}\fi-360\li720\lin720 }{\listlevel\levelnfc3\levelnfcn3\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{upper-alpha\}.}{\leveltext\leveltemplateid102\'02\'01.;}{\levelnumbers\'01;}\fi-360\li1440\lin1440 }{\listname ;}\listid2}
+{\list\listtemplateid3\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid201\'01\uc0\u8226 ;}{\levelnumbers;}\fi-360\li720\lin720 }{\listname ;}\listid3}}
+{\*\listoverridetable{\listoverride\listid1\listoverridecount0\ls1}{\listoverride\listid2\listoverridecount0\ls2}{\listoverride\listid3\listoverridecount0\ls3}}
+\margl1440\margr1440\vieww19380\viewh16080\viewkind0
+\deftab720
+\pard\pardeftab720\partightenfactor0
+
+\f0\b\fs33\fsmilli16800 \cf2 \cb3 \expnd0\expndtw0\kerning0
+System requirements\
+\cf0 \cb1 \
+\pard\tx220\tx720\pardeftab720\li720\fi-720\partightenfactor0
+\ls1\ilvl0
+\b0\fs28 \cf2 \cb3 \kerning1\expnd0\expndtw0 {\listtext	\'95	}\expnd0\expndtw0\kerning0
+MacOSX 10.12 or later.\cb1 \
+\pard\pardeftab720\partightenfactor0
+
+\b\fs33\fsmilli16800 \cf2 \cb3 \
+\
+Installation\
+\pard\pardeftab720\partightenfactor0
+
+\b0\fs28 \cf2 \cb1 \
+\pard\tx220\tx720\pardeftab720\li720\fi-720\partightenfactor0
+\ls2\ilvl0\cf2 \cb3 \kerning1\expnd0\expndtw0 {\listtext	1.	}\expnd0\expndtw0\kerning0
+To install OSCAR, you need to copy it to the Applications folder on your computer. To do so:\uc0\u8232 \cb1 \
+\pard\tx940\tx1440\pardeftab720\li1440\fi-1440\partightenfactor0
+\ls2\ilvl1\cf2 \cb3 \kerning1\expnd0\expndtw0 {\listtext	A.	}\expnd0\expndtw0\kerning0
+Open the Applications folder in Finder by selecting the "Go" menu and then "Applications": \uc0\u8232 \u8232 \cf4 \cb1 {{\NeXTGraphic Oscar-mac-2-open-applications-folder.jpg \width9620 \height8140 \noorient
+}¬}\cf2 \uc0\u8232 \u8232 \cf4 {{\NeXTGraphic Oscar-mac-3-opened-applications-folder.jpg \width17640 \height10960 \noorient
+}¬}\cf2 \uc0\u8232 \
+\ls2\ilvl1\cb3 \kerning1\expnd0\expndtw0 {\listtext	B.	}\expnd0\expndtw0\kerning0
+Arrange the windows so that you can see the OSCAR icon and the Applications folder, as shown below.\uc0\u8232 \cb1 \
+\ls2\ilvl1\cb3 \kerning1\expnd0\expndtw0 {\listtext	C.	}\expnd0\expndtw0\kerning0
+Click on the OSCAR icon and drag it into the Applications window. Note the green "+" cursor indicating that it will be copied to this location when you unclick: \cf4 \cb1 {{\NeXTGraphic Oscar-mac-4-click.jpg \width18520 \height12920 \noorient
+}¬}\cf2 \uc0\u8232 \u8232 \cf4 {{\NeXTGraphic Oscar-mac-5-drag.jpg \width18520 \height12920 \noorient
+}¬}\cf2 \uc0\u8232 \
+\pard\tx220\tx720\pardeftab720\li720\fi-720\partightenfactor0
+\ls2\ilvl0\cf2 \cb3 \kerning1\expnd0\expndtw0 {\listtext	2.	}\expnd0\expndtw0\kerning0
+To launch OSCAR for the first time, you will need to grant it permission, otherwise you will receive an error that it "can't be opened because it is from an unidentified developer." To grant OSCAR permission to run:\uc0\u8232 \cb1 \
+\pard\tx940\tx1440\pardeftab720\li1440\fi-1440\partightenfactor0
+\ls2\ilvl1\cf2 \cb3 \kerning1\expnd0\expndtw0 {\listtext	A.	}\expnd0\expndtw0\kerning0
+Hold down the "control" key on your keyboard and click on the new OSCAR icon in the Applications folder. Select "open" from the menu that will appear: \cf4 \cb1 {{\NeXTGraphic Oscar-mac-6-right-click-open.jpg \width18520 \height13460 \noorient
+}¬}\cf2 \uc0\u8232 \
+\ls2\ilvl1\cb3 \kerning1\expnd0\expndtw0 {\listtext	B.	}\expnd0\expndtw0\kerning0
+A window will appear advising you that "OSCAR is from an unidentified developer" and asking if you want to run it. Click "Open" to grant it permission: \uc0\u8232 \cf5 \cb1 {{\NeXTGraphic Oscar-mac-7-open-confirm-with-cursor.jpg \width10640 \height6220 \noorient
+}¬}\cf2 \uc0\u8232 \u8232 \cb3 You will only need to do this the first time you run OSCAR after installing any new version.\cb1 \
+\pard\pardeftab720\partightenfactor0
+
+\b\fs33\fsmilli16800 \cf2 \cb3 \
+\
+Troubleshooting\
+\cf0 \cb1 \
+\pard\tx220\tx720\pardeftab720\li720\fi-720\partightenfactor0
+\ls3\ilvl0
+\b0\fs28 \cf2 \cb3 \kerning1\expnd0\expndtw0 {\listtext	\'95	}\expnd0\expndtw0\kerning0
+Help, I'm getting the following error! \uc0\u8232 \cf5 \cb1 {{\NeXTGraphic Oscar-mac-8-open-error.jpg \width10640 \height6220 \noorient
+}¬}\cf2 \uc0\u8232 \u8232 \cf6 \cb3 This can happen after installing a new version of OSCAR. Open the Applications folder as shown in step 1 above and then see step 2 above to grant OSCAR permission to run.\
+\pard\tx720\pardeftab720\partightenfactor0
+\cf2 \
+\
+The most up-to-date version of these instructions can be found at {\field{\*\fldinst{HYPERLINK "http://www.apneaboard.com/wiki/index.php/OSCAR_Installation:_Apple_Mac"}}{\fldrslt http://www.apneaboard.com/wiki/index.php/OSCAR_Installation:_Apple_Mac}}.\
+}

oscar/oscar.pro

@@ -508,7 +508,11 @@ test {
         tests/sessiontests.h
 }
 
-# On macOS put a custom Info.plist into the bundle that disables dark mode on Mojave
 macx {
+    # On macOS put a custom Info.plist into the bundle that disables dark mode on Mojave
     QMAKE_INFO_PLIST = "../Building/MacOS/Info.plist.in"
+
+    # Add a dist-mac target to build the distribution .dmg.
+    QMAKE_EXTRA_TARGETS += dist-mac
+    dist-mac.commands = QT_BIN=$$[QT_INSTALL_PREFIX]/bin $$_PRO_FILE_PWD_/scripts/create_dmg OSCAR OSCAR.app $$_PRO_FILE_PWD_/../Building/MacOS/README.rtfd
 }

oscar/scripts/create_dmg

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Usage: create_dmg target_name file1 [file2...]
+
+# TODO: add background image and symlink to /Applications, once we have a signed app and no longer need the README
+
+STAGING_DIR="./Staging"
+
+# Extract the target name
+TARGET="$1"
+shift
+
+# Look for the .app in the files to be added to the .dmg
+APP=""
+for src in "$@"
+do
+    [[ "$src" == *.app ]] && APP="$src"
+done
+
+if [[ ${APP} != "" ]]; then
+    # Create deployable application bundle (if it hasn't been already been done)
+    if [[ ! -d "${APP}/Contents/Frameworks/QtCore.framework" ]]; then
+        echo $QT_BIN/macdeployqt "${APP}"
+        $QT_BIN/macdeployqt "${APP}"
+    fi
+
+    # TODO: add version number to target .dmg filename
+    # 1. Set the version in the Info.plist during build.
+    # 2. Get the version from ${APP}/Contents/Info.plist
+fi
+
+mkdir "${STAGING_DIR}" || exit
+
+for src in "$@"
+do
+    echo "Copying ${src}"
+    cp -a "$src" "${STAGING_DIR}/."
+done
+
+echo "Creating .dmg"
+hdiutil create -srcfolder "${STAGING_DIR}" -volname "${TARGET}" -fs HFS+ -fsargs "-c c=64,a=16,e=16" -format UDZO -imagekey zlib-level=9 -o "${TARGET}.dmg" -ov
+
+rm -rf "${STAGING_DIR}"