Differences

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

--- developersguide:portingnetbsdstepbystep [2015/03/10 01:06]
stux [Step 6: Remove the old minix3 command from minix/commands] clarify. These are in the minix/commands subfolder inside the minix repo
+++ developersguide:portingnetbsdstepbystep [2016/02/12 16:06]
stux Update instructions to reflect current setup; and minor fixes
@@ Line 1: / Line 1: @@
+====== 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

Differences

Page Tools