Getting Started

What is this

This is an implementation and a certain kind of redesign over the old Plan 9 ANSI/POSIX Environment (APE). Now APEX runs in amd64, RISC-V and AArch64 are not implemented for now. It's C11 and POSIX.1-2008/IEEE Std 1003.1 compliant, and is built mainly with Clang, though it's suitable to be built with GCC too.

This file is a quick list of instructions to get you started quickly.

Prerequisites

To build APEX and play with it, you need to have git, Clang or GCC, binutils and (GNU) make installed. And of course, a running Harvey OS to use it. On a Debian, Ubuntu or other .deb system, you should be able to get going with

sudo aptitude install git build-essential

Working with GitHub

Before at all, you can clone the repo wherever you want, now APEX for Harvey is tree independent. So you needn't use anything like $HARVEY/sys/src/apex and its related bin/lib/include directories anymore.

We use GitHub pull-request method for code-review as in Harvey main GitHub repository. So check this if you want to submit pull requests:

• Sending a patch

Assuming you cloned the repo in your machine, it's now all set. You can build the whole thing just by running

HARVEY=$HARVEY APEX=`pwd` OS=linux ARCH=amd64 make lib

which should take maybe less than a minute (assuming you set up $HARVEY to your Harvey tree). It will build libap.a only. That is all what you need to compile ANSI/POSIX C programs for Harvey.

You can build libap internal parts separately setting up APEX variable to top of the tree, OS and ARCH properly and typing make inside every directory of sources included (amd64, gen, math, plan9, posix, stdio, stdlib, mutibyte...).

For building basic programs shipped with APEX, awk troff, expr or pdksh, just type:

HARVEY=$HARVEY APEX=`pwd` OS=linux ARCH=amd64 make cmd

Once building process is complete, you can test it in Harvey (see its wiki).

Rules and tricks for patching, committing or fixing code with GitHub pull-request method are the same like with Harvey's main repo. (One more time see Harvey's wiki).

Running your programs

You can use the ufs file server that Harvey building process provided you, for serving your APEX programs (see Harvey's wiki). In fact, you can put your APEX binaries wherever you want, into Harvey's tree or not. That includes other file servers, imported directories, binded or mounted directories, etc... Just ensure that you have in your Harvey's path the destination directory to your Harvey's APEX programs. Putting inside of one of the standard directories for binaries or using bind or mount.

Example:

ajc@ajc-machine:~/source/c$ clang -c -I /home/ajc/source/apex/amd64/include -I /home/ajc/source/apex/include -I . -O2 -mno-red-zone -ffreestanding -fno-builtin -nostdlib -nostdinc -trigraphs -Wall -Wuninitialized -g -D_SUSV2_SOURCE -D_POSIX_SOURCE -D_LIMITS_EXTENSION -D_BSD_SOURCE -D_BSD_EXTENSION -DHAVE_SOCK_OPTS hello-posix.c

ajc@ajc-Vostro-3560:~/source/c$ ld -o hello-posix -static hello-posix.o /home/ajc/source/apex/amd64/lib/crt1.o /home/ajc/source/apex/amd64/lib/crti.o /home/ajc/source/apex/amd64/lib/crtn.o -L /home/ajc/source/apex/amd64/lib -L /home/ajc/source/harvey/amd64/lib -lap -lc

The program:

#include <stdio.h>

int
main (void)
{
	printf("Hello world from ANSI!\n");
	return 0;
}

Result:

harvey@cpu% /apex/amd64/bin/hello-posix
Hello world from ANSI!

As you can see, I have APEX repo in my home, under source/apex. Note that we used -L pointing to where I have Harvey's runtime libs in order to link against libc.a (-lc). Also look at those startup files explicitly indicated in command line: this task will be done for clang/gcc driver natively in Harvey (crt.i and crt.n are por C++ constructors/destructors, not covered here for now), so for cross-compiling just try to make an script for yourself which could do this for you in Linux. Also all that -D_FOO defined are guards from ANSI headers that native compilers will have, but linux compiler hasn't. So for now you need to explicitly indicate them. That's all you need to compile ANSI/POSIX programs for Harvey. After that I setup ufs and mounted my APEX repo in /apex, to test my hello world.

Conventions about paths and ports

• Conventions for now, and with those GCC and Clang for Harvey are being built natively, is that inside Harvey APEX resides at top of the file system: that's /apex. This ensures an stable path for internals in compilers which need fixed ways for finding subprograms like ld, as, etc... it's not an APEX issue, instead it's a requierement of toolchains.

• Also, for keeping some order, programs maintained by Harvey team like awk, troff, expr, etc, will be placed as sources in /apex/cmd and the binaries under /apex/$arch/bin, placing dependent libs if it would be needed in /apex/$arch/libs. Into the last, you'll find there startup files for compilers and the libap.a library once APEX was built.

• Ports and toolchains are usually very dependents of the normal Unix hierarchical file system for many reasons, so the convention for ports will be that all of them will reside under /apex/ports. Under it, one can find /etc, /share, /usr and all of those usual directories in what this kind of programs from Unix world like for living. This will do easier making a tool for package management, and maintaning the ports themselves: less params in the setup of everyone.

---

As mentioned before, if one would want to remove APEX and friends nuding Harvey to its pure beauty, with this conventions just deleting /apex would be enough for having the system base again.