Introduction

Building libraries in occam-pi has always been tricky -- particularly so if you want to support both KRoC and the Transterpreter. occbuild is a tool that makes it straightforward to compile occam libraries and programs without needing to know the details of which toolchain you're using.

occbuild hides the details of the toolchain by acting as if you only care about the occam-specific files in your program; that is, .occ source files get compiled to .tce objects, .tce files (and native .o FFI files) are linked into .lib libraries, and .occ and .tce files are compiled into programs (which have no extension). You can describe dependencies entirely based upon the above files, and occbuild will handle the other files that the toolchain produces automatically for you.

occbuild is currently included in the kroc module of the KRoC source tree; if you install the latest Subversion version of KRoC, you'll get occbuild installed automatically.

Building things with occbuild

Do occbuild --help to get an overview of the different options occbuild understands. As a simple example, let's suppose we're building a module called demo that consists of the following files:

To compile this, you would need to execute the following commands:

occbuild --object foo.occ
occbuild --object bar.occ
cc `occbuild --cflags` -c baz.c
cc `occbuild --cflags` -c quux.c
occbuild --library demo.lib --include demo.inc foo.tce bar.tce baz.o quux.o

The result would be the occam library file demo.lib and a module include file demo.module plus whatever other files the occam implementation you're using needs -- for example, it will also generate libdemo.so for KRoC, and demo.precomp for the Transterpreter.

To install the module to the system library location, you would say:

occbuild --install demo.lib demo.inc

To compile a program wibble.occ, you can just say:

occbuild --program wibble.occ

... which produces wibble. (For the Transterpreter, wibble is a wrapper script that runs wibble.tbc using tvm.) If wibble.occ wants to use the demo library, it only has to say #INCLUDE "demo.module" in its source; everything else necessary to use the library is now handled automatically by KRoC and the slinker.

occbuild supports many other options to select the toolchain to use and the installation path, define preprocessor symbols for the occam compiler, and so on; see the --help output for more information.

However, you won't normally need to invoke occbuild by hand; it should be run by whatever build system you're using for your library, just like any other compiler. occbuild deliberately is not a complete build system -- there are plenty of good ones already!

Packaging a library using occbuild

(I'm only going to talk about automake here for now; occbuild should integrate just as happily with SCons, but I haven't tried it yet.)

occbuild provides an occbuild.m4 aclocal file that can be used to easily integrate it into automake-based packages. It is installed into ${prefix}/share/aclocal by default, which means you'll need to provide aclocal with an appropriate -I flag in order to find it if you're rebuilding your configure script. (The KRoC setup.sh script sets ACLOCAL appropriately.)

In your configure.ac file, you can just say:

OCCAM_OCCBUILD

... to locate occbuild in the path; this also gives your configure script a --with-toolchain option that can be used to choose which toolchain to use. The macro defines OCCBUILD and OCCBUILD_CFLAGS for use in Makefile.ams. There's also an OCCAM_INCLUDE macro that can be used to test for the presence of an occam include file (or module file); see occbuild.m4 for more details.

A Makefile.am for the above examples might look like:

@SET_MAKE@

AUTOMAKE_OPTIONS = foreign no-dependencies

OCCBUILD = @OCCBUILD@
OCCAM_DEFS = @OCCAM_DEFS@
CFLAGS = @CFLAGS@ @DEFS@ @OCCBUILD_CFLAGS@

EXTRA_DIST = \
        foo.occ \
        bar.occ \
        demo.inc \
        baz.c \
        quux.c \
        wibble.occ

demo_lib_objs = \
        foo.tce \
        bar.tce \
        baz.o \
        quux.o

all-local: demo.lib wibble

demo.lib: $(demo_lib_objs)
        $(OCCBUILD) --library demo.lib --include demo.inc $(demo_lib_objs)

install-exec-local: demo.lib demolib.inc wibble
        $(OCCBUILD) --install --prefix "$(prefix)" --destdir "$(DESTDIR)" demo.lib demo.inc wibble

clean-local:
        $(OCCBUILD) --clean demo.lib $(demo_lib_objs) wibble

SUFFIXES = .occ .tce .lib

.c.o:
        $(CC) $(CFLAGS) -c $<

.occ.tce:
        $(OCCBUILD) $(OCCAM_DEFS) --object $<

%: %.occ
        $(OCCBUILD) --program $<

Toolchain-specific behaviour

occbuild defines the preprocessor symbol OCCBUILD.KROC or OCCBUILD.TVM in occam depending on which toolchain you're compiling for; you can use this with #IF directives to conditionally disable inappropriate library features.

OCCBUILD_KROC or OCCBUILD_TVM is also defined as a C preprocessor macro by --cflags so you can do the same in C FFI files.

occbuild.m4 similarly provides OCCBUILD_KROC and OCCBUILD_TVM as automake conditionals; this lets you use if directives to choose what will be compiled in your Makefile.am files.

OccBuild (last edited 2007-07-02 16:07:57 by ats1)