service/protocol-plugin/lib/cpluff/examples/INSTALL.txt

   1 INSTALLING C-PLUFF EXAMPLES
   2 ===========================
   3
   4 This directory includes examples of extensible applications based on
   5 C-Pluff. You can build the examples as part of the C-Pluff source tree at
   6 the same time as building the C-Pluff implementation or as a stand-alone
   7 build using an already installed C-Pluff instance.
   8
   9 These are generic build and installation instructions. For more
  10 information on an individual example, see README.txt in the corresponding
  11 subdirectory.
  12
  13
  14 Building as part of the C-Pluff source tree
  15 -------------------------------------------
  16
  17 This build method can be used if you are building the C-Pluff
  18 implementation and the examples at the same time using the supplied GNU
  19 autotools based build environment. If this is not the case, skip to the
  20 next section.
  21
  22 Configure C-Pluff as usual using the configure script in the top level
  23 source directory. To build and install the examples make targets
  24 "examples" and "examples-install", respectively, in the top level source
  25 directory. This will build and install the C-Pluff implementation together
  26 with the example applications.
  27
  28 Notice that example applications will be installed into the same prefix
  29 as the C-Pluff implementation.
  30
  31
  32 Building in stand-alone mode using GNU autotools
  33 ------------------------------------------------
  34
  35 This build method more correctly reflects the way real independent
  36 applications would be built. It is assumed that you already have an
  37 installed C-Pluff instance and you wish to configure, build and install
  38 the example applications separately using GNU autotools. If you wish to
  39 use Windows specific tools, skip to next section.
  40
  41 If you don't have write access to the example source directory (because
  42 it is part of the installed C-Pluff documentation), make a personal copy
  43 of the source directory.
  44
  45   cp -r INSTALLED_SOURCE MY_SOURCE
  46
  47 To use this build method, you must have some GNU tools installed because
  48 the C-Pluff source distribution does not ship intermediate build system
  49 files for examples. You will need these tools anyway if you are about to
  50 develop applications using a build system similar to these examples. The
  51 version numbers in parentheses are known working versions.
  52
  53   - GNU Autoconf (2.61)
  54   - GNU Automake (1.10)
  55   - GNU libtool (1.5.22)
  56
  57 To bootstrap the build system, run the autogen.sh script in the source
  58 directory. It will invoke the above mentioned GNU tools to generate
  59 intermediate build system files.
  60
  61   ./autogen.sh
  62
  63 Alternatively, if you want to get more familiar with the process, you can
  64 browse through the script and execute the necessary commands manually.
  65
  66 Now you should have a build system in place and you can configure and
  67 build the examples using the standard autotools procedure.
  68
  69   Building in the source directory:
  70     ./configure
  71     make
  72
  73   Building in a separate build directory:
  74     cd BUILD_DIR
  75     SOURCE_DIR/configure
  76     make
  77
  78 When configuring, you can use the --prefix option to choose another
  79 installation prefix for the examples (the default is /usr/local).
  80
  81 If C-Pluff has been installed into a location that is not included in the
  82 standard include or library path then you have to specify some additional
  83 environment variables to the configure script. Assuming that C-Pluff was
  84 installed into /usr/local (the default), you would have to set following
  85 environment variables before calling configure.
  86
  87   CPPFLAGS="-I/usr/local/include"
  88   LDFLAGS="-L/usr/local/lib"
  89   CPLUFF_LOADER="/usr/local/bin/cpluff-loader"
  90
  91 Finally, install the example applications.
  92
  93   make install
  94
  95
  96 Building in stand-alone mode using Microsoft Visual C
  97 -----------------------------------------------------
  98
  99 This build method is specific to Microsoft Visual C. It is provided
 100 separately because of complexity involved in setting up more generic GNU
 101 tools on Windows platform. Be warned that this build method is not being
 102 tested as often as the GNU autotools based build method. Please report
 103 any problems to the C-Pluff users mailing list.
 104
 105 The included build environment and these instructions were initially
 106 tested with Microsoft Visual C++ 2005 Express Edition. The build
 107 environment relies only on command line tools. It is assumed that the
 108 given commands will be entered into command prompt.
 109
 110 As the first step, you have to set up correct paths in common.nmake using
 111 Notepad or some other text editor. If you are building example source that
 112 has been extracted from cpluff-VER.zip (or cpluff-VER-only.zip) Windows
 113 distribution then the default settings should be fine. Examples will be
 114 installed to the same path as the C-Pluff implementation by default.
 115
 116 Before trying to use the Visual C command line tools, you have to set up
 117 required environment variables by executing vcvarsall.bat in the Visual C
 118 installation directory. Alter the path in the following example as
 119 necessary for your installation.
 120
 121   C:\"Program Files"\"Microsoft Visual Studio 8"\VC\vcvarsall
 122
 123 The C-Pluff Windows distribution includes a precompiled C-Pluff runtime
 124 library as DLL. Additionally, on Windows platform you will also need a
 125 corresponding import library to be able to compile software that uses a
 126 DLL. For some reason import libraries generated by different Windows
 127 compilers (MinGW, Visual C, Borland C, etc.) are generally incompatible.
 128 The C-Pluff Windows distribution only includes an import library for MinGW
 129 (libcpluff.dll.a) so you have to generate one for Visual C.
 130
 131 This can be done using the Microsoft Library Manager, or lib.exe, and the
 132 export definitions provided in libcpluff.def. Execute the following
 133 command in the library directory containing libcpluff.def.
 134
 135   lib /machine:I386 /name:libcpluff-0.dll /def:libcpluff.def /out:libcpluff.lib
 136
 137 This should generate libcpluff.lib, an import library for Visual C.
 138
 139 Now you should be ready to build the examples. Build the examples by
 140 making target "all" in Makefile.nmake in the examples directory using
 141 nmake.
 142
 143   nmake /f Makefile.nmake all
 144
 145 This compiles the examples but does not yet install them.  To install
 146 required files to the installation directory make target "install" in
 147 Makefile.nmake in the examples directory using nmake.
 148
 149   nmake /f Makefile.nmake install