This shows you the differences between two versions of the page.
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. | ||