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 [--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 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).
  16
  17 > This script borrows extensively from https://github.com/create-dmg/create-dmg
  18
  19 ## Old manual method (possibly instructive)
  20
  21 ### How to make the DS_Store file needed for the DMG prettification
  22
  23 > ALSO SEE https://www.ej-technologies.com/resources/install4j/help/doc/concepts/dmgStyling.html
  24
  25 First create a dmg with no DS_Store (or an existing one if you just want to edit one)
  26
  27 ```
  28 cp ../../build/install4j/11/Jalview-OFFLINE_macos-app_DEVELOPMENT-j11.dmg ./temp.dmg
  29 hdiutil convert temp.dmg -format UDRW -o temp_rw.dmg
  30 ```
  31
  32 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.
  33
  34 ```
  35 CURSIZE=`hdiutil resize temp_rw.dmg | perl -n -e 'm/^\s*\d+\s+(\d+)\s+\d+$/ && print "$1\n";'`
  36 NEWSIZE=$(( CURSIZE + 20000))
  37 hdiutil resize -sectors $NEWSIZE temp_rw.dmg
  38 ```
  39 Continue by opening the dmg in Finder.  The `/Volumes/...` folder will depend on the dmg you're editing.
  40 ```
  41 open temp_rw.dmg
  42 open /Volumes/Jalview\ Installer
  43 ```
  44
  45 Run the AppleScript which is needed to set a relative path for the background image which you can ensure is in the volume:
  46 ```
  47 mkdir -p /Volumes/Jalview\ Installer/.background
  48 cp utils/channels/release/images/jalview_dmg_background.png /Volumes/Jalview\ Installer/.background/jalview_dmg_background.png
  49 /usr/bin/osascript utils/install4j/set_relative_dmg_background_image.applescript "Jalview Installer"
  50 ```
  51 (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.
  52
  53 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.
  54 Wait a few seconds to allow the `.DS_Store file` to update.
  55 You can now use the `.DS_Store` file and unmount the RW volume.
  56 ```
  57 cp /Volumes/Jalview\ Installer/.DS_Store ./utils/channel/release/images/jalview_dmg_DS_Store
  58 umount /Volumes/Jalview\ Installer
  59 ```
  60
  61 ### Background image
  62
  63 See file `README-DMG_background_image_creation.md` on how to create the background image.
  64
  65 ### Adding the background image
  66
  67 #### update 2022-03-10
  68 > NEW METHOD: The background image setting now gets added as a relative path with the AppleScript.
  69 > 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.
  70 >
  71 > 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).
  72 > 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.
  73 > ` /usr/bin/osascript ./set_relative_dmg_background_image.applescript Jalview\ Installer\ \(2.11.2.0\) `
  74 > which has to be done when the temporary volume is mounted in read-write (UDRW) mode.
  75
  76 ## Future development
  77
  78 Worth exploring further:
  79 * https://github.com/create-dmg/create-dmg  [This was main resource for the new script]
  80 * 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
  81 to script precise placement of icons over background image.
  82 * https://miloserdov.org/?p=3867
  83 * https://www.npmjs.com/package/create-dmg