User Tools

Site Tools


releases:3.2.0:developersguide:portingguide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

releases:3.2.0:developersguide:portingguide [2014/11/11 14:52]
127.0.0.1 external edit
releases:3.2.0:developersguide:portingguide [2014/11/14 18:01] (current)
lionelsambuc
Line 1: Line 1:
 +====== 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
 +[[.:​testingpkgsrc|Testing Pkgsrc]]. ​ 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. ​ 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:
 +
 +  - Post to the MINIX newsgroup, and inform your fellow programmers about your intention. ​ Perhaps, somebody already is working on your package.
 +  - Download the source of your app.
 +  - Modify the source code to make it compile and run on MINIX 3.
 +  - 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.
 +  - Send in the package for inclusion on the website and/or the official repositories.
 +
 +===== Recommendations for packagers =====
 +  * 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.
 +
 +===== Random notes from existing ports =====
 +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:
 +
 +<​code>​
 +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
 +</​code>​
 +
 +===== Recommendations for porters =====
 +
 +==== Configuration ====
 +
 +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 [[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 ====
 +
 +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 [[:​wishlist:​|wish list]], specifying that the unavailability of
 +the latter blocks the former.
 +
 +==== 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. Although //cc// provides some warnings, do attempt to compile your program in
 +//gcc// 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 ====
 +
 +  * 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 **<fs big>''​__minix''</​fs>​** preprocessor symbol indicates when C code is being compiled on MINIX.
 +  * In some Makefiles, "<​fs big>''​-funsigned-char''</​fs>"​ 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.
  
releases/3.2.0/developersguide/portingguide.txt · Last modified: 2014/11/14 18:01 by lionelsambuc