Porting software to MINIX from Linux or FreeBSD is non-trivial in most cases, but not exactly rocket science either. A major part of the work often has to do with altering/extending makefiles or build scripts. Recoding major parts of a piece of software generally is required for only software that does some or all of its work in kernel space. You can help MINIX by porting packages!

For starters, read POSIX and MINIX, Programming in MINIX, and Testing Pkgsrc. The information shared on those pages is partially redundant.

This page shall serve as an entry-point for developers wishing to port POSIX applications (e.g., from Linux) to MINIX 3.

A fair number of applications already were ported, thanks to the efforts of our contributors. Check out MINIX 3's download areas for ported packages before trying to do any port; and, see whether your favorite package already is available.

If not, follow this recipe:

1. Post to the MINIX newsgroup, and inform your fellow programmers about your intention. Perhaps, somebody already is working on your package.
2. Download the source of your app.
3. Modify the source code to make it compile and run on MINIX 3.
4. Notify the MINIX 3 maintainers about your success. Notify the upstream package maintainers. Perhaps, they would like to include your patches in the original distribution.
5. Send in the package for inclusion on the website and/or the official repositories.

• Add a .descr file, containing a one-line package description. (When packman shows a list of packages, it displays short descriptions on the right-hand side. They came from those packages' .descr files. So, they are good examples of what you should put into that file.)
• Add a readme.txt_Minix3 or similar file, documenting your patch. You should include contact information. (See other packages.)
• Add a build.minix shell script. (See other packages.)
• Do not package generated files.

Several packages were portable from the start; that is, no source files needed patching, in order to compile under MINIX 3. You can use these packages as references for portable coding practices:

CSSC ascii atk automake avra bc bchunk bcrypt btyacc
catdoc cpio ctags diffutils libiconv libmcrypt libpng
links lzo lzop m4 mdf2iso nano nasm neon nomarch
pkg prng pstotext psutils readline rman sed slang slrn
src2tex wdiff webcpp whichman zlib

First, get the configure script to run. Some scripts use shell features not supported by the ASH shell that is the default in MINIX. In that case, use another shell, such as BASH. Similarly, the make which comes with MINIX also has some limitations. If it gives any error messages, try using GNU Make (gmake) instead.

As AST points out in his very recommended talk on Fosdem, most configure scripts are buggy. Have a look at this Tutorial on debugging configure.

At the least, you probably will need to add detection of the uname string returned by MINIX. That case often can be handled in the same way as other POSIX systems, such as Linux and BSD.

Attempt to compile the program. If you encounter many unexpected syntax errors, the source code might rely on C99 features or GCC extensions of the C language. One typical example is using // single-line comments rather than /* … */ comments. The single-line comments are allowed in C99; but, ACK does not implement the C99 standard unfortunately. In such cases, it's best to compile the program with GCC.

At first, do not implement missing library functions, but only declare them in header files. That way, you will be able to see which are the most important missing functions, before doing much work. Based on the missing functions, it then is possible to determine whether or not porting is feasible. For example, it might not be possible to port programs which use threads or memory-mapped files, without fundamental changes. Such ports can be delayed until the required functionality is available in MINIX. In that case, you may add both the port and the missing features to the wish list, specifying that the unavailability of the latter blocks the former.

If you added declarations, as recommended in the previous section, eventually you will receive a linker error showing which symbols were used but not defined. That would be the time to implement those missing library functions, preferably in such a way that they easily can be moved into the MINIX libraries, later on. The man pages on the Open Group website are a good source of information about what such calls should do exactly.

Warnings emitted by the C compiler are a good source of information on what might be wrong in the program you ported. It is preferable to eliminate all warnings, as that might save you a great deal of time on testing. Although cc provides some warnings, do attempt to compile your program in gcc with the -Wall -W flags, for maximum compiler assistance.

Testing and fixing bugs can take considerable time for software with poor portability and software that uses features missing in MINIX. Often, programs come with test suites that provide a good starting point.

• The gnutools are located in “/usr/gnu/bin”; you might need to adjust the PATH in the Makefiles.
• Add a “README_Minix.txt” file, documenting your changes, esp. with respect to MINIX 3 specialties.
• Use gar, instead of ar, when making GCC libraries.
• If you install libraries, for other programs to use, then put libraries built by cc into /usr/local/lib/ack/; and, put libraries built by gcc into /usr/local/lib/gcc/.
• Don't comment out code – use preprocessor conditionals instead. The __minix preprocessor symbol indicates when C code is being compiled on MINIX.
• In some Makefiles, “-funsigned-char” was added to the CFLAGS.
• Bitfields are not recognized natively for cc programs. You can use the GCC compiler; or, you can remove the bitfields in structs – if the data structure doesn't need to conform strictly to the hardware or memory layout, then it's harmless.
• Try to be as unobtrusive as possible, to enhance your chances for inclusion in the upstream package.
• Please comment your patch inline.
• ioctl() and setsockopt() are common sources of portability problems. Calls may be defined even though they have limited or no implementation; so, you may want to check all of those calls, in advance. In particular, make sure that each call is checked properly for error results.
• The recv(), send(), recvfrom(), sendto(), recvmsg(), and sendmsg() calls do not support flags on MINIX.
• recvmsg() and sendmsg() only support unix domain sockets. Calling these functions with internet sockets will result in an error (return -1 & errno ENOSYS).
• Because there is no dedicated loopback device, it is not possible to have a server listening on localhost (127.0.0.1). If you encounter that problem, you can listen on INADDR_ANY instead; but, note that it works only if there is a network connection (note that, for example, the X Window System cannot be started without one). Also, think through the security implications of accepting non-local connections.
• Use the latest version of MINIX. That makes the package more useful; and, provides you with the latest features.
• If you use GCC, it is possible to use the 64-bit long long type on MINIX. However, it is not supported by library routines; and, might be truncated when used. Be sure to test for values over 2^32^, in that case.