Getting Started

Álvaro Jurado edited this page Jan 10, 2017 · 16 revisions

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:

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

APEX=`pwd` OS=linux ARCH=amd64 make

which should take maybe less than a minute. It will build libap.a only. That is all that 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...).

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 that 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.