User Tools

Site Tools


developersguide:portingnetbsdstepbystep

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
developersguide:portingnetbsdstepbystep [2015/03/09 20:08]
stux [Step 7: Remove the old man pages for the now removed minix3 command] same as before: clarify minix subfolder location
developersguide:portingnetbsdstepbystep [2016/02/12 10: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.)
 +
  
developersguide/portingnetbsdstepbystep.txt · Last modified: 2016/02/12 10:06 by stux