How to distribute your software

2006-01-16 00:05:00 UTC

Recently, I went to Apple’s games site and downloaded a bunch of puzzle/arcade games. I was dismayed to find that many of these games were distributed in formats other than UDIF (the .dmg format). So clearly this matter bears some explanation.

This is the second part of a two-part post. Part 1 came previously; it discussed the difference between compression, archive, and disk-image formats and described the different specific formats in each category. Part 2 covers why you should use a plain dmg (no StuffIt or *zip sprinkles) to distribute your software. This was originally one long post, but I Kill Billed it.


Part 2: How to distribute your software

The sad current state of affairs is that much software is not distributed in a plain dmg. Here’s a brief hall of shame, in increasing order of silliness:

I’m not singling any of these products out (especially for .dmg.gz, .zip, and .sit, as these are absurdly common), nor am I critiquing the quality of the software; these are just examples of how not to distribute your application.


Regarding the last one: StuffIt format? WHY?!?!?! Mac OS X doesn’t even come with StuffIt Expander anymore!

And it’s not even StuffIt X (that would be .sitx); .sit is the older StuffIt 5 format, that doesn’t properly support application packages! Worse: because StuffIt 5 format does not support storage of UNIX permissions, StuffIt Expander relies on a preference setting to know whether to set a file as executable or not. So if you UnStuff an application from a StuffIt 5 archive, it might not even run. Doesn’t that make a great first user impression? And who’s going to suspect that their unarchiver is the cause of the problem?

In fact, it isn’t the cause of the problem at all. If you are still distributing your software in StuffIt format, you are to blame.


Panther added support in the Finder for zipping and unzipping files. Tiger added support in the Finder for gunzipping, bunzip2ing, and untarring files. All of these features are the wrong way to distribute an application.

First off, tarring a dmg is pointless. tar files exist to put multiple files into one file. A dmg is already a single file. There is no need to tar it.

Second, if you created your dmg correctly, it is already compressed (probably with zlib). ‘Correctly’ means making a read-only compressed image, either from a folder or from another (read/write) image. There is no need to compress it further. Be very surprised if the additional savings exceed 20 K. (the .dmg.tar.gz listed above is particularly egregious — hello, Mr. Redundancy Man!)

Third, if somebody on Jaguar (or earlier) downloads your zip file, and you created it using Finder, it will not unpack correctly in StuffIt Expander. Specifically, it will create ugly ‘__MACOSX’ folders. Your application might work (unless you actually did intend to use the resource fork for something, in which case it’s gone then), but littering a user’s system is not a way to build goodwill.

Fourth, the purpose of Finder’s zip support is to allow you to send files to Windows users. Distributing Mac software does not count.

There is only one valid use for zip: getting around stupid web servers that either don’t allow dmgs (*shakes fist at GeoCities*) or that don’t have a proper media type (application/octet-stream) set for it. If you have access to add that media type, do so, and distribute a plain dmg; otherwise, politely badger your admin. And until such time as they fix it, you should include a note on your downloads page acknowledging that having to zip your dmgs is lame.


Lest this article sound completely negative, let me explain the upsides of using UDIF.

The major advantage is that it sandboxes your application. An application shouldn’t install anything outside of its bundle (are you listening, Adobe?). If your application is written correctly, it is self-contained (everything it needs is in the .app bundle — this is what bundles are for) and does not require write access to the volume it is on. If your application can be run without problems from the dmg, then you are doing all right.

The second advantage is that a dmg does not require proprietary software (i.e. StuffIt). This seems to be a bigger advantage than it should be — StuffIt does not come with the OS anymore, and requiring people to download other software in order to use your software at all is not a good way to make them fans of it. Disk Copy/Disk Utility has always come with Mac OS X.

(Before you bring up Growl: Growl isn’t required by most of the applications that use it; it’s just value-added. Those applications that do require Growl are aimed specifically at existing Growl users.)

Third: with a dmg, you can easily embed a license agreement. There is no need for an installer to display it; Disk Copy/Disk Utility will do it for you.


That gives me an idea. Here are a couple of points about installers.

Unless you are installing a framework (that really needs to be installed into a Library directory) or a kernel extension, do not create an installer or an Installer package. There is no point.

The user should be able to try your application without installing it (remember what I said about it being usable from the dmg?). An installer is a barrier to this. You should make it as easy as possible for people to try your app.

5 Responses to “How to distribute your software”

  1. Domain of the Bored » Blog Archive » Compression and archive formats: A description Says:

    […] Domain of the Bored The personal weblog of Peter Hosey, aka Mac-arena the Bored Zo. « Folding at home How to distribute your software » […]

  2. Scott Hicks Says:

    Peter:

    I applaud the post regarding compression and archiving and how to distribute software. I hope many people read and heed. This is probably the best thread on this subject matter. Thank you for writing it up. Here’s hoping kernelthread.org and maybe a few other popular information sources will solicit you to republish it.

    Thanks,

    Scott

  3. Dave Vasilevsky Says:

    Thanks for the analysis, but I’m afraid I disagree with the some of the conclusions. I’ve begun to prefer zip files for distributing software.

    It’s not horrible to use dmg files, but they suffer from being an opaque format. Windows and Linux (or even OS 9) users who find themselves with a dmg are left with no idea what’s inside. At least with a zip file they can read the Read Me and see whether it might be worth trying out my app on a Mac. Sometimes I find myself downloading a program just to check out some of the files in the bundle–images, scripts, etc–and it’s nice to be able to do that even if I’m stuck on a Windows box at a library. And if you’ve ever wanted to extract a dmg at the command line, you might have noticed how annoying it can be–but see undmg for an attempt to make it easier.

    Now with the recent security issue, I’ve noticed myself being more careful around dmg files from people I don’t completely trust, so I’m becoming even more hesitant to use them to distribute my stuff. As far as I can tell, a “regular zip” (not the Finder’s weird kind) should be able to hold most modern OS X apps, since resource forks are rare nowadays–and there doesn’t seem to be any real downside to that method. I guess I’d only prefer dmgs for apps with resource forks that are compatible with Jaguar.

    Somewhat off-topic, why do so many people not “internet-enable” their dmg files before distributing them? I’ve always found the open dmg => wait for it to attach => drag app to destination => eject dmg sequence to be tiring, and internet-enabled dmgs circumvent all that bother. Is there any disadvantage to them?

  4. Peter Hosey Says:

    Somebody on a Windows or Linux box can’t use the software anyway, and they should already know whether they want it or not from the webpage. As for people on Mac OS 9, that’s why you state the requirements for your software up front. If they can’t manage that, that’s their problem. :)

    The security issue is a non-issue for software developers. Apple will fix it, and the worry over it (which I think is confined to Mac exports anyway) will pass. I don’t think most people know about it, and legitimate developers won’t need to worry about it unless dmg exploits become rampant.

    undmg seems pointless to me. A tbz or zip would be smaller and achieve the same end. Same goes for internet-enabled disk images.

    The nice thing about internet-enabled disk images is that Safari will attach the disk image, copy the files from it, and detach and Trash the disk image for you. But it does the same thing for zips, and zips are smaller than even UDBZ dmgs. So you should just use a zip at that rate.

    I like the conventional disk image. I like how it isolates the app: If an app cannot run on an unwritable disk image (because it requires write access to itself or its parent directory), I consider it buggy and unworthy of my custom.

    Yes, I know that any app I run can write to my home directory. That’s not the point: I see an app demanding to be on the startup disk (probably so that it has write access to itself or its parent directory) as a critical design failures, probably the first of several. Good OS X citizens can run just fine from a disk image, which is why that’s my first test of the app.

  5. Yuhong Bao Says:

    I think that the .zip and .sit (or for that matter, .sitx) examples are not too bad (in fact, .sit was used before and still can be used for a Carbon or Classic application that does not use packages), but I agree that the other examples creates unnesserary indirection that just complicates extracting the app. And BTW, you can write a shell script called undmg that mounts the disk image (in /tmp, prehaps) and copy the files to the hard disk.

Leave a Reply

Do not delete the second sentence.