Step by Step porting Guide for NetBSD userland

Step by Step porting Guide for NetBSD userland written by zacts.

Note: This tutorial assumes familiarity with the UNIX command line, git, email, and how to install an OS into a virtual machine. Also, I may update my blog entries from time to time for updates.

Importing NetBSD commands into minix3 is simpler than you might initially think. Once you understand how the process works of modifying the correct files, crossbuilding the minix.git repo, and using git to format and send a patch, you should have no problem importing new simple NetBSD commands.

For this tutorial, you will want to read the wiki page describing how to import NetBSD commands into minix3 Porting the NetBSD Userland.

First, we must clone the minix.git repo by issuing the command:

git clone git://git.minix3.org/minix.git

We now want to clone the latest minix3 netbsd.git repo.

git clone git://git.minix3.org/netbsd.git

Note: you may also use

git remote add netbsd git://git.minix3.org/netbsd.git

git remote update

within the minix repo to keep everything together.

For this step, decide on a NetBSD utility you want to import into minix3. You should check the official wiki guide listed above, Porting the NetBSD Userland, and scroll down to make sure you aren't duplicating work that someone else is working on. Another consideration is to know your skill level, in terms of understanding C, UNIX, POSIX, and the Minix3 codebase. You may want to chat with the Minix3 developers on the official minix3 mailing list if you have questions regarding which command you should import, and what all would be involved in doing that: Minix3 Google Groups.

Next we will actually copy the NetBSD command into the proper subdirectory of the locally cloned minix repo. There are several possibilities here; the command will probably be in either the netbsd/bin, netbsd/usr.bin, netbsd/usr.sbin subdirectories. In some cases the tool may be found in one of the extern/* subdirectories. When you find out which directory your command is located, you must then copy it into the corresponding minix/bin, minix/usr.bin, minix/usr.sbin, extern/* directory.

Now we must add the newly imported command into the Makefile for the corresponding minix/bin, minix/usr.bin, or minix/usr.sbin directory that we copied the NetBSD command into in the previous step.

These commands must be listed in alphabetical order within the Makefile.

At this point you will need to remove the directory within minix/minix/commands containing the NetBSD command, and you will also want to remove the command's entry in the minix/minix/commands/Makefile.

Find if the command has a man page listed within one of the minix/minix/man/ subdirectories, and then remove the .1 man page. Also, you will need to remove the corresponding man page entry from the Makefile in the same directory of the old man page.

Add entries for the proper locations of the imported NetBSD command. Also, make sure to put the word obsolete after the entry for the old command unless the new command's location is the same as the previous command's location, and if both the old and new command share the same name.

Note that since the Minix 3.3.0, the single mi file has been split among multiple minix-*/mi files. You will have to find the right subfolder to edit the mi file for your file(s) that changed.

If the old minix command had a different install path, i.e. /usr/bin/sleep instead of /bin/sleep, then git grep the old path:

git grep '/usr/bin/sleep'

Remove any old invocations of the old path, unless it is part of a test suite or another NetBSD command that references the old path in the original upstream source code for that test suite and/or command.

Note: This step should work on most Gnu/Linux distros, along with FreeBSD. For this next step, make sure you have the required build dependencies installed: gcc, g++, gnumake, binutils, zlibc, zlib1g, zlib1g-dev, and curl. If you have any problems ask the minix3@googlegroups.com mailing list. (Note: The following example assumes you are running Debian or a Debian variant of Linux.)

sudo apt-get install gcc g++ make binutils zlibc zlib1g zlib1g-dev curl

Next, you will want to cross build minix with the new changes. cd into the minix directory and issue the following command:

./releasetools/x86_cdimage.sh

If you have any build failures, either you don't have the required build dependencies installed, you don't have an internet connection (the crossbuild fetches programs during the build), or there are Minix3 related issues with porting your command. For the latter, sending a well researched question to the minix3 google groups mailing list with a log of the end of your build can be helpful. The newly built ISO will be located in the ./minix directory.

Now we want to test the x86 minix3 image within a virtual machine. Boot your newly built ISO image into a virtual machine, such as VirtualBox, and then test the install. If it installs, then you may reboot the virtual machine, and try booting into it without the ISO image. Now you want to invoke the command with as many of the command's flags as possible. view the man page for the newly imported command. Now, you will want invoke the minix-posix test suite within the virtual machine.

/usr/tests/minix-posix/run

If the tests for your command pass, then you are good to go. Otherwise, you may want to send a log of the tests to the mailing list if asked to do so.

Finally, once everything is tested use:

git format-patch --cover-letter

to format a patchset to email to the google groups minix-dev mailing list.

Once you look over and review the patches, and create a cover letter, use git send-email to send your patch to the minix-dev@googlegroups.com mailing list. git help send-email for more details. (Also, another great resource for help with git is the community Pro Git book available from the git homepage.)