$Id: howtobuild.txt 60 2006-04-03 15:40:51Z epocman $ IBPP, A c++ Client API for Firebird (and Interbase) HOW TO INTEGRATE AND USE IBPP IN YOUR OWN PROGRAMMING --------------------------------------------------------------------------- (C) Copyright 2000-2006 T.I.P. Group S.A. and the IBPP Team (www.ibpp.org) The contents of this file are subject to the IBPP License (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.ibpp.org or in the 'license.txt' file which must have been distributed along with this file. This software, distributed under the License, is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. --------------------------------------------------------------------------- Dear developers, This is a short documentation instructing you how to integrate IBPP source code in your own projects. Starting with version 2.5 IBPP does not provide anymore a stand-alone build procedure. IBPP is a set of C++ classes. A small hand of .h and .cpp files implement them. You might wish to compile them separately in a lib, then use the lib in your own programs, but it is as well easy, if not easier and safer, to properly integrate IBPP source core inside your own applications build procedure. Here are guidelines to help you do that. (*) WHICH FILES TO INTEGRATE Choose a proper location in your own source code tree of folders and files to host the ibpp files. A good idea would be to create a folder named 'ibpp' where you see fit. Now unzip the distribution archive to that ibpp folder. In that ibpp folder you will find some *.txt files, including _this_ file. There will also be a sub-folder named 'core'. It has all the files you need to integrate to your build procedure. All the other folders are only there to support the development and testing of ibpp itself. You don't need to compile and link anything else than what is in the 'core' folder to your own application. An alternate way, if you have for instance multiple programs which all use ibpp, would be to host the 'ibpp' folder in a common place to all these programs and simply reference those 'ibpp/core' files at that common location from your multiple build procedures. Out of the files which are located in the 'ibpp/core' folder, 'ibpp.h' is the only one which you will need to #include from your own code files which use ibpp interfaces. That may be all your files, or only a subset of them. Wether you include the 'ibpp.h' file from another central header file of your project, or locally from within each code file which use ibpp does not matter. All the other code files (*.cpp) of the 'ibpp/core' folder must be compiled and linked with your application as if they were original portions of your application, except the file 'all_in_one.cpp'. There are less than 20 code files, this is very easy to add to your Makefile, or visual project file. In a Visual Studio Project, you might conveniently add a "group" (or "filter") named 'ibpp' and there 'add' the existing .cpp files from the 'ibpp/core' folder. It is probably even more straightforward to do in your existing Makefile on unix. You can obviously even simplify your integration work by just adding the file 'all_in_one.cpp' in your build procedure. In turn, this file includes all the others. This is why you must either include all .cpp files except all_in_one or *only* include all_in_one.cpp. All the header files (*.h), other than 'ibpp.h' itself are included by one or multiple of the core code files. They are NOT included by 'ibpp.h' itself. You should not have anything to do regarding those files. They should be found automatically while compiling the core source files (because they are in the same directory than the code files themselves). (*) WHAT SPECIFIC COMPILER OPTIONS / SETTINGS TO USE Generally speaking, don't tamper with the settings of your own projects just for the purpose of compiling in and linking in ibpp. The advantage of integrating ibpp source code in this manner is precisely here : it helps be sure that the ibpp code has been compiled in a compatible manner with all the code of your application. At the cost of setting up ibpp inside your build procedure you will quickly discover that it brings you multiple advantages. Switching between debug and release builds is easier. The ibpp code follows yours, as if it was your own code. Finding source files while debugging is generally automatic, making for easier debugging sessions where you can trace execution inside ibpp code itself very easily. Your compiler or linker might even find more opportunities for optimizations in such a setup. Despite the generic above recommendation not to tamper with your own settings due to ibpp, there are some things you need to do though. First and foremost, ibpp requires C++ Exceptions and RunTime Type Information to be supported and enabled in your compiler. These are part of the C++ Standard and as such, no modern compiler should have C++ Exceptions and Runtime Type Information disabled by default. If they happen to be disabled, you will have to enable them, at the least for all ibpp code files and for all of _your_ code files which do include and use ibpp. Second, ibpp use the C++ Standard library (a very minimal subset of the STL part of it, indeed). Again that should not require you to turn on a switch on your compiler, but if you need to, you have to do so. Third, all ibpp/core files and your files which use ibpp interfaces _must_ be compiled with some defines. You can define the required values on the compiler command-line (through Makefile for instance) or insert those in the properties of your visual projects. You can also #define them somewhere at an appropriate location in one header file of your project, but you have to define them. They drive some conditional code inside the source code of IBPP. Those required preprocessor definitions start in "IBPP_" so they are likely not to conflict with any existing definitions in your own code. To keep things simple, you might want to globally compile all of your application code with those definitions, no matter if they use or reference ibpp or not. It should not harm anything to do so. The required prepocessor definitions are documented near the top of the ibpp.h header file. Please review it for the details. Currently one define is used to select the platform. To the contrary of previous IBPP versions, the compiler is auto-detected by recognizing some hard-coded predefined macros provided by each supported compiler. That's all! (*) WITH WHAT COMPILERS IS IBPP REPORTED TO BE WORKING Well, a lot of compilers and environment indeed. The IBPP source code has very minimal needs to interface to your system. It is then largely portable C++ Standard code. You will find very few conditionals inside IBPP source code. IBPP is known to be useable or in useage on the following platforms and compilers. The real list is probably much longer. - Nearly all Linux or Unix systems using GCC 3.2 or higher, wether big-endian or little-endian. This also include Mac OS X 'darwin' system. - Nearly all Windows compilers, provided that they have a decent C++ Standard library implementation or can be fitted one optional correct one. This at least includes Visual Studio 2005, 2003, and 6.0. Add Borland C++ Builder 6, the Borland free C++ compiler, cygwin, mingw, dmc (Digital Mars Compiler). - 32 bits or 64 bits platforms. (*) COMPILING THE 'TESTS' PROGRAMS The tests programs are located in the 'ibpp/tests' folder. You never need to compile those tests programs as part of your applications. That code is NOT part of IBPP. It is part of the project because it is used to run the most basic tests when developing IBPP itself. You can of course build the tests programs in order to verify that IBPP works correctly with you installed server. Compiling the tests program is easy. It merely needs to compile and link the tests.cpp file along with those of the 'ibpp/core' folder. To make things easier and to give samples of build procedures showing integration of IBPP in another application build system, you will find various procedures in sub- folders of the 'tests' folder. - unixes: contains a Makefile which should build the tests executable without issues, out of the box, on most linux and unixes systems. At least those where IBPP was tested at least once. - bcb6: contains both a visual project and a 'simplest-build.bat' file, which target Borland C++ Builder 6 (visual or command-line compiler). The 'simplest-build.bat' file is really dumb but shows that there is no black magic in compiling IBPP code along with your application code. - vs2005: contains both a visual project and a 'simplest-build.bat' file, which target Microsoft Visual Studio 2005 (visual or command-line compiler). The 'simplest-build.bat' file is really dumb but shows that there is no black magic in compiling IBPP code along with your application code. It should work too for Visual Studio .NET 7.x and possibly for Visual Studio 6.0. (*) TIPS AND TRICKS (o) SVN CLIENT ON WINDOWS If you want a very nice and well-done SVN client for Windows, I recommend you TortoiseSVN (http://tortoisesvn.tigris.org). This is an excellent piece of software. This SVN client integrates completely with the Windows Explorer UI. All SVN interactions are very easy to do and what's more the SSH functionnality is built-in ! Give it a try. -- Olivier Mascia om at tipgroup dot com *** EOF ***