README

Motivation:
-----------

The goal of this project is to allow people to easily write programs using
plan9's C programming environment on their platform of choice. The provided
Makefile.p9c will also link statically by default against the musl libc library
if available when installing on Linux. This has the benefit of compiling
programs that are fast, easily transferable yet small. Indeed, our hello.c
example only weights 60K stripped of symbols (125K OpenBSD's libc and 752K
ArchLinux's glibc). Even though the source code is small, it does include code
from both lib9.a and libbio.a.

Background:
-----------

Plan9 has its own ANSI C compiler with extensions that are now mostly
supported by the newer C standards and also has its own core routines (libc)
and buffered I/O (libbio) libraries. A typical program will probably only need
to include u.h, libc.h and libbio.h.

For more information on how to write programs using the plan9 libraries :

 http://plan9.bell-labs.com/sys/doc/comp.html
 http://doc.cat-v.org/plan_9/programming/c_programming_in_plan_9

Because of its compact size and fast performing qualities, plan9 base
programming enviroment has been ported to other Unix-like platforms. The
system is available at :

 https://github.com/9fans/plan9port

Up to version 1.4.2, go C bootstrap included a copy of that base
cross-platform programming environment. Our project includes that last version
of the source code.

Requirements:
-------------

* musl libc, our Makefile.p9c uses musl-gcc when available on Linux systems,
  see http://www.musl-libc.org/ or check your distribution package manager for
  more musl libc installation information.

NOTE: plan9c will still install and work without musl libc. Static binary
compactness will depend on the host's libc programs are linked against.

To get started:
---------------

 ./install.sh	<= builds plan9 C libraries and generate your Makefile.p9c
 make		<= builds our example hello.c against lib9 & libbio
 ./hello	<= test the installation

 make strip	<= optional: remove symbols; check your binary size!

To create a new project, include the Makefile.p9c file to your own project
Makefile. Like the Makefile provided with the hello.c example. You will only
have to modify Makefile, not Makefile.p9c for simple projects.

Credits:
--------

The plan9c folder comes from the go 1.4.2 source tree. Modifications were done
to the build system (dist) mostly. The go authors holds the copyrights. This
subset of the plan9port uses a permissive BSD license which is very similar to
the license of this package (ISC license). Finaly thanks to the ken, rob, russ,
and the plan9 team to come up with all of that in the first place.

Enjoy !