
                        X H A R B O U R - Using Xharbour library as SO

                                 For end users - HOWTO

                                  Giancarlo Niccolai

                                    gian@nccolai.ws


$Id: linuxso_howto.txt,v 1.3 2004/03/07 14:42:22 likewolf Exp $
/*  $DOC$
 *  $FUNCNAME$
 *      Using Xharbour library as SO
 *  $CATEGORY$
 *      Xharbour Enhacements
 *  $ONELINER$
 *      Faq to xharbour libraries as SO
 *  $DESCRIPTION$
 *      ABSTRACT
 *      
 *      This document is a short howto that guides the users in building shared object
 *      libraries for GNU/linux, and other unix like systems using ELF relocatable code
 *      system and GNU gcc compiler.
 *      
 *      Shared libraries, called also shared objects, are useful to the final user
 *      because of many reasons. The main advantage with respect to using a single
 *      monolythic file is that the resulting executable (binary) file is considerably
 *      smaller (often by orders of degree) to a statically linked one. If an application
 *      is composed of a set self-standing programs, this turns out to be a great advantage,
 *      as the complete application can be delivered and updated with "smaller" media, or
 *      making it available via internet becomes easy.
 *      
 *      In applications that are interactively loaded and unloaded many times, like CGI,
 *      the program size is important, as the program loader can load it in memory in less
 *      time, making the application responding more promptly. In fact, the shared library
 *      is loaded in memory once, and then held there as long as possible. Also, if many
 *      programs are using the same shared library, it will be loaded only once, sparing
 *      memory and system resources.
 *      
 *      PREREQUISITES
 *      
 *      Before creating the so libraries you need, you must know that:
 *      
 *      - Shared object are better to be installed in "well known positions"; this requires
 *        you and your customer to be able to access system directories as root or equivalent
 *        privileges. See http://www.visi.com/~barr/ldpath.html to have an in depth
 *        reason why this should be that way.
 *      
 *      - Your ld.so.conf should be correctly configured. In GNU/Linux and many other systems,
 *        the paths /lib and /usr/lib are generally linked in the program loader modules;
 *        usually also /usr/local/lib is, but in Red Hat distribution (and related, like
 *        Mandrake) it is not; then you should add /usr/local/lib to your /etc/ld.so.conf file,
 *        that is the preferred path to store libraries that are not part of the distribution
 *        packages (and is here taken as the default installation path).
 *      
 *      - HB_BIN_INSTALL and HB_LIB_INSTALL must be respectively set to where your harbour
 *        binaries and static librearies are residing. If you have your libraries installed
 *        in a system path, like /usr/local/lib, you will need to be root to complete the
 *        process, while if you have them installed somewhere else, you will need only
 *        local access to build the shared objects, but root access is still needed to
 *        install the libraries.
 *      
 *      - HB_MT should be set to "MT" if you want to build Multithreading capable
 *        libraries, while HB_GT_LIB should be set to the gtxxx api you want to use
 *        for terminal input output. This variables are taken as defaults, and can
 *        be overriden, so you don't really need to set them or change them now.
 *      
 *      CREATING THE SHARED OBJECTS
 *      
 *      An utility called bld_solib.sh is found in your harbour binary path. It is
 *      used to build the libraries. Invoking it results in library creation using
 *      the current HB_MT and HB_GT_LIB setting. The "-?" command line options gives
 *      a short usage and description.
 *      
 *      If HB_MT is not set, single thread library will be built, and if HB_GT_LIB
 *      is not set, gtsln will be used (slang terminal library). This defaults can
 *      be overriden in command line: the option -s will force single thread library
 *      creation, while -t will force multi threading. Using -g gtxxx you can chose
 *      one of the unix oriented gt libraries: gtcrs will use ncurses library, gtcgi
 *      will create a shared library that has output suitable for CGI applications,
 *      but also for daemons, and gtnul will produce no output at all.
 *      
 *      The resulting shared object will have the following naming convention:
 *      
 *         libharbour(mt)-xxx.so
 *      
 *      The mt postifx will be added if the library can be used for multithreading
 *      applications, while xxx are the last 3 letters of the gt library: crs, nul
 *      sln, or cgi.
 *      
 *      The library will be placed in HB_LIB_INSTALL; you can then move it in the
 *      place where you need it.
 *      
 *      * NOTICE: the resulting library is stripped of debug symbols. To have
 *        debug symbols left in, you can use the -n option.
 *      
 *      
 *      
 *      INSTALLING A LIBRARY
 *      
 *      Installation can be made by hand by using the "-i" option of bld_solib.sh.
 *      The installtion directory defaults to /usr/local/lib, and can be changed with
 *      "-I instdir" option. The script takes care of MOVING the library to the
 *      installation path, creating a valid SO name with current version of xharbour
 *      libs, creating consistent links for real name and linker name, and then
 *      calling ldconfig.
 *      
 *      * NOTE: if your ld.so.conf does not include the target directory, ldconfig
 *        will be called anyway, but it will have not any effect.
 *      
 *      
 *      
 *      USING A LIBRARY
 *      
 *      With a library correctly installed and "ldconfig"ured in a library system
 *      directory, building an xharbour program becomes pretty easy:
 *      
 *      $ harbour filename
 *      $ gcc -o filename filename.c -I $HB_INC_INSTALL -lharbour(mt)-xxx -lm
 *      
 *      Math library is always required (-lm). The If your program uses
 *      multithreading, you will have to add -lharbourmt-xxx, while you will need
 *      -lharbour-xxx for Single thread applications; xxx is here the gt library
 *      name you have compiled the library for. If your compilation is multithreading,
 *      you will also have to add -lpthread, and if you have libraries compiled with
 *      gpm support, you will also need -lgpm. Finally, slang support requires -lslang.
 *      
 *      In example:
 *      
 *      $ gcc -o filename filename.c -I $HB_INC_INSTALL -lharbourmt-sln \
 *            -lm -lslang -lgpm -lpthread
 *      
 *      
 *      The compiled program will work out of the box, and will also be loadable
 *      in other systems that have the xharbour library configured in one of the
 *      system library directory (or a directory that is present in /etc/ld.so.conf).
 *      
 *      
 *      If your library is NOT installed, things are a little more tricky: You will
 *      have to add -Lpath to "gcc" invocation, and also set LD_LIBRARY_PATH to
 *      where your library is stored before to launch the program.
 *      
 *      
 *      
 *      THANKS
 *      
 *      To Przemyslaw Czerpak, that has created the hb-mkslib.sh script that
 *      transforms harbour static libraries in .so files. The bld_solib.sh is
 *      just a wrapper/utility.
 *
 *  $END$
 */
