Tokonoma.de

Adventures in Minix Land

Introduction

This paged was moved into the Minix3-Wiki. Go there for the current version!

I am a Linux user. I began using Linux, when it didn't quite work. I fondly remember the times, when I had to re-compile the kernel every once in a while. I had some time at hand and could fiddle around with it. Today I am a father of two and have a full-time job. No more fiddling, but that's ok, because Linux (the system, that is) is working out-of-the-box nowadays. There is hardly any plumbing necessary any longer if you don't have special requirements. I support the GPL and freedom and such. Anyway, Linux is not my topic in this document.

Minix was something un-free and therefore irrelevant to me in the past. When I found out, that Minix3 switched to a BSD-ish license my interest awoke. I read some of the papers on their website and thought: My, that's terrific. I want to try that. Then I found that, although Minix3 is POSIX compliant, there is no such thing as a user-friendly distro. It's mainly a developers toybox. OK, you can run apache, but I use my desktop like a desktop-user, that means: Webbrowser, Mail, CD-burning and so on. The screenshots on the Minix3 website look like fvwm in the early nineties. Now that's what I call an opportunity! It will be possible to build a user-friendly and rock-solid Minix3-distro from scratch with all the splendid tools that are avaliable today. (OK, I have to admit, Linux runs rock-solid for me. I haven't had a Kernel Oops for years now, and the last one was due to bad hardware.) Most Perl/Python based solution should be portable with hardly any effort. But, first things first.

Looking the the applications page, I found that a ridiculous small number of packages for Minix are available. Since they are linked on that very page, I assume that the standard packages on the applications homepage will not work. They are "patched" or "ported".

If Minix wants to attract users and developers, porting applications to Minix must be simple, easy and supported by tool-chains. Ideally it would be possible to use the original tarballs from the projects homepages, instead of patched versions. I also like the FreeBSD ports approach, but I was never patient enough to install Gentoo-Linux.

Problems

I know how to code in C, but I have only little experience with kernel programming. Thus, I need some good documentation to get started porting applications to Minix and adapting source to the initricacies of Minix' low-level functions.

But,

  • there is no documentation, no manual, no how-to, no nothing.

  • Existing packages do not concisely document how they needed to be patched

Debian is a good example, how to handle packages with respect to upstream. On the packages page you can find the original tarball and the patched one. The changes are easily traced. Now Debian is a monster project. It grew organically. You cannot and should not replay that. Perhaps there can be a Debian on Minix project?

To get a foot in the door, I want to concisely describe how the existing Minix-ports were done by examining the patches applied to the original packages. Then I will try to generalize the findings by collection and explanation of the found patterns. The consideration of these patterns should allow developers two things:

  1. Port existing programs to Minix.

  2. Create programs that support Minix from the start.

My quest starts with examining the differences between several arbitrary original and

patched tarballs in a tabular fashion.

When writing this introduction, I have no idea, what I will find, or whether my quest will be successful, but since we're Real Programmers, we are not afraid to learn…

A Systematic Approach

To set out for my quest, I had a look at the minix-applications page and collected the URLs to the archives mentioned there. Then I browsed the internet for the original source-packages and downloaded all mentioned tarballs. (I pasted all URLS in one plain text file and retrieved them with wget -i). Then I ran "diff" on all original and minix-folders.

The results are documented here.

I had to drop several packages, because I could not find the appropriate original source.

Analysis of VIM

Analysis of WGET

Porting pcal

Documented packages

These packages have a readme.minix file.

diffutils lynx2 patch pce pdksh perl php prng python readline tcl8 unzip

An exemplary port was done for patch (thanks to dcvmoole), where the necessary change was explained in detail in the readme-minix3 file.

Portable packages

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

These packages are minix-capable without any change in the source-files. They add only the .descr and the build-script to the original source-package. Some add a Minix-specific Makefile.

Most other packages tweak only Makefiles, shell-scripts, documentation. In most packages automatic SCM comments have been changed. This does not necessarily imply that the porting is trivial. Setting the correct environment variables in the Makefile or tweaking of the memory settings might still prove difficult.

Random notes from various packages

In package unrtf, we find the following diff in file malloc.c

« #include "malloc.h" » #include «malloc.h»

In package cvs, we find the following addition in cvs.h

#ifndef S_ISSOCK #define S_ISSOCK(x) 0 #endif

But why?

And client.c adds

#include «sys/select.h»

Recommendations for porters

General tips:

  • When commands are referred to with hardcoded paths in the Makefile, you need to adjust the path often, since many commands are found in /usr/gnu/bin. I really think that this is an arbitrary design decision.

  • Do not package generated files.

  • Add a README_Minix.txt file that documents the patch.

  • Document crucial lines, don't use literals.

BAD: chmem =1200000 $(DEST_BIN)/$(VIMTARGET) GOOD: MINIX_STACKSIZE = 120000 # We need 120k, because of foo. chmem = $(MINIX_STACKSIZE) $(DEST_BIN)/$(VIMTARGET)
  • The type off_t is typedef'd to unsigned long in Minix3. If you need to rely on the sign, you need to replace with long.

  • When modifying code, don't change the original code, but add your code and activate it through preprocessor variables. This will keep the code working on the original platform and allow upstream maintainers to incorporate the changes more easily, so that you don't have to fork.

  • Do not disable code in Makefiles by commenting it out. Use conditionals again. Exception: When using a Makefile.minix, strip all code, that is non-minix.

  • Use gar instead of ar

Some Makefiles modified CFLAGS = @CFLAGS@ -Wall -funsigned-char

"-funsigned-char" was added to CFLAGS

Final thoughts

After comparing some packages, I think that porting to Minix is actually quite simple as required in the preliminiaries. Perhaps it can even be done mostly automatic. The future will tell. Stay tuned for another edition of "the incomplete guide for minix porters".

Can you contribute to this document? Write to stefanDOG@tokonoma.de and remove the animal from the mail address.

This document is still in its infancy and published in the spirit of "release early, release often", so critic and helpful comments especially on the specialties of Minix are appreciated.

File last modified: 19:14:22 18-Aug-2009