Software submission howto

modified: 7 May 2006

How to submit a package for the minix1 contributed software area:

Anonymous uploads by FTP are not allowed, but you may e-mail a uuencoded (see the uue(1) man page) tarred and compressed file to me at asw@woodhull. If you have another way (for instance, an ftp site where I can upload from you) please send me e-mail to make arrangements. Please contact me in advance before mailing me any really long files (>200K). I may be able to accept a moderately large file submitted as e-mail if I am alerted in advance. Most e-mail servers have a limit on message and file sizes, however, so it may be better to arrange to transfer by ftp, either to a directory I enable for an ftp upload or by my downloading from an ftp site to which you have upload access.

Tar(1) archives compressed with compress(1) are preferred. They may be named with .tar.Z or .taz suffixes as you prefer (the latter is helpful in dealing with the Minix 14 character file name length limit). The archiving and compression should preferably be done on a Minix system, to guarantee that Minix users will have no difficulties unpacking . If you expect your contribution to be useful to users of 16-bit Minix please use 13-bit compression. Minix uses 13-bit compression by default, but Linux and other Unix versions use 16-bit compression.

If you have a really big file you can submit it as a gzipped (.gz or .tgz) archive. Gzip compresses more efficiently than good old Unix-style compress; however, gzip is not part of the standard Minix distribution, and people who want a gzipped file will also have to install gzip (it's available for Minix from Terry McConnell's site, or here so it's not really a problem, but possibly an inconvenience).

If your contribution is a utility designed to run under MS-DOS or Windows (or to support Minix-under-DOS) you may send a .zip file.

Original uploads will generally be placed in the pub/contrib/ directory.

The descriptive text file:

You should also submit a short text file explaining your contribution. An index of the text files describing contributions can be accessed here.

This is important! If you don't submit such a file I won't post your contribution until I have written one myself, and you might not like the way I write it. (I might edit yours, too, but if you submit one yourself the result will probably be more correct than if I write it all.) Also, sometimes I get behind in my real work and then your contribution might not be posted for a while if it doesn't include the descriptive file.

Please look at the existing descriptive files. There are some good and bad examples. Please try to emulate the good ones! Basically, you should put information in the first two lines stating the name and purpose of the package, the version, the release date, and the author's name and e-mail. The file should be plain text, with a filename ending with a .txt suffix. I periodically run a script that extracts the first two lines of .txt files in the contributed software directory and builds the master index automatically. The file should also be short, ideally short enough to appear within a browser window without scrolling. The filename should be identical to the name of the complete package except for the suffix (for example, package01.txt and package01.taz, so a directory listing will sort descriptive files and the packages they refer to together). Finally, the name of the file to download for the complete package should be in the text file, preferably near the top, to make it easy to cut and paste into the browser.

Package preparation:

Assume that your contribution will be improved sometime, by you or someone else. Assign it a version number and incorporate that in the file names, for instance newprog01.txt and newprog01.taz for release 0.1 of your masterpiece. It's also a good idea to make sure you have date and version information in both source and binary files. It can be very helpful to have a way to know which version is in use.

If you are modifying something developed by someone else don't increment the version number without consulting with the original author or the current maintainer. Instead, add a suffix letter (i.e., package01a) to indicate this is a modification of an existing package. You should also try to contact the author or maintainer, it would be much better for everyone if your modifications are folded into the next official release.

The Minix 14 character filename length limit makes it difficult to make file names as informative as might be desired. Try to think about how you will name the next release and devise a name that make it easy for someone looking at a list of files to see which one is newer. Also, if you have reason to package seperate source and binary versions of a package (usually only desirable when importing a really big program, such as perl or lynx), put an 's' or a 'b' in the filenames -- and also explain this in the descriptive text.

In preparing a package for others, create the tar archive so it includes a directory whose name incorporates the version number (so when you unpack package01.tar.Z it will create a new package01/ directory with all the files in that directory, rather than overwriting an existing package/ directory or dumping the files into a home directory). Explain this in your descriptive text. Normally users should install downloaded source code packages in the /usr/local/src tree, but you should not create a package that includes an absolute path name -- let the user decise where to put it.

It's also nice if you include a Makefile and a man page. The Makefile should have an install: target that installs the new binaries into /usr/local/bin and and an installman: target that installs the man page into a directory in the /usr/local/man tree. These features are not essential, but a man page makes it easier for someone else to figure out how to use your contribution. And installing into the /usr/local tree makes it easier for users to install custom software in a standard way that won't get messed up when Minix itself is upgraded and the standard /usr/bin and /usr/man directories are replaced.

Copyrights, permissions, and use

I expect that any offer of material to be posted on my site implies that you have the right to make such an offer, whether it be documentation or software in binary or source form.

Open source programs often include work of many authors. Any source code that is not original should retain the original copyright and you should be sure that incorporating it in new work is OK under the terms of the original copyright. For the original parts of your programs I encourage you to be sure your name appears on every source file and is also embedded in executable files, whether or not this information is displayed when the program is run. Your name and contact information and the date should also be added as a comment to any source file you modify. It's also a courtesy to let the authors or current maintainers of a modifed work know about your improvements, they may want to put them into the next official release.

I have defined a copying policy (click here) for material on my sites. In summary, permission is granted to copy anything written by ASW unless otherwise noted, but attribution and preservation of authorship and copyright information are requested. Permission is not automatically granted to copy items identified as authored by others, it must be asked of the original contributor unless explicitly granted in the contribution. You are encouraged make your own policy clear in anything you contribute.


All material on this site not otherwise attributed is copyright ©1994-2006 Albert S. Woodhull
Click here for information on copying and other use.
Mail comments on this page to: Al Woodhull <asw@woodhull.com>
[Viewable With Any Browser]
Valid CSS!
[Valid XHTML 1.0!]