developersguide:portingnetbsdstepbystep [Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 [[.:portingnetbsduserland|Porting the NetBSD Userland]].

===== Step 1: Clone the minix.git repo =====

First, we must clone the **minix.git** repo by issuing the command:
<code>
git clone git://git.minix3.org/minix.git
</code>

===== Step 2: Checkout the latest minix3 netbsd.git repo =====

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

<code>
git clone git://git.minix3.org/netbsd.git
</code>

Note: you may also use

<code>
git remote add netbsd git://git.minix3.org/netbsd.git

git remote update
</code>

within the minix repo to keep everything together.

===== Step 3: Choose a NetBSD utility to import into minix3 =====


For this step, decide on a NetBSD utility you want to import into minix3.
You should check the official wiki guide listed above, [[.:portingnetbsduserland|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:
[[https://groups.google.com/forum/#!forum/Minix3|Minix3 Google Groups]].

===== Step 4: Copy the NetBSD command into the proper subdirectory of minix/ =====

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.

===== Step 5: Modify the minix ./bin, ./usr.bin, or ./usr.sbin Makefile =====

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.**
	

===== Step 6: Remove the old minix3 command from minix/commands =====

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''.

===== Step 7: Remove the old man pages for the now removed minix3 command =====

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.

===== Step 8: Edit ./distrib/sets/lists/minix-*/mi =====

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.

===== Step 9: git grep for old invocations of the previous command. =====

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:

<code>
git grep '/usr/bin/sleep'
</code>

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.

===== Step 10: Crossbuild and test minix.git for x86 =====

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.)

<code>
sudo apt-get install gcc g++ make binutils zlibc zlib1g zlib1g-dev curl
</code>

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

<code>
./releasetools/x86_cdimage.sh
</code>

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.

===== Step 11: Test the x86 minix3 image in a virtual machine. =====

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.

<code>
/usr/tests/minix-posix/run
</code>

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.

===== Step 12: git format-patch and git send-email. =====

Finally, once everything is tested use:

<code>
git format-patch --cover-letter
</code>

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 [[http://git-scm.com/book|Pro Git]] book available from the git homepage.)
User Tools

Site Tools

Page Tools
