doc/README-DMG_creation.md

   1 # Information for making the DMG
   2
   3 ## New method to make the DS_Store file from scratch (on a Mac)
   4
   5 ```
   6 ./utils/install4j/mk_ds_store.sh --name Jalview [--volname "Jalview Installer (2.11.2.0)"] [--bgimg ./utils/channels/release/image/jalview_dmg_background.png] [--output ./utils/channels/release/image/jalview_dmg_DS_Store]
   7 ```
   8
   9 A script that creates a new DMG with the top level items to be found in a Jalview Installer DMG, mounts the volume, then uses an AppleScript to adjust the background image, size and position of the icons, and appearance of the Finder window.
  10
  11 The .DS_Store is then copied out of the volume by the script, the volume unmounted, and all files (in /tmp) tidied up.
  12
  13 To use it, the NAME (of the application, without the `.app` extension) should be set in the script (set to "Jalview"), and the background image that you want to use should be copied to your working directory as `background.png` (or use the --bgimg option).
  14
  15 While it is running you will see a styled Finder window appear.  The App icon will be broken as only a folder for the App is put in place, not an actual .app.
  16
  17 Once it is run (only works on a Mac with osascript) it will leave a file Output-DS_Store in your working directory (or use the --output option).
  18
  19 > This script borrows extensively from https://github.com/create-dmg/create-dmg
  20
  21 ## Old manual method (possibly instructive)
  22
  23 ### How to make the DS_Store file needed for the DMG prettification
  24
  25 > ALSO SEE https://www.ej-technologies.com/resources/install4j/help/doc/concepts/dmgStyling.html
  26
  27 First create a dmg with no DS_Store (or an existing one if you just want to edit one)
  28
  29 ```
  30 cp ../../build/install4j/11/Jalview-OFFLINE_macos-app_DEVELOPMENT-j11.dmg ./temp.dmg
  31 hdiutil convert temp.dmg -format UDRW -o temp_rw.dmg
  32 ```
  33
  34 If you are creating a new dmg, or want to add more files than remaining space, then you will need to add some capacity to the dmg.  If you're just doing small edits then you might get away without the following block of commands used to resize the dmg.
  35
  36 ```
  37 CURSIZE=`hdiutil resize temp_rw.dmg | perl -n -e 'm/^\s*\d+\s+(\d+)\s+\d+$/ && print "$1\n";'`
  38 NEWSIZE=$(( CURSIZE + 20000))
  39 hdiutil resize -sectors $NEWSIZE temp_rw.dmg
  40 ```
  41 Continue by opening the dmg in Finder.  The `/Volumes/...` folder will depend on the dmg you're editing.
  42 ```
  43 open temp_rw.dmg
  44 open /Volumes/Jalview\ Installer
  45 ```
  46
  47 Run the AppleScript which is needed to set a relative path for the background image which you can ensure is in the volume:
  48 ```
  49 mkdir -p /Volumes/Jalview\ Installer/.background
  50 cp utils/channels/release/images/jalview_dmg_background.png /Volumes/Jalview\ Installer/.background/jalview_dmg_background.png
  51 /usr/bin/osascript utils/install4j/set_relative_dmg_background_image.applescript "Jalview Installer"
  52 ```
  53 (when copying the background image, always put it in the volume as `.background/jalview_dmg_background.png` as that is the relative path we want in the DS_Store.
  54
  55 Then manually position/resize icons, extend size of Finder window, etc so that the Finder window looks how you want it. Some of this is now done by the above AppleScript.
  56 Wait a few seconds to allow the `.DS_Store file` to update.
  57 You can now use the `.DS_Store` file and unmount the RW volume.
  58 ```
  59 cp /Volumes/Jalview\ Installer/.DS_Store ./utils/channel/release/images/jalview_dmg_DS_Store
  60 umount /Volumes/Jalview\ Installer
  61 ```
  62
  63 ### Background image
  64
  65 See file `README-DMG_background_image_creation.md` on how to create the background image.
  66
  67 ### Adding the background image
  68
  69 #### update 2022-03-10
  70 > NEW METHOD: The background image setting now gets added as a relative path with the AppleScript.
  71 > OLD METHOD: See https://www.ej-technologies.com/resources/install4j/help/doc/concepts/dmgStyling.html which describes how to add the background image to your DMG file using macOS Finder.
  72 >
  73 > Adding the background image in this way sets a full path from `/` in the `.DS_Store`, meaning the DMG Volume name cannot change (or if it does then the background image isn't found and so not displayed).
  74 > It should now be set (only needs to be done once) to a relative path, e.g. `.background/jalview_dmg_background.png` using the AppleScript in `utils/install4j/set_relative_dmg_background_image.applescript` with, e.g.
  75 > ` /usr/bin/osascript ./set_relative_dmg_background_image.applescript Jalview\ Installer\ \(2.11.2.0\) `
  76 > which has to be done when the temporary volume is mounted in read-write (UDRW) mode.
  77
  78 ## Future development
  79
  80 Worth exploring further:
  81 * https://github.com/create-dmg/create-dmg  [This was main resource for the new script]
  82 * and the AppleScript on https://stackoverflow.com/questions/96882/how-do-i-create-a-nice-looking-dmg-for-mac-os-x-using-command-line-tools
  83 to script precise placement of icons over background image.
  84 * https://miloserdov.org/?p=3867
  85 * https://www.npmjs.com/package/create-dmg