====== Porting Guide ======
===== Porting Guide Introduction =====

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 [[.:posixandminix|POSIX and MINIX]], [[.:programmingminix|Programming in MINIX]], and
[[.:pkgsrcguide|Pkgsrc Guide]]. The [[:Wishlist:]] may also be helpful for identifying functionality that hasn't been implemented in Minix yet. The information shared on those pages is partially redundant.

====== Porting Posix applications to Minix3 ======

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. Before you begin porting any application, check to see if it's already been ported. A list of packages known to compile and work is in pkgsrc in a file called [[http://git.minix3.org/?p=pkgsrc.git;a=blob_plain;f=minix/limited_list.pbulk;hb=refs/heads/minix-master|limited_list.pbulk]].

If the application hasn't been ported yet and it doesn't work 'out of the box' via pkgsrc, follow this recipe:

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

===== Recommendations for porters =====

==== Use pkgsrc ====

pkgsrc is configured with the right settings to make source code happy. The right defines are set (-D_NETBSD_SOURCE -D_POSIX_SOURCE -D_COMPAT_MINIX) with the right additional libraries (-lcompat_minix -lminlib) as well as dependency checking and patches. So start off on the right foot and start your porting effort with pkgsrc.

==== Configuration ====

As AST points out in his very recommended talk at [[http://fosdem.org/2010/schedule/events/867|FOSDEM]],
most configure scripts are buggy. Have a look at this 
[[http://www.ibm.com/developerworks/linux/library/l-debcon.html|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.

==== Compilation ====

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 [[:wishlist:|wish list]], specifying that the unavailability of
the latter blocks the former.

If the program can be made to work without the functions/headers, it is usually best to add autoconf checks for the features/headers and then using the generated macros (example: HAVE_SETPGID, etc). This solution is much better than simply adding ifdef ''%%__%%minix'' everywhere. Using the autoconf feature checks will allow the packages to take advantage of new features in Minix when they are introduced with a simple re-compile (instead of another set of patches to remove ifdef ''%%__%%minix'').

==== Linking ====

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
[[http://www.opengroup.org/onlinepubs/000095399/|Open Group website]] are a good source of
information about what such calls should do exactly.

==== Eliminating warnings ====

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. Do attempt to compile your program with the<fs big>'' -Wall''</fs> <fs big>''-W ''</fs>flags, for maximum compiler assistance.

==== Testing ====

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.

==== Random notes ====

  * Don't comment out code -- use preprocessor conditionals instead. Autoconf feature test definitions are best (example: HAVE_FOO, etc). The **<fs big>''%%__%%minix''</fs>** preprocessor symbol indicates when C code is being compiled on MINIX -- avoid ''%%__%%minix'' if Minix might one day get the ability to use the code you are blocking out.
  * In some Makefiles, "<fs big>''-funsigned-char''</fs>" was added to the CFLAGS.
  * 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.