STLPort and the EOCP

[ home ] [ overview ] [ developers ] [ about escher ]

The EOCP was upgraded to run with STLPort, and thus be STL "compliant" (i.e., not including a bunch of hacked files to allow old Microsoft Compilers to work).

Because the EOCP will be running on embedded platforms, it is necessary for us to provide our own iostreams library implementation of STLPort, though this is not usually required for windows. Thus, when downloading and installing STLPort, we have to do some of those things that the documentation for STLPort says we problably don't need to do. This is a little annoying in the beginning, but will pay off.

Also, please check out the EOCP STLPort FAQ.

Downloading version 5.0.0

You can download STLPort from the web, but I recommend getting it as part of the escher CVS tree. It can be found under $eschercvs/EOCP/src/vendors/STLPort.

Build & Installation Process

Cross Compiling

1. This feature currenly ONLY works for GNU-built, *-linux crosscompilers built on a true linux system. There has not been success thusfar using Cygwin-built crosscompilers for building STLPort. Note that we hope to still use Cygwin-built crosscompilers once we determine STLPorts issues with Cygwin.
2. You must first build your crosscompiler. For EOCP, we use this procedure. Don't forget to add the ${BASECROSS}/bin/ directory to your path, and export the appropriate environment variables by running the setup_crosscompiler script.
3. Once the crosscompiler it is built, environment variables are exported, etc., you will be able to use it by configuring STLPort to use that compiler. For the gumstix crosscompilation, we have created a special makefile and added it to the CVS repository directory in which STLPort is found:

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort]
$ cd build/lib

   All building is performed in this directory.

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/build/lib]
$ ./configure --clean

   This step removes any existing configurations (e.g., a build you did for your regular installation of STLPort).

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/build/lib]
$ echo $CROSSTARGET
arm-linux

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/build/lib]
$ echo $BASECROSS
/usr/local/escher/crosscompile/buildroot_gumstix_2.6.11gum/build_arm_nofpu/staging_dir

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src]
$ ./configure --target=${CROSSTARGET} --with-extra-cxxflags=-I{BASECROSS}/include

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/build/lib]
$ make -f gcc-gumstix.mak clean

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/build/lib]
$ make -f gcc-gumstix.mak &> build.out

   Note that you must be building the Escher CVS version of STLPort in order to make this work, since the existing STLPort 5.0.0 release does not correctly recognize that --target=arm-linux and --target=arm-unknown-linux should be equivalent, and thus Makefiles in the build directory are listed in nonexisting directories. I have patched this version to work, based on feedback from the STLPort gurus and code managers. I have learned that it will be rolled in to future releases.
   
   Next, we will test to ensure that everything was built correctly:

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/build/lib]
$ ls obj/arm-linux-gcc/shared/libstl*
obj/arm-linux-gcc/shared/libstlport.so
obj/arm-linux-gcc/shared/libstlport.so.5
obj/arm-linux-gcc/shared/libstlport.so.5.0
obj/arm-linux-gcc/shared/libstlport.so.5.0.0

   Examine the file build.out for any errors which may crop up, and you can address them to us. Many errors may have already appeared on the Escher STLPort FAQ .

4. Making the STLPort libraries part of your normal, everyday, compilation and linkage routine is necessary in order to fully take advantage of the project. You have to put these shared libraries in the critical path of future compilations, as well as moving them to the destination platform. This is done in the same spirit of Boris' README file (Hint Hint, this is copied and cleverly pasted (for path correctness) from that README file).

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/build/lib]
$ su

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/build/lib]
$ cd ../..

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ tar cf - stlport | (cd ${BASECROSS}/include; tar xf -)

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ chmod -R a+r ${BASECROSS}/include/stlport

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ chown -R root:root ${BASECROSS}/include/stlport

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ (cd build/lib/obj/${CROSSTARGET}-gcc/shared; tar cf - --exclude=CVS --exclude=.cvsignore .) | (cd ${BASECROSS}/lib; tar xf -)

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ chown root:root ${BASECROSS}/lib/libstlport*

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ exit

   Now, all of the files are installed on our local filesystem. Next, we must put them on the embedded linux machine. We do not need to send the stlport/ directory which would normally reside in the include path, since we won't be building anything on that local machine.

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ (cd build/lib/obj/${CROSSTARGET}-gcc/shared; tar cf stlport.so.tar --exclude=CVS --exclude=.cvsignore libstlport*)

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ mv build/lib/obj/${CROSSTARGET}-gcc/shared/stlport.so.tar .

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ scp stlport.so.tar root@gumstix2:/mnt/mmc

   Note that our machine name is gumstix2, and that we are using an externally mounted memory card (MMC) in order to have enough space for these libraries. You will get annoying and difficult-to-decipher messages if you do not have this directory on your embedded platform, or if it is not mounted correctly.

   [sprinkle@ransom-urquell /usr/local/escher/EOCP/src/vendors/STLPort/]
$ ssh root@gumstix2

   When we ssh to the gumstix2 machine, our clever little prompt changes.

   gumstix # cd /mnt/mmc && ls | grep stlport
stlport.so.tar

   gumstix # mv stlport.so.tar lib && cd lib
gumstix # tar xf stlport.so.tar && ls | grep stlport*
libstlport.so.5.0.0

   The observant reader will not be surprised to see only our actual library, and not the symbolic links to it; we did not request for tar to create those links for us back on the crosscompiler platform. However, even if we had, we would not be able to take advantage of them, because we are going to have to create new symbolic links in any case.

   gumstix # pwd
/mnt/mmc/lib
gumstix # cd /lib
gumstix # ln -s /mnt/mmc/lib/libstlport.so.5.0.0 libstlport.so
gumstix # ln -s /mnt/mmc/lib/libstlport.so.5.0.0 libstlport.so.5
gumstix # ln -s /mnt/mmc/lib/libstlport.so.5.0.0 libstlport.so.5.0
gumstix # ln -s /mnt/mmc/lib/libstlport.so.5.0.0 libstlport.so.5.0.0

   Now we should have the proper shared libraries in place for our crosscompiler's benefit, as well as the final platform's benefit, there's nothing to do but run some tests!!

5. Running the built in regression tests for STLPort. This is where, as they say, we are at an impass. Tests compile, but do not link, with the crosscompiler. We are working on it (3/8).
   
   The problem is that the arm-linux-gcc compiler is built with the option --disable-__cxa_atexit, which is required by STLPort. No word yet on whether STLPort actually needs this, or it can be disabled somehow...

Conclusion

You are now ready to start building the EOCP. I find it EXTREMELY useful to close and reopen Visual Studio before starting the build process. If you have more than one instance open, you should make sure that the one you set the paths in is the LAST one you close, since those settings are written to the registry. Otherwise, you might think "why did the paths change?" "I set that, I REMEMEBER setting that..."