%RED% This manual is under construction! %ENDCOLOR%

---++ Table of Contents

%TOC%

---++ Introduction

---++ Using a library

At the command-line, or in Automake.

---+++ Using =strc= at the command-line

<verbatim>
  module foo
  imports lib
  strategies
	 ...
</verbatim>

<verbatim>
  module foo
  imports liblib
  strategies
	 ...
</verbatim>

<verbatim>
  strc -i foo.str -la stratego-lib
</verbatim>

---+++ Using AutoXT and Automake

Libtool, Automake and AutoXT make separate compilation in Makefiles
almost trivial.

Use libtool for linking.
	* Invoking =libtoolize= or =glibtoolize= (MacOS X) in =bootstrap=
	* Add =AC_PROG_LIBTOOL= to =configur.ac=

Libtool will add the path of a dynamic library to the search path in
the executable. If you don't use Libtool, then you might need to set
the =LD_LIBRARY_PATH= environment variable.

For the separately compiled SSL =Makefile.xt= defines the variable
=SSL_LIBS=.

All program:
<verbatim>
  LDADD += $(SSL_LIBS)
</verbatim>

Just for the program foo:
<verbatim>
  foo_LDADD = $(SSL_LIBS)
</verbatim>

Other libraries: use =-L= and =-l=.

---++ Creating your own library

<verbatim>
  module mod
  imports liblib
	 strategies
		...
</verbatim>

---+++ Producing the C code

The Stratego Compiler strc can be used now to generate a library from
a module file.str with the command

<verbatim>
  strc -i mod.str -c -o libmod.rtee --library 
</verbatim>

This produces three files:
	* libmod.c
	* libmod.str
	* libmod.rtree

The first is the C implementation of the closure of =mod.str=. It
provides C functions for all user-defined strategies, and static C
functions for strategies generated at compile-time. The last two are
the concrete syntax and abstract syntax files for a Stratego module
with external definitions for all strategies defined in =mod.str= and
imported modules. It is now possible to import libmod in another
Stratego program, instead of mod. Note that =libmod.str= is produced
mainly for documentation, =libmod.rtree= should be used to
import. This is done automatically by the compiler as long as the file
is present.

Note that no modules from the 'library' should be imported in the
program via another path. This will lead to doubly defined strategies;
it is not allowed to extend external definitions.

---+++ Compile and link to a library

The C program =libmod.c= can be compiled to an object file =libmod.o=
and to a static (=liblibmod.a=) or shared (=liblibmod.so=)
library. This should be done in a makefile; strc does not deal with C
compilation of libraries.

Static linking of the libraries thus produced may actually lead to
larger executables since no unused-function-removal is performed on
the library (for obvious reasons). Shared libraries are the solution
here to save diskspace. This can be achieved by proper use of libtool
in the buildenvironment; again strc does not provide support for this.

Compiling and linking a library using Libtool and Autmake is very
easy. Basically, the only thing you need to do is to declare that you
want to have a library:

<verbatim>
  pkglib_LTLIBRARIES	= libmod.la 
  pkgdata_DATA			= libmod.rtree

  liblibmod_la_SOURCES = libmod.c
  AM_CPPFLAGS			 = -I$(SRTS)/include -I$(ATERM)/include

  libmod.c : 
	$(STRC)/bin/strc -c --library -i ./mod.str -o libmod.rtree
</verbatim>

-- Main.MartKolthof - 23 Jun 2005