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
Last revision Both sides next 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 [2015/03/09 20:48]
stux [Step 10: Crossbuild and test minix.git for x86] fix typo
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.
 +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''​ 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.
 +
 +===== 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 runing 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_hdimage.sh -i
 +</​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 virtul 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 availible from the git homepage.)
 +
  
developersguide/portingnetbsdstepbystep.txt · Last modified: 2016/02/12 10:06 by stux