Synesis Software STLSoft - ... Robust, Lightweight, Cross-platform, Template Software ...

Building and Linking to the Libraries

Installing the library

shwild comes as a source-only distribution, meaning that you will need to build the library before you can use it. The library depends on two other projects - cstring and STLSoft. If you wish to build shwild using the makefiles supplied, you will need to have defined the STLSOFT environment variable to be the root directory of the STLSoft include files, and the CSTRING_ROOT environment variable to be the root of the cstring installation. In addition, you will need to have built the cstring libraries for your compiler (e.g. cstring.3.dm.debug.lib and cstring.3.dm.lib), using the makefiles provided in the cstring distribution.

The distribution is in the form of a zip file, e.g. shwild-0.9.1.zip which you should extract (recursively) to a location of your choice, e.g. c:\opensrc\shwild\0.9, or ~/opensrc/shwild/0.9, which will be referred to in the subsequent documentation as <SHWILD-install-dir>.

Building the library for your compiler(s)

Via makefile

Makefiles for all the main supported compilers are included in the subdirectories of the build directory. For example, the makefile for Borland C/C++ v5.6 is in build/vc6. Since Borland is only supported on Windows, there is a single makefile called makefile.

Hence, to build shwild for Borland C/C++ 5.6 you need open a Windows command box (with the environment set up for the compiler and linker) and execute the following command:

  <SHWILD-install-dir>\build\bc56> make -f makefile

or just:

  <SHWILD-install-dir>\build\bc56> make

Note:
For compilers that are supported on more than one platform, there are several makefiles located in the build sub-directory. For example, for GNU C/C++ v3.4 (in <SHWILD-install-dir>/build/gcc34) both makefile.unix and makefile.win32 are provided. Most make tools require that you explicitly specify the makefile name (using -f) to use such makefiles, e.g. make -f makefile.unix.
This will build the shwild library, and the C test programs. It will also attempt to build the C++ test programs. Since the C++ mapping relies on the STLSoft and cstring libraries, the makefile will look for the environment variables STLSOFT and CSTRING_ROOT: it specifies -I%STLSOFT%/include -I%CSTRING_ROOT%/include (Windows) / -I$STLSOFT/include -I$CSTRING_ROOT/include (UNIX) to the compiler, and %CSTRING_ROOT%/lib (Windows) / $CSTRING_ROOT/lib (UNIX) to the linker.

With the Visual C++ 6.0 project file

Also included are Visual C++ 6.0 project files for the core library and the samples and test programs. These files can be read (and converted) by any later version of Visual C++.

Just open the workspace file shwild_vc6.dsw, located in the root directory (i.e. <SHWILD-install-dir>), and select the Build-All option.

Note:
You will still need to have the STLSOFT and CSTRING_ROOT environment variables set up correctly.

Linking the library

There are two options for linking to the core library: explicit linking and implicit linking.

Note:
There is no notion of "linking" to the C++ mapping because it is 100% header-only.

Explicit Linking

Explicit linking requires that you stipulate the requisite library name (and associated path) to your compiler/linker. Since shwild depends on cstring, this will also involve linking to the appropriate cstring library. (For the purposes of the following discussion, use of version 3.4 of the cstring library is assumed.)

For example, if you are using the Borland compiler, version 5.6, you would link to the libraries shwild.0.bc56.debug.lib and cstring.3.bc56.debug.lib in a debug build and shwild.0.bc56.lib cstring.3.bc56.lib in a release build. Say you wish to compile and build the example_c_1.c sample, that resides in <SHWILD-install-dir>\samples\c\example_c_1.c.

You could compile it:

<SHWILD-install-dir>\samples\c\example_c_1.c6> bcc32 -c -I..\..\..\include

and then link it:

<SHWILD-install-dir>\samples\c\example_c_1.c6> bcc32 -L..\..\..\lib -L%CSTRING_ROOT%\lib example_c_1.obj shwild.0.bc56.lib cstring.3.bc56.lib

With most compilers, you can do this in one step, as in:

<SHWILD-install-dir>\samples\c\example_c_1.c6> bcc32 -I..\..\..\include -L..\..\..\lib -L%CSTRING_ROOT%\lib example_c_1.c shwild.0.bc56.lib cstring.3.bc56.lib

Optional Implicit Linking

Some compilers support implicit linking, which involves the compiler inserting information into the object file during the compilation phase that directs the linker to the name of the required library. shwild supports implicit linking for Borland, Metrowerks CodeWarrior, Intel, and Visual C++ compilers. To use implicit linking, simply #include the files <shwild/implicit_link.h> and <cstring/implicit_link.h> in the file that is using the shwild library, as in:

  #include <shwild/shwild.h>
  #include <shwild/implicit_link.h>
  #include <cstring/implicit_link.h>

  int main()
  {
    shwild_match("1?2", "122", 0);

    return 0;
  }

When you compile and link this file you will not have to specify the library name. You will still have to specify the library path, however, if it is not in the default linker path(s) for your compiler/linker. The above example reduces to:

<SHWILD-install-dir>\samples\c\example_c_1.c6> bcc32 -I..\..\..\include -I%CSTRING_ROOT%\include -L..\..\..\lib -L%CSTRING_ROOT%\lib example_c_1.c

but not to:

<SHWILD-install-dir>\samples\c\example_c_1.c6> bcc32 -I..\..\..\include -I%CSTRING_ROOT%\include example_c_1.c

(whereupon the compiler will complain about not knowing the location of shwild.0.bc56.lib or cstring.3.bc56.lib).

There are two advantages of implicit linking:

  1. If you build your product in several versions (e.g. debug and release), you do not have to worry about specifying the different names of the requisite libraries.
  2. If you use libraries that are dependent on other libraries, you do not have to remember which other library names are needed by the intermediate libraries.

Note:
: In both cases above (indeed, in all cases), you do need to provide the linker with the library directories if they do not reside in the default linker path(s) for your compiler/linker
shwild Library documentation © Matthew Wilson and Sean Kelly, 2004-2006 SourceForge.net Logo