C Project Building

The goal is to simplify the building and compiling of projects. This is accomplished through a standard layout of the files and a standard for a build script.

Library Projects

The goal of a library project is to produce a library file and its header files.

The initial contents of the project directory consists of source files (.c) and header files (.h) under the source directory src/.

To build the C archive, change your current directory to the project directory, and execute a conformant build script. This should should first create a library lib/libNAME.a (or lib/libNAME.so if compiled with dynamic linking).

Secondly, the build script should assemble the library and the header files under into a tar archive. This archive will be called a C archive, and should have the file extension .car. Here is an example of a small library project, and the content of its C archive:

	$ tar tf org_pvv_hakonhal.car
	lib/liborg_pvv_hakonhal.a
	src/org/pvv/hakonhal/utils/ip.h
	src/org/pvv/hakonhal/system/net.h

An implementation may also choose to make the C archives compressed with bzip2 (.car.bz2) or gzip (.car.gz), and implementations must be able to deal with such C archives.

The Structure of the Source Directory

It is possible and recommended that you put the code in a directory structure below the source directory. For instance if we are producing utility functions and socket routines, we put the code under src/org/pvv/hakonhal/utils/ and src/org/pvv/hakonhal/net/ respectively.

Code in such a directory structure should generally refer to other header files using the Fully Quallified Name, which is the pathname relative the src/directory. The directory in which the source file is located should also included in the header search path. So for instance, the src/org/pvv/hakonhal/utils/ip.c source file may refer to its header file as either of

	#include "org/pvv/hakonhal/utils/ip.h"
or
	#include "ip.h"

All source files under src/ has a common directory prefix, for instance org/pvv/hakonhal/. By default, the build script will use the common directory prefix to name the library and the C archive, with the directory slashes converted to underscores. For the above common directory prefix, the C archive would get the name org_pvv_hakonhal.car.

Third Party's C Archives

When you are using third party C archives, copy them to the cars/ directory, or use a symlink. The build script will ensure that the third party's C archive's src/ directory will be included in the header search path when compiling.

Under the hood, the build script might unpack a C archive cars/NAME.car under a cars/NAME/ directory, and add cars/NAME/src/ to the header search path (-Icars/NAME/src/).

	$ find cars/ -type f
	cars/com_hotmail_arneolav_utils.car.bz2
	cars/com_hotmail_arneolav_utils/lib/libcom_hotmail_arneolav_utils.a
	cars/com_hotmail_arneolav_utils/src/com/hotmail/arneolav/utils/io.h

Customizing the Build

If the user chooses to, (s)he can define a makefile Makefile.user that will affect the building of the C archive. The user may assume that Makfile.user is included in a makefile just after variables like CC and CFLAGS are defined. The user may also assume that Makefile.user is included just before the default target all that would compile and build the C archive. For instance one implementation may produce a makefile during the project building containing:

.Makefile.g.src:
	CC=gcc -W -Wall -Wstrict-prototypes -Wmissing-prototypes -Wunused -Werror -g
	CFLAGS=-Isrc/ -Icars/com_hotmail_arneolav_utils/src
	
	-include Makefile.user
	
	all: org_pvv_hakonhal.car.bz2

So if the user uses the math library, (s)he should create the Makefile.user containing:

Makefile.user:
	LDLIBS+=-lm

Projects with Executables

A project that wants to produce executables is supposed to be split into a library project plus one source file (.c) per executable. Each of these program source files would contain a main() function.

The program source files should be put under the psrc/ directory. For each program source file psrc/PROG.c, there will be produced one executable bin/PROG.

The build script must ensure that all C archives' header files are included in the header search path, and ensure that all C archives' libraries are included when linking.

For instance, if we got the following files:

	$ find . -type f -o -type l
	./cars/com_hotmail_arneolav_utils.car.bz2
	./psrc/get.c
	./src/org/pvv/hakonhal/utils/ip.c
	./src/org/pvv/hakonhal/utils/ip.h
	./src/org/pvv/hakonhal/system/net.c
	./src/org/pvv/hakonhal/system/net.h

psrc/get.c includes the following headers:

	#include "org/pvv/hakonhal/system/net.h"
	#include "org/pvv/hakonhal/utils/ip.h"
	#include "com/hotmail/arneolav/utils/io.h"

Running a conformant build script builds the library lib/org_pvv_hakonhal.a, the C archive org_pvv_hakonhal.car, and the executable bin/get. For the linking, both com_hotmail_arneolav_util.car.bz2's library and liborg_pvv_hakonhal.a are included.

Bugs

The following could become better:

1. If there are no files in the src/ directory, but files in the psrc/ directory, the build should not fail.
2. If source files are removed from the src/ directory, this is not detected by the build script. This may cause the source files' object- and dependency- files to be lying around and perhaps causing errors. Do a build clean or build rebuild to remove such files.