# Information for making the DMG

## New method to make the DS_Store file from scratch (on a Mac)

```
./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]
```

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.

The .DS_Store is then copied out of the volume by the script, the volume unmounted, and all files (in /tmp) tidied up.

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).

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.

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).

> This script borrows extensively from https://github.com/create-dmg/create-dmg

## Old manual method (possibly instructive)

### How to make the DS_Store file needed for the DMG prettification

> ALSO SEE https://www.ej-technologies.com/resources/install4j/help/doc/concepts/dmgStyling.html

First create a dmg with no DS_Store (or an existing one if you just want to edit one)

```
cp ../../build/install4j/11/Jalview-OFFLINE_macos-app_DEVELOPMENT-j11.dmg ./temp.dmg
hdiutil convert temp.dmg -format UDRW -o temp_rw.dmg
```

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.

```
CURSIZE=`hdiutil resize temp_rw.dmg | perl -n -e 'm/^\s*\d+\s+(\d+)\s+\d+$/ && print "$1\n";'`
NEWSIZE=$(( CURSIZE + 20000))
hdiutil resize -sectors $NEWSIZE temp_rw.dmg
```
Continue by opening the dmg in Finder.  The `/Volumes/...` folder will depend on the dmg you're editing.
```
open temp_rw.dmg
open /Volumes/Jalview\ Installer
```

Run the AppleScript which is needed to set a relative path for the background image which you can ensure is in the volume:
```
mkdir -p /Volumes/Jalview\ Installer/.background
cp utils/channels/release/images/jalview_dmg_background.png /Volumes/Jalview\ Installer/.background/jalview_dmg_background.png
/usr/bin/osascript utils/install4j/set_relative_dmg_background_image.applescript "Jalview Installer"
```
(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.

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.
Wait a few seconds to allow the `.DS_Store file` to update.
You can now use the `.DS_Store` file and unmount the RW volume.
```
cp /Volumes/Jalview\ Installer/.DS_Store ./utils/channel/release/images/jalview_dmg_DS_Store
umount /Volumes/Jalview\ Installer
```

### Background image

See file `README-DMG_background_image_creation.md` on how to create the background image.

### Adding the background image

#### update 2022-03-10
> NEW METHOD: The background image setting now gets added as a relative path with the AppleScript.
> 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.
> 
> 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).
> 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.
> ` /usr/bin/osascript ./set_relative_dmg_background_image.applescript Jalview\ Installer\ \(2.11.2.0\) `
> which has to be done when the temporary volume is mounted in read-write (UDRW) mode.

## Future development

Worth exploring further:
* https://github.com/create-dmg/create-dmg  [This was main resource for the new script]
* 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
to script precise placement of icons over background image.
* https://miloserdov.org/?p=3867
* https://www.npmjs.com/package/create-dmg