/*
 * $Id: howtobld.txt 9312 2008-09-05 00:08:34Z vszakats $
 */

In the last phase of install process if bash shell is available in the
system then few bash scripts are created to make compiling and linking
with Harbour a little easier. There are compiler and linker wrappers
called "hbcc", "hbcmp", "hblnk" and "hbmk".

"hbcc" is a wrapper to the C compiler only. It sets all flags
and paths necessary to compile .c files which include Harbour header
files. The result of its work is an object file.

Use "hbcmp" exactly as you would use the harbour compiler itself.
The main difference with hbcmp is that it results in an object file,
not a C file that needs compiling down to an object. hbcmp also
ensures that the harbour include directory is seen by the harbour compiler.

"hblnk" simply takes a list of object files and links them together
with the harbour virtual machine and run-time library to produce an
executable. The executable will be given the basename of the first object
file if not directly set by the "-o" command line switch.

"hbmk" tries to produce an executable from your .prg file. It's a simple
equivalent of cl.bat from the CA-Cl*pper distribution.

All these scripts accept command line switches:
-o<outputfilename>      # output file name
-static                 # link with static Harbour libs
-fullstatic             # link with all static libs
-shared                 # link with shared libs (default)
-mt                     # link with multi-thread libs
-gt<hbgt>               # link with <hbgt> GT driver, can be repeated to
                        # link with more GTs. The first one will be
                        #      the default at runtime
-xbgtk                  # link with xbgtk library (xBase GTK+ interface)
-hwgui                  # link with HWGUI library (GTK+ interface)
-l<libname>             # link with <libname> library
-L<libpath>             # additional path to search for libraries
-fmstat                 # link with the memory statistics lib
-nofmstat               # do not link with the memory statistics lib (default)
-[no]strip              # strip (no strip) binaries
-main=<main_func>       # set the name of main program function/procedure.
                        # if not set then 'MAIN' is used or if it doesn't
                        # exist the name of first public function/procedure
                        # in first linked object module (link)

Link options work only with "hblnk" and "hbmk" and have no effect
in "hbcc" and "hbcmp".
Other options are passed to Harbour/C compiler/linker.

An example compile/link session looks like:
----------------------------------------------------------------------
druzus@uran:~/tmp$ cat foo.prg
function main()
? "Hello, World!"
return nil

druzus@uran:~/tmp$ hbcmp foo
Harbour Compiler Alpha build 46.2 (Flex)
Copyright 1999-2006, http://www.harbour-project.org/
Compiling 'foo.prg'...
Lines 5, Functions/Procedures 2
Generating C source output to 'foo.c'... Done.

druzus@uran:~/tmp$ hblnk foo.o

druzus@uran:~/tmp$ strip foo

druzus@uran:~/tmp$ ls -l foo
-rwxrwxr-x    1 druzus   druzus       3824 maj 17 02:46 foo
----------------------------------------------------------------------

or using hbmk only:
----------------------------------------------------------------------
druzus@uran:~/tmp$ cat foo.prg
function main()
? "Hello, World!"
return nil

druzus@uran:~/tmp$ hbmk foo
Harbour Compiler Alpha build 46.2 (Flex)
Copyright 1999-2006, http://www.harbour-project.org/
Compiling 'foo.prg'...
Lines 5, Functions/Procedures 2
Generating C source output to 'foo.c'... Done.

druzus@uran:~/tmp$ ls -l foo
-rwxrwxr-x    1 druzus   druzus       3824 maj 17 02:46 foo
----------------------------------------------------------------------


You will find additional wonderful tools: /usr/bin/hbrun
You can run clipper/xbase compatible source files with it
if you only put in their first line:
#!/usr/bin/hbrun

For example:
----------------------------------------------------------------------
druzus@uran:~/tmp$ cat foo.prg
#!/usr/bin/hbrun
function main()
? "Hello, World!, This is a script !!! :-)"
?
return nil

druzus@uran:~/tmp$ chmod +x foo.prg

druzus@uran:~/tmp$ ./foo.prg

Hello, World!, This is a script !!! :-)

druzus@uran:~/tmp$

I hope you will find this information useful,
Przemyslaw Czerpak (druzus/at/priv.onet.pl)
