Álvaro Jurado edited this page Dec 13, 2016 · 15 revisions

Welcome to the Harvey's APEX wiki!

Getting Started

Jump right into Getting Started page. It contains the basics about prerequisites, code review system and accessing files.

Design and concept

First of all, you must remember that APEX is a work in progress. We're adding/fixing things while porting Unix/Linux software. Seeing what must be changed or updated and what does not matter.

When Plan 9 was made at Bell Labs, its authors made a minimal ANSI/POSIX environment (APE) to test native Plan 9 software in a simulated Unix environment. Main purpose was porting Plan 9 programs to Unix.

But life has weird ways sometimes, and APE ended up being the way to port Unix programs to Plan 9. If you don't know anything about that, you should read first this paper in order to understand better next paragraph.

APE originally had a bunch of libs wrapping native Plan 9 libs, but now Harvey is using GCC or Clang as its toolchain, then there's only one lib needed : libap.

As you can see, and in "Getting Started" page, it's needed the "-lc" for libc. Well, native toolchain will do it for you, but for now we are compiling in Linux and running in Harvey.

Plan 9 APE was built like a bunch of wrappers for native syscalls and related functions (see malloc.c) thinking in building ANSI libc over this "translators". In those days, it was slow and under certain point of view, a leak in runtime. But we're in 2016, and now we have better hardware. And APE was being implemented/fixed in many ways.

We implemented APEX from APE with Musl libc code, to bring up an ANSI/POSIX environment more compatible and in line with the times. Because original Plan 9 APE was purely C89, and in Harvey we have needs and projects that were claiming for a better implementation. It keeps main wrappers under ap/plan9, but updated, and uses native syscall API: what means there's no any syscall wrapped anymore, providing access to kernel API through native libc. Harvey's APEX allows the issue of native syscalls because it's using the same compiler across all the system. Plan 9 used its own toolchain and an ANSI wrapper for it called "pcc" (do not confuse with Portable C Compiler) wrapping entire syscall collection. Harvey uses the same GCC/Clang for all, so there's no need to wrap any syscall, just look at how we avoid it for those what could collide with ANSI functions (open, dup, stat...).

This way provides as well that Harvey only needs libap to build ANSI/POSIX programs, because rest of the old APE libs were made thinking for using a wrapped compiler (Plan 9 8c/6c/etc.. -> pcc) what had its own way and subworld into the system. APEX works with Harvey as a modular subsystem, so you can add or remove it just by adding/removing its dir, using the same compiler and all of the system environment. Then, with the same toolchain, you can merge code in your programs between native Harvey's library and APEX subsystem. For instance, you are not obligated to use printf, being able to have a source including u.h and libc.h and use fmt functions like print, vfprint, etc... with a simple guard from native system into an ANSI/POSIX program, usually ported from Unix/Linux world. Our preferred way in case you wanted to do something like that is writing native code in separated sources and not merging both in the same file due to style purposes.

Finally, APEX is now being built with Clang: ensure if you want to build it with GCC you changed properly linux.inc file at top of the tree.

Harvey inherited a libStdio from Plan 9. It's not clear why it exist, because it was the same implementation as lib/ap/stdio in old APE. So if you merge things from both environments, ensure you're not using libStdio or Stdio.h (note the uppercase). Now APEX stdio is Musl libc stdio, which makes APEX more suitable for porting tasks.

About porting earthling software to Harvey, check Porting programs from Unix or Linux to Harvey.