Building and Linking to the Libraries

Installing the library

b64 comes as a source-only distribution, meaning that you will need to build the library before you can use it. The core library is self-contained, but the C++ layer depends on the STLSoft libraries (an open-source, 100% header-only, suite of lightweight C++ libraries, also using the BSD license).

The distribution is in the form of a zip file, e.g. b64-1.1.1.zip which you should extract (recursively) to a location of your choice, e.g. c:\opensrc\b64\1.1, or ~/opensrc/b64/1.1, which will be referred to in the subsequent documentation as <B64-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 b64 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:

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

or just:

<B64-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 <B64-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 b64 library, and the C test programs. It will also attempt to build the C++ test programs. Since the C++ layer relies on the STLSoft libraries, the makefile will look for the environment variable STLSOFT: it specifies -I%STLSOFT%/include (Windows) / -I$STLSOFT/include (UNIX) to the compiler for C++ compilation. If the STLSOFT environment variable is not defined or does not correspond to an installation of STLSoft, then the build will fail, although it will successfully build the core library and the C samples and test programs.

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 b64_vc6.dsw, located in the root directory (i.e. <B64-install-dir>), and select the Build-All option.

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++ layer 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.

For example, if you are using the Borland compiler, version 5.6, you would link to the library b64.1.bc56.debug.lib in a debug build and b64.1.bc56.lib in a release build. Say you wish to compile and build the example.c.1.c sample, that resides in <B64-install-dir>\samples\c\example.c.1.c.

You could compile it:

<B64-install-dir>\samples\c\example.c.1.c6> bcc32 -c -I..\..\..\include

and then link it:

<B64-install-dir>\samples\c\example.c.1.c6> bcc32 -L..\..\..\lib example.c.1.obj b64.1.bc56.lib

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

<B64-install-dir>\samples\c\example.c.1.c6> bcc32 -I..\..\..\include -L..\..\..\lib example.c.1.c b64.1.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. b64 supports implicit linking for Borland, Metrowerks CodeWarrior, Intel, and Visual C++ compilers. To use implicit linking, simply #include the file <b64/implicit_link.h> in the file that is using the b64 library, as in:

  #include <b64/b64.h>
  #include <b64/implicit_link.h>

  int main()
  {
    int     ints[]  =   { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
    size_t  cch     =   b64_encode(&ints[0], sizeof(ints), NULL, 0);  /* Ask for length required */
    char    *enc    =   (char*)malloc(cch);                           /* No error checking here ... real code must do so */

    b64_encode(&ints[0], sizeof(ints), enc, cch);

    printf("Converted: %.*s\n", cch, enc);

    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:

<B64-install-dir>\samples\c\example.c.1.c6> bcc32 -I..\..\..\include -L..\..\..\lib example.c.1.c

but not to:

<B64-install-dir>\samples\c\example.c.1.c6> bcc32 -I..\..\..\include example.c.1.c

(whereupon the compiler will complain about not knowing the location of b64.1.bc56.lib).

There are two advantages of implicit linking:

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.
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

b64 Library documentation © Synesis Software Pty Ltd, 2004-2007