This shows you the differences between two versions of the page.
Next revision | Previous revision Last revision Both sides next revision | ||
developersguide:portingnetbsdstepbystep [2015/03/08 18:18] stux created |
developersguide:portingnetbsdstepbystep [2015/03/10 01: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.) | ||
+ | |||