Top tips for packaging software

present.jpgBy Mike Jackson.

The first encounter a user often has with your software is when they download it as a package. The nature of this package, and what the users have to do with it, can make the difference between a happy user using your software for their work, and a frustrated user, who has wasted a morning, and is now looking elsewhere.

Here are our top tips for packaging software…

1. If you can, distribute a binary

If you can distribute a binary executable, your users will thank you. This might be an EXE file for Windows, or an executable JAR file, for example. But, if all a user has to do is double-click on a file or run one or two commands - whether that be a “yum install”, “easy_install” or “java -jar application.jar” - to install or run your software, then they’ll be off and running far more rapidly than if they first have to try to build it.

If you are providing a binary then make sure it’s clear what operating systems it can run on. Don’t just say “Linux” or “Windows” unless you’re sure it runs on all flavours of Linux or Windows, but rather state the versions you know it runs on for sure. For example, “Scientific Linux 6” or “Windows 2007”

2. If users must build source code, which is sometimes inevitable, then at least make it easy for them

It may not always be possible to distribute a binary executable, due to the complexities of certain languages and platforms. That, however, is no excuse for just giving the user source code and a short README that just says “Run ./configure then make it install”. Building code from source can be an intimidating and error-prone experience, and at the first sign of trouble a user may just stop and look for another tool elsewhere, or they may struggle for a while, then stop anyway.

If your software has many configuration options, it can help to provide, via a README, a default set for new users rather than barraging them with every possible option at the outset. Likewise, it can be very useful to provide some information on what might go wrong during the build and how these can be fixed. For example, advice like “if you see the error ‘library not found’ then …” to help users recognise and recover from any errors. Likewise, documenting where things go after they’ve been installed can help users, especially if things go wrong. (So they can check if things were put in the expected places, for example.)

If your software relies upon third-party packages then either bundle these, or at least, make sure they are well documented, including their version numbers and the URLs where they can be downloaded. Remember, your goal is to get the user using your software for their work as quickly as possible.

3. Don’t neglect Windows

It’s a hard fact to face, and some Linux aficionados may cringe at the thought but there are a great many Windows users out there, and not just among the general public but in research too! So, if possible, make sure you cater for these users when providing binary distributions, or documenting how to build your source code.

4. Remember your users may not be super-users

Administrator privileges are often a barrier to using software as not all users may have these. If possible, ensure that your software can be installed and run without the need for super-user or administrator privileges. This can be done by allowing users to specify where your software is installed to so they can install it in their home directory, rather than a standard systems directory, if required.

5. Ensure ZIP and TAR files unpack to a single directory

If you intend to bundle your software as a zip or tar file (or any archive format), it is safer to pack it as a single directory and then name the bundle after the directory. For example, put all the files in ssiproduct-1.3.23/ and then zip or tar the directory to create ssiproduct-1.3.23.zip (or ssiproduct-1.3.23.tar). If you simply zip up all the files from a directory, then when a user will find the files spread all over their current directory when they unpack the bundle. The user then has to waste time cleaning up their directory. Or worse, the user’s files may be overwritten by your unpacked files if they share the same names.

6. Make it easy to get the package

There are great packages out there but sometimes they can be difficult to find and are often buried deep within the pages of a web site. Having to play “hunt the package” is no fun for the users. Nor is expecting users to e-mail you and then wait for the package when you finally get round to reading the message. A user actively seeking your package wants it as soon as possible, so make sure your software is readily downloadable from your web site and it’s clear where the download link is. This is one of the great things about SourceForge, for example, where project pages have a big green Download button!

You may also wish to check out our top tips on releasing software.

Posted by s.crouch on 13 May 2013 - 5:29pm