Getting Started

What is this

This is an implementation and a certain kind of redesign over the old Plan 9 ANSI/POSIX Environment (APE). It's C11 and POSIX.1-2008/IEEE Std 1003.1 compliant, and is built mainly with GCC, though it's suitable to be built with Clang too.

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

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

Prerequisites

To build APEX and play with it, you need to have git, GCC or Clang, binutils and (GNU) make installed. And of course, a running Harvey OS to use it.

Official support

we test with Linux on every commit

Linux

On a Debian, Ubuntu or other .deb system, you should be able to get going with

sudo apt install git build-essential

FreeBSD

(regulary tested with latest release version)

If you are in a FreeBSD, you should do:

pkg install git go bison gmake
export PATH=/usr/local/bin:$PATH

BUILD

Assuming you cloned the repo in your machine, it's now all set. You can build now the whole APEX:

cd src; CC=gcc HARVEY=$HARVEY APEX=$(dirname `pwd`) OS=linux ARCH=amd64 make

which should take around a minute (assuming you set up $HARVEY to your Harvey tree). Note that you can choose the compiler as in Harvey build process. It will build lib, startup files and some programs. 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 only basic programs shipped with APEX, awk troff, expr or pdksh, assuming you're into apex/src dir, just type:

CC=gcc HARVEY=$HARVEY APEX=$(dirname `pwd`) OS=linux ARCH=amd64 make cmd

For building only APEX lib and related:

CC=gcc HARVEY=$HARVEY APEX=$(dirname `pwd`) OS=linux ARCH=amd64 make lib

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

If you are in a FreeBSD, you should do:

CC=gcc HARVEY=$HARVEY APEX=$(dirname `pwd`) OS=linux ARCH=amd64 gmake

For all the stuff. As you can see, linux.inc file is very portable. Also follow the same rules for separated lib/cmd build.

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.

By default Harvey provides a bind call in lib/profile so if you have /apex in your Harvey running system, you can just run awk or troff without doing anything special.

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-machine:~/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/src/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 source ports will be that all of them will reside under /apex/src/ports. Under $arch (/apex/amd64 in this case) you'll find /etc, /share, /lib, /bin 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 base system again.