README
node-appdmg
Generate beautiful DMG-images for your OS X applications.
Installation
npm install -g appdmg
Usage
appdmg <json-path> <dmg-path>
json-path
: Path to the JSON Specification filedmg-path
: Path at which to place the final DMG
Test
To produce a test DMG to your desktop, run the following command:
appdmg test/assets/appdmg.json ~/Desktop/test.dmg
JSON Input
The JSON input for the image follows a simple structure. All paths are relative to the JSON file's path.
Example
{
"title": "Test Application",
"icon": "test-app.icns",
"background": "test-background.png",
"contents": [
{ "x": 448, "y": 344, "type": "link", "path": "/Applications" },
{ "x": 192, "y": 344, "type": "file", "path": "TestApp.app" }
]
}
Specification
title
(string, required) - The title of the produced DMG, which will be shown when mountedicon
(string, optional) - Path to your icon, which will be shown when mountedbackground
(string, optional) - Path to your backgroundbackground-color
(string, optional) - Background color (accepts css colors)icon-size
(number, optional) - Size of all the icons inside the DMGwindow
(object, optional) - Window optionsposition
(object, optional) - Position when openedx
(number, required) - X position relative to left of the screeny
(number, required) - Y position relative to bottom of the screen
size
(object, optional) - Window sizewidth
(number, required) - Window widthheight
(number, required) - Window height
format
(enum[string], optional) - Disk image formatUDRW
- UDIF read/write imageUDRO
- UDIF read-only imageUDCO
- UDIF ADC-compressed imageUDZO
- UDIF zlib-compressed imageUDBZ
- UDIF bzip2-compressed image (OS X 10.4+ only)ULFO
- UDIF lzfse-compressed image (OS X 10.11+ only)
contents
(array[object], required) - This is the contents of your DMG. +x
(number, required) - X position relative to icon center +y
(number, required) - Y position relative to icon center +type
(enum[string], required) +link
- Creates a link to the specified target +file
- Adds a file to the DMG +position
- Positions a present file +path
(string, required) - Path to the file +name
(string, optional) - Name of the file within the DMG
0.1.x
used a different JSON format. This format is still supported but
deprecated, please update your json.
Retina background
Finder can display retina backgrounds if packaged correctly into a .tiff
file. appdmg
will do this for you automatically if it can find a file
with the same name as the background appended with @2x
.
E.g. if the json contains "background": "TestBkg.png"
then add a file
with the name TestBkg@2x.png
into the same folder.
API
The application can also be called from within another javascript file, example:
var appdmg = require('appdmg');
var ee = appdmg({ source: 'test/appdmg.json', target: 'test.dmg' });
ee.on('progress', function (info) {
// info.current is the current step
// info.total is the total number of steps
// info.type is on of 'step-begin', 'step-end'
// 'step-begin'
// info.title is the title of the current step
// 'step-end'
// info.status is one of 'ok', 'skip', 'fail'
});
ee.on('finish', function () {
// There now is a `test.dmg` file
});
ee.on('error', function (err) {
// An error occurred
});
You can also pass in the specification directly instead of reading it from a file. basepath
should be a path which will be used to resolve other paths in the specification.
var ee = appdmg({
target: 'test.dmg',
basepath: __dirname,
specification: {
"title": "Test Title",
// ...
}
});
OS Support
Currently the only supported os is Mac OS X.
Track the status of this here: https://github.com/LinusU/node-appdmg/issues/14
Hidden files
By default hidden files will show for users with com.apple.finder AppleShowAllFiles
set to TRUE
. This can be worked around by moving all hidden files outside the initial
window size (using "type": "position"
), this has the side-effect of enabling a scrollbar.
Files to usually move:
.background
.DS_Store
.Trashes
.VolumeIcon.icns
Alternatives
- create-dmg, a Bash script
- dmgbuild, a Python version