General Software Porting Guide

1.    Purpose of this document

As there is so much excellent open source software from the Open Groups, we can port these software to our project to speed up our development under the GPL (GNU General Public License). But because of we used many different platforms, most of the time we can not use these software directly. So this document is written to give a big picture of porting the open source software to our projects.

This document will show you how do I porting the BOA (a http server for embedded system) server with SSL to the ARM platform and the Wget with SSL to the MIPS platform. All of these porting steps are from my own porting experience, but even though, I can not assure you that the following my steps can work properly when you porting other software to other platform.

2.    General software porting steps

2.1 Get the source code.

Obviously you need to get the source code of the software from the Open Group under the GPL.

2.2 Install the tool chains

Make sure you have installed the correct tool chains before you do the porting.

2.3 Get clear the architecture of the source code.

The first thing you need to do when you get the source code is to read the “README” file in the top most directory, in which will tell you how to install and run the software in a PC and things you need to pay attention to. These information are very important and useful when you porting the software to other platforms.

In most case there is a file named “configure” or something like that in the top most directory, this file makes the porting process very simple. But if there has no such file, then it must have a file named “makefile” or a shell script file whose name may be “Install” or “go” etc. Now let’s go and see how to deal with the three conditions described above.  

2.3.1    Source code with configure file.

For those who have configure file first you need to run following command to see what is supported by the configure file.

This will print a list of options which you can pass to the configure file. For porting purpose, you should find out whether there have options like “--target=”, “--host=” and “--build=”. If you find these from the printed list, congratulations! You can run command similar as following to cross compile the software easily.

Replace the “arm-linux” with you target platform type and the “i686-pc-linux” with your build platform type (other options not presented in the command, you should use these options according your demand)

After the “configure” command run successfully, you can run “make” to cross compile the source code and if no error reported, you will find the executable binary file in the “source” or “src” or the top most directory. Copy this binary code and related library to the target platform then you have porting it to the target platform successfully.

But if you have not find the options like “--target=”, “--host=” and “--build=”, don’t worry, you can still run the “configure” with options with your demand. After that, the condition is the same as those which just have “makefile”, so you should see chapter 2.3.2 for more details.

2.3.2    Source code with makefile

If there is only “makefile” in the source code then you need to modify the makefile to cross compile the source code. Generally speaking, you need modify following things:

1.       Modify the header file path which passed to the compiler by “-I” parameter. You should use the header file of the tool chain other than the default header files of the build system.

2.       Modify the library path which passed to the linker by parameter “-L”. You should tell the linker to use the library of the tool chain other than using the library of the build system.

3.       Modify the compiler to your cross compiler by modify the value of “CC” or any parameter that define the compiler.

4.       If there is several “makefile” in different directory then you need modify all of them.

2.3.3    Source code with shell script

This is very similar to the one with “configure” file, but it will do the configuration, compilation and installation all in one command. So you need to modify the shell script to avoid it doing the compilation and the installation. After you modify the shell script you run it and it will generate the makefile. Again you need to modify the makefile.

3.    Examples of porting

3.1 Porting OPENSSL to ARM platform

If you need the HTTP server or client to support the SSL (Security Socket Layer), the easiest way is to use the OPENSSL library. The OPENSSL already support many platforms so it’s very easy to port it to the arm platform.

Step 1. Find out what is support by the “Configure” file by run the following command:

Step 2. Tell the configure file to use the “arm-linux-gcc” to compile the program.

Step 3. Compile the source code using the cross compiler:

If no error is reported you will find two libraries in the top most directory: libssl.a and libcrypto.a. Now you can use these library in you program which run on the ARM platform. The detailed information about how to use the library is on the webpage: http://www.openssl.org/docs/ssl/ssl.html

3.2 Porting BOA server with SSL to ARM platform

The BOA server itself does not support the SSL. So if you need to have it support with SSL you need to write code to use the library compiled as I described above. To have the BOA server support the SSL, the basic idea is to use socket created by the OPENSSL library (see http://www.openssl.org/docs/ssl/ssl.html for more information).

But if you don’t want to write any code, the uClinux community has already implemented the SSL in the boa, and so you can use this boa in your project without modify any source code (I did so). In this situation, the makefile of the boa needs to be modified to support the SSL. Make sure that the linker can find the right libraries of the OPENSSL which was compiled for the ARM platform.

In my case, the makefile in “boa\src” goes like:

BTW, don’t forget to put the certification to the directory which you define in your code of boa(in file boa.c)

My case is:

3.3 Porting Wget with SSL to MIPS platform

GNU Wget is a free software package for retrieving files using HTTP, HTTPS and FTP. From the definition we can see that the Wget support the SSL. But we need to configure it with SSL for cross compiling.

Also, the first step is to run the “./configure -h” command to find out what can be configured(Suppose you have already cross compile the OPENSSL library). From the output we can find out that in the simplest condition, you need to use flag “--build=”, “--host=”, and “--with-libssl-prefix[=DIR]”. But for embedded system we should make the executable binary as small as possible, so I disable many features in the Wget that useless for our project. So my configuration goes like:

You may get errors when you run the “configure” command as I described above if you didn’t put the “libssl.a” in the right directory. In my case I indicate the linker to find “libssl.a” in directory “/opt/gr2512/lib/libssl”, but in fact you need to create a directory named “lib”under it, and then put the “libssl.a” in the folder of “lib”, that is, in folder “/opt/gr2512/lib/libssl/lib”. If the configure returns no errors you can run “make” to cross compile the Wget. After that you can get the executable binary code for MIPS platform in the “wget/src” directory.