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