# Styling of DMGs on macOS

On macOS, software is usually delivered as a DMG. DMG stands for "Disk image" and contains a file system that can be mounted, rather than an archive that can be extracted. When the user double-clicks on a DMG file in the Finder, it is mounted to `/Volumes/[volume name]` and a new Finder window is opened for the mount point.

The Finder can be styled on a per-directory basis, and the information about that styling is saved to a file named `.DS_Store` in every directory. This means that you can ship styling information with a DMG file. Styling includes setting a background image for the Finder window, and that image file can be added to the DMG as well.

For single bundle GUI applications, a styled DMG generally includes a symbolic link to `/Applications` in the top-level folder of the DMG, so that user can drag the application bundle into the default installation directory with minimum effort. To make this process easy for you, install4j applies standard styling to generated DMGs by default. Standard background images are used, and the application or installer icons are positioned accordingly. Also, for single-bundle archives, a symbolic link to `/Applications` is added automatically.

![](../images/ui/dmg_styling.png)

### Custom styling

To customize styling options, go to the "DMG styling" step of the media wizard and select "Custom styling". Then you can select your own background image as well as the position of the application or installer icon. Window bounds, icon sizes and text sizes can also be configured.

install4j allows you to add any number of files and symbolic links to the DMG. In the "Additional DMG files" sub-step of the "DMG styling" step, you can add files and symbolic links. When applying custom styling to single-bundle archives, you can add a link to `/Applications` here. The icon position is specified in the configuration dialog of the symbolic link.

### Manual DS_Store creation

For advanced use-cases, you can create your `.DS_Store` on a macOS machine where install4j is installed. This requires the "No styling" option to be selected on the "DMG styling" step of the media wizard. Note that this is not a recommended approach, but is documented here because it used to be the only way of applying DMG styling in earlier versions of install4j and remains an option for achieving a level of customization that is not available with the "Custom styling option".

1. **Compile DMG** — The first step is to compile your macOS media file from install4j without any custom styling. This DMG will be the template for which we will define the style. You cannot use just any other DMG, because each media file has a unique ID. When using background images, the `.DS_Store` file must have been created for a DMG with the same ID, otherwise the image will not be found reliably.   When you recompile the media file in install4j, this ID remains the same, so you can add the `.DS_Store` file from a previously compiled DMG to the additional DMG files in the media wizard.
2. **Convert the read-only DMG to a writable DMG** — The generated DMG is a read-only image. To make any modifications at all, we have to convert the DMG to a writable format.   First, make sure that the DMG is not mounted. In a terminal, cd to the directory where the DMG was created and execute   hdiutil convert hello.dmg -format UDRW -o hello_rw.dmg   where "hello" has to be replaced by the actual name of your media file. Note that the last argument has "_rw" appended at the end, because the output DMG must be different from the input DMG.
3. **Enlarge the writable DMG** — By default, a DMG generated by install4j is full. It is not possible to add any more files simply because the file system in it has no more available space. To enlarge the DMG, we first determine its current size by executing   hdiutil resize hello_4_0_rw.dmg   The "cur" column of the output shows the number 512-byte sectors. To add about 10 MB, we add 20,000 to that number and execute    To check the new size, run   hdiutil resize hello_4_0_rw.dmg   again.
4. **Mount DMG** — We now mount the read/write DMG by executing   hdiutil attach hello_4_0_rw.dmg   and note the mount point /Volumes/[volume name] that is given by the output of the above command.
5. **Copy background image to DMG** — To add a background image, we first have to copy the image to the DMG. We do not want the image file to show up in the finder, so we create a hidden directory in the DMG. To do that, we execute   cd /Volumes/[volume name] mkdir .background   To open this hidden directory in the Finder, we execute   cd .background open .   Now, we open another Finder window, locate our background image and copy it to the hidden directory that is visible in the original Finder window.
6. **Select background image for DMG top-level folder** — Because we need the Finder with the hidden directory in a minute, we leave it as it is, and double-click on the mounted volume on the desktop to open the default Finder window for the DMG. We position the new Finder window side-by side with the Finder window that shows the hidden directory.   To start changing styles, we invoke **View → Show View Options**. This will show a tool window with styling controls. In the "Background" section, we choose "Picture" and notice the drop target for a picture file.    Now we have to perform a somewhat tricky operation. From the Finder window that shows the hidden directory, we drag the image to the mentioned drop target in the view options dialog without activating that Finder window (otherwise the view options dialog would change its target folder).   Finally, we see can see the background image applied to our read/write DMG.
7. **Adjust DMG finder window** — Two properties of the Finder window should be adjusted: Invoke **View → Hide Toolbar** and resize the window so that it fits the size of the background image.
8. **Add link to /Applications for single-bundle archives** — If you have a single-bundle archive media file type, you probably want to add a drop-target for the installation. In the terminal, we execute   cd /Volumes/[volume name] ln -s /Applications " "   This creates a link with an empty name that immediately shows up in the Finder window. The empty name is a good strategy to get around localization issues. The Applications folder has a special icon and is easily recognizable, so a name is not necessary.
9. **Adjust icons** — Now you can position the icons as needed and adjust the "Icon size" property in the view options dialog until they fit with your background image.
10. **Extract .DS_Store file** — The result of your work above is the `.DS_Store` file in the top-level folder of the DMG. Go to the terminal and copy it to your project folder so that you can reference it in the install4j IDE:   cp .DS_Store [project folder]/DS_Store   Note that we have omitted the leading dot before DS_Store in the target path. This makes it easier to work with the file and prevents confusion with the Finder.

At this point, our work with the read/write DMG is finished. We should now delete it and also remove it from the Trash. If we don't do this, subsequent tests will automatically mount this DMG again. This is due to the "alias" feature in macOS. The .DS_Store contains an alias to the configured background image and as long as the original DMG still exists somewhere, it will open it from the template DMG instead of from the newly generated DMG.

In the media file wizard of the install4j project, we can now use the generated `.DS_Store` file. On the "DMG styling->Additional DMG files" step we enter the `[project folder]/DS_Store` and give it the name `.DS_Store` in the DMG.

The background image is added with the name `.background/[image name with file extension]` where the image name must be the same as on the read/write DMG. The `.background` folder will be created automatically.

If you have added a symbolic link to `/Applications`, you can add a corresponding symbolic link entry here, the name should also be set to the same name as in the read/write DMG. An empty name is entered as "" (with the quotes).

![](../images/ui/dmg_styling_files.png)

With the above files and symbolic links a newly generated DMG will look the same as the read/write DMG where the styling was added. When you tweak your styling in the future, you don't start from zero but with the styles that are already present in the generated DMG.
