Porting programs from Unix or Linux to Harvey

Building in Linux

One of the main Harvey's features is that you can compile in Linux (or Mac, or BSD) and run into Harvey, thanks to Harvey's standard ABIs and ELF64 support.

We're working on native toolchain, for now GCC, so you can get more information about in our list. But from Linux we're using Clang as main native toolchain, for APEX too.

What do you need to port a program from Linux/Unix into Harvey for now? well, first a working Linux. The process is simple: you will have to run configure with some parameters to ensure it's compatible and most of C code needed is implemented in APEX library. This doesn't mean that it will be built without any problem in case configure runs nicely, there could be exclusive parts not implemented in Harvey by design, for example symlinks or missing functions in APEX library. APEX should have now all what you need to port software from BSD and Linux world, but out there, programmers usually use specific libraries or any other kind of dependencies that Harvey couldn't have yet.

So before porting any program or application, first look for carefully the documentation and information available about it to know all what you could need. Because you'll have to port any third party library that this program or application could use. APEX is just C, not SDL, X11, libboost for C++, etc...

For now we have a working Linux system and tons of docs about the program we want to port. The program was written in C, because for now only Go and C are supported in Harvey until native toolchain could be released. So let's go with configure part.

More usual issue is that you'll find and autoconf setup in the program you want to port. So you need to ensure that configure detects all things what programs needs, in APEX or in other libraries needed and previously ported. Since we are not in a Harvey system, you will need to pass some standard options to every configure script by default:

./configure CFLAGS="-I$PATHTO/harvey/apex/amd64/include -I$PATHTO/harvey/apex/include -I$PATHTO/source/harvey/sys/include -mno-red-zone -ffreestanding -fno-builtin -nostdlib -trigraphs -D_SUSV2_SOURCE -D_POSIX_SOURCE -D_LIMITS_EXTENSION -D_BSD_SOURCE -D_BSD_EXTENSION -DHAVE_SOCK_OPTS -DHARVEY" LDFLAGS="-static $PATHTO/harvey/apex/amd64/lib/crt1.o $PATHTO/harvey/apex/amd64/lib/crti.o $PATHTO/harvey/apex/amd64/lib/crtn.o -L$PATHTO/harvey/apex/amd64/lib -L$PATHTO/harvey/amd64/lib" LIBS="-lap -lc" LIBM="" --prefix=$PATHTO/harvey/apex/ports --host=x86_64-linux-gnu --build=x86_64-harvey-elf --target=x86_64-harvey-elf --disable-shared --$FOO_CONFIGURE_PARAMS_NEEDED[num]

Where $PATHTO is your path where you have APEX repo and Harvey's libc, which means you need Harvey OS system built, and $FOO_CONFIGURE_PARAMS_NEEDED refers all of that kind of options in a configure setup: --without-foo --with-bar, etc... what could be required by the program you're porting.

Be careful and ensure you have properly set --host, --build and --target options, because if not, it won't work. This is a special case of cross compiling, because our cross compiler is the usual Linux compiler.

LIBS must be setup, even you should do

    export LIBS="-lap -lc"

to ensure all subdirs in your program with their own configure script can set the libs you need. This is usually problematic, because GCC always set -lgcc -lc automaticly, so many GNU scripts like libtool, won't add -lc. You'll know it when you see all of that "undefined foo" at linking time. The trick usually is add -lc to the appropriate place. Ask in our list if you find any of this problems. (Don't forget to put "APEX:" at the begining of the topic in your mail).

If all configure setup was well, you only need to type make, and cross your fingers until all went well. In case it didn't, usually, you will need to look for in APEX if the undeclared function is present, but it's depending on a header not present in earthling (we are the aliens!) source, or wasn't rightly discovered by configurescript, etc... A common task would be grep to config.h to see what has been set up, and... over all, being patient is always a good method. Porting software is usually maddening.

After you successfully built your program and the miracle is done, just test it via booting Harvey and copying your new program into the disk of Harvey or in your ufs server tree that you could be using. Probably that first time you run it, it will commit "suicide". Take PC=num, then

    objdump -S your_program_binary

and lookup for "num" in it. You'll have the place where it's dying. Now, I'll guess you're an experimented programmer and debugger and you'll provide your own solution :-).

Of course, porting from a running Harvey system is very different, and it has also its own issues. Let's go to see them.

Building in Harvey

TODO (pending on native toolchain... soon).