|
cstringC-style string definition and manipulation library |
Updated: 13th May 2008 |
Installation
This page gives a guide to unpacking, building and using the cstring library.
Unpacking
cstring comes in a zip file, which you should unpack, preserving the directory structure, into a location of your choice. We'll call this root directory the installation directory, and will refer to it as CSTRING_ROOT for the remainder of this discussion.
Note: You are advised to create a CSTRING_ROOT environment variable, defined to the installation directory. This allows you to move, or update, cstring when required without requiring changes in software that depends on it.
Building the library
cstring comes as a source-only distribution, which means that you have to compile it yourself in order to use it. It requires only a C compiler and standard library headers and libraries, and, on Win32, the Windows headers and libraries.
Makefiles are provided for the following compilers, in the given subdirectories:
| Compiler | Version | Compiler Identity | makefile directory | Operating system | makefile |
| Borland C/C++ | 5.5 | bc55 | CSTRING_ROOT/build/bc55 | Win32 | makefile |
| 5.5.1 | bc551 | CSTRING_ROOT/build/bc551 | Win32 | makefile | |
| 5.6 | bc56 | CSTRING_ROOT/build/bc56 | Win32 | makefile | |
| 5.6.4 | bc564 | CSTRING_ROOT/build/bc564 | Win32 | makefile | |
| Comeau C++ | 4.3.3 | como433 | CSTRING_ROOT/build/como433 | UNIX | makefile.unix |
| CSTRING_ROOT/build/como433 | Win32 | makefile.win32 |
To build cstring with your compiler, open a shell / command prompt in the given makefile directory, and execute your make command, as in:
- to build for Borland C/C++ 5.5.1, you would type "make" in CSTRING_ROOT/build/bc551.
- to build for GCC C/C++ 4.0 on Mac OS-X, you would type "make -f makefile.mac" in CSTRING_ROOT/build/gcc40.
Once the compilation and linking has completed, the library can be found in CSTRING_ROOT/lib. The name of the library is formed according to the following pattern:
cstring.<MAJOR-VERSION>.<COMPILER-IDENTITY>.<THREADING-IDENTITY>.<DEBUG-IDENTITY>.<LIBRARY-EXTENSION>
where the pattern elements are defined as:
| <MAJOR-VERSION> | The major version of the cstring library, e.g. 3 |
| <COMPILER-IDENTITY> | The compiler identity, e.g. Visual C++ 7.1 is vc71. (See the table above for a full list) |
| <THREADING-IDENTITY> | The compiler identity: mt for multithreaded, dll for multithreaded-DLL, nothing for single-threaded |
| <DEBUG-IDENTITY> | The debug identity: debug for debug, nothing for release |
| <LIBRARY-EXTENSION> | The library extension for the platform: a for UNIX, lib for Win32 |
Therefore, the libraries built from the commands given above could be:
cstring.3.bc56.debug.lib,
cstring.3.bc56.lib,
cstring.bc56.debug.lib,
and
cstring.bc56.lib
and
cstring.3.como433.debug.a,
and
cstring.3.como433.a
Using the library
Once you have built cstring, you use it by #include-ing the cstring/cstring.h file in your C/C++ source file, and linking to the appropriate library for your compiler. There are two sample programs supplied in the distribution that demonstrate how this is done.
Some compilers support implicit linking: whereby a #pragma in a source file inserts a linker record into the object file that the linker reads, meaning that the library file does not need to be explicitly expressed in the link step. The compilers for which cstring supports explicit linking are Borland, Intel (Win32-only), Metrowerks (Win32-only) and Visual C++. To use explicit linking with these compilers, simply #include the cstring/implicit_link.h file in your C/C++ source file.