Harbour

Beginners'
Guide v1.2

Copyright © 2014 - Mario Wan Stadnik

Copyright © 2014 - Mario Wan Stadnik

 Harbour Beginners' Guide v1.2

Table of contents

Introduction ................................................................................................................2

Step-by-step ...............................................................................................................4

Conclusion ................................................................................................................ 21

1 / 23
 Harbour Beginners' Guide v1.2

Introduction

Welcome to Harbour!

This is a basic guide intended to help programmers moving from other xBase languages (f.e. CA-Clipper®)
to Harbour.

It will show all the steps from downloading and installing Harbour to build a simple program and create a
project file.

It is not intended to give all the information necessary to do the conversion of a complete application to
Harbour. For such task other considerations should be taken in place because the process can be straight
forward or pretty complex depending of how the source code was designed and eventual dependencies in
other libraries.

In some cases it will be necessary to rewrite functions that you do not have as a source code. That is a
typical situation of trying to build an application in Harbour from other xBase sources that uses an external
library Harbour does not know. Keep in mind that no library that worked for that application before will work
in Harbour. The libraries from other xBase flavors are incompatible with Harbour. If you do not have the
sources to rebuild with Harbour then you will have to substitute for other functions that will do the same or
rewrite them.

Fortunately Harbour has some of the well know libraries included and has many powerful extensions that
may directly replace what is missing or help you to create better alternatives. Please look carefully the
'Harbour directory structure' to know the libraries included.

In the last part of this guide you will find a list of websites with tutorials, manuals, guides and examples that
may be very helpful to give you more information and ideas.

2 / 23
 Harbour Beginners' Guide v1.2

For advanced users:

More information how to download and build Harbour from sources, build options, other platforms, libraries,
tools, etc..., can be found reading the README.md file directly on the GitHub website. It is not necessary to
read all that to follow this guide although it is required for those who want to build applications for other
platforms (f.e: Linux, Darwin, OS/2 etc...) and those who want to download Harbour source code, build it
and explore all the new possibilities. Harbour is compatible with Clipper® but it has many other interesting
extensions that may greatly empower your application.

More information for advanced users:

o Clipper x Harbour differences

o xHarbour x Harbour differences
o Harbour Documentation files (NanFor format)
o Harbour Changelog (History of changes)
o Harbour source files directory structure

The only requirements to follow this guide are:

(Note)
a) A computer with Windows® (XP to 10) and some free space ;

b) Time to carefully read, understand and execute the instructions;

c) Some knowledge of any xBase language.

(Note)
Harbour is multi-platform and that means it works on most operating systems but for this guide the only operating
system that is being considered is Windows®.

The guide was prepared using 'Windows® 7 Professional 32 bits' so the steps and the screen shoots may
differ a bit on other versions of that operating system.

The good news are that to install Harbour, configure and build a program are very simple and easy
tasks.

The step-by-step guide to do so will be given on the following topic.

Step-by-step

3 / 23
 Harbour Beginners' Guide v1.2

Step-by-step

Attention!  It may be easier than what you thought...

1. You have to download Harbour from the project website. Open your browser and go to http://harbour-
project.org [Fig.1]:

Fig.1 - Harbour Project home page

4 / 23
 Harbour Beginners' Guide v1.2

2. On the home page look for "Nightly binary: (exe)" [Fig.2] - that's the most updated Harbour build.
Although it is updated daily and may contain eventual bugs, it is still considered pretty safe for most users
not to mention that it will have the latest features and bug fixes. The "stable version" ('Download Harbour'
button) is not recommended because it is outdated but there is always a chance that the main developers
will create a newer one to make it available on the website. The actual version of the "Nighly binary" is
v3.2.0dev ('dev' means "in .development") - that is the recommended version to install.

Fig.2 - Detail of the download link on the home page

3. The size of the downloaded file is about 35MB and it is hosted on the Sourceforge website [Fig.3]:

Fig.3 - Details about the download of Harbour's nightly binary install file

4. Execute the install file [Fig.4]. It will require less than 400MB of your hard disk.

Fig.4 - Harbour's nightly binary install file

5 / 23
 Harbour Beginners' Guide v1.2

5. It will behave in an expected way like any other Windows® installation. It is recommended to leave the
options as they come. The default is all the components selected to install [Fig.5]:

Fig.5 - Harbour install - Choosing the components to install

6 / 23
 Harbour Beginners' Guide v1.2

6. Choose the default location to install Harbour (C:\hb32). You can change it if it is more convenient but if
you do not have a good reason for doing it then just keep it as is [Fig.6]:

Fig.6 - Harbour install - Choosing the default location to install

7 / 23
 Harbour Beginners' Guide v1.2

7. Once Harbour is installed it will create shortcuts on the program list [Fig.7a] and on the desktop [Fig.7b]:

Fig.7a - Windows® start menu and list of programs featuring Harbour shortcuts

Fig.7b - Harbour folder shortcut on the Desktop

8 / 23
 Harbour Beginners' Guide v1.2

8. On Harbour folder you will find information about 'Changelog', 'Copying', 'Release Notes' and a the README.md
with information for advanced users [Fig.8a]. You can read those files directly from the GitHub website and it is
recommended because it is better formated with working links [Fig.8b]:

Fig.8a - Harbour folder with information files

9 / 23
 Harbour Beginners' Guide v1.2

Fig.8b - Harbour on GitHub website

9. The Harbour directory structure is well organized and it is recommended to explore all the folders because it will help
you to understand what are the available libraries and other options. You will find many working examples that you give
you better idea of the formating style, good programming practices and other possibilities. Here you have the Harbour
directory structure in the form of a tree with a small explanation of what is on each folder:

10 / 23
 Harbour Beginners' Guide v1.2

Harbour directory structure

<harbour> - Main Harbour directory. Contains important
| information and the Changelog (changes history)
|
+---addons - Reserved to copy/install 3rd party Harbour
| libraries
|
+---bin - Executables, DLLs and build scripts
| Contains Harbour, HBMK2 (Harbour Make utility)
| and other related tools
|
+---comp - ANSI C compiler directory tree
| |
| +---mingw - Installed MinGW GNU C compiler (good for 32/64 bit)
| |
| +---mingw64 - Reserved for MingW64 compiler
| |
| +---mingwarm - Reserved for MinGW GNU C ARM
| |
| +---pocc - Reserved for Pelles C
| |
| +---watcom - Reserved for Open Watcom C/C++
|
+---contrib - Contrib library tree
| |
| +---3rd - 3rd party library components (internal)
| |
| +---gtalleg - GT for Allegro backend (GUI)
| |
| +---gtwvg - GUI emulation of GTWVT (win only)
| |
| +---hbamf - AMF3 file format handling (encoder/decoder)
| |
| +---hbblat - BLAT wrapper class (email - win only)
| |
| +---hbblink - BLinker compatibility
| |
| +---hbbz2 - BZ2 file compression wrapper (compression)
| |
| +---hbcairo - Cairo graphics library (imaging)
| |
| +---hbcomio - ComIO File IO redirector COM<n>: (Comm)
| |
| +---hbcomm - Comm compatibility - xhb.com, MiniGUI (Comm)
| |
| +---hbct - CA-Cl*pper Tools library
| |
| +---hbcurl - Curl library interface (IP communication)
| |
| +---hbexpat - Expat library interface (XML parser)
| |
| +---hbfbird - Firebird wrapper (SQL)
| |
| +---hbfimage - FreeImage wrapper (imaging)
| |
| +---hbformat - Harbour source code formatter tool (utility)
| |
| +---hbfoxpro - Visual FoxPro compatibility
| |
| +---hbfship - FlagShip compatibility
| |
| +---hbgd - GD API wrapper (imaging)
| |
| +---hbgt - GT library
| |
| +---hbhpdf - HaruPDF library wrapper (PDF)
| |
| +---hbhttpd - micro HTTPD server

11 / 23
 Harbour Beginners' Guide v1.2

| |
| +---hblzf - LZF API wrapper (compression)
| |
| +---hbmemio - Memory I/O (RDD)
| |
| +---hbmisc - Miscelaneous functions collection
| |
| +---hbmlzo - Mini LZO wrapper (compression)
| |
| +---hbmxml - Mini XML wrapper (XML parser/generator)
| |
| +---hbmysql - MySQL wrapper (SQL)
| |
| +---hbmzip - Mini Zip wrapper (compression)
| |
| +---hbnetio - NET I/O (RDD)
| |
| +---hbnf - NanFor library compatibility
| |
| +---hbodbc - OBDC wrapper (SQL/db)
| |
| +---hboslib - OSLib compatibility
| |
| +---hbpgsql - PostegreSQL wrapper (SQL)
| |
| +---hbsms - SMS sending functions
| |
| +---hbsqlit3 - SQLite3 wrapper (SQL)
| |
| +---hbssl - OpenSSL wrapper (encryption)
| |
| +---hbtcpio - TCP I/O file redirector
| |
| +---hbtest - Harbour test
| |
| +---hbtinymt - TyinyMT pseudo random generator wrapper
| |
| +---hbtip - TCP/IP specific communication protocol
| |
| +---hbtpathy - Telepath(y) compatibility
| |
| +---hbwin - Windows specific functions
| |
| +---hbxdiff - LibxDiff wrapper (diffing)
| |
| +---hbxpp - Xbase++ compatibility
| |
| +---hbzebra - Zebra barcode functions
| |
| +---hbziparc - Ziparc compatibility (compression)
| |
| +---rddads - ADS - Advantage Database Server (RDD)
| |
| +---rddbm - Bitmap filter (RDD)
| |
| +---rddsql - RDDSQL core
| |
| +---sddfb - RDDSQL Firebird backend
| |
| +---sddmy - RDDSQL MySQL backend
| |
| +---sddoci - RDDSQL OCILib (Oracle) backend
| |
| +---sddodbc - RDDSQL ODBC backend
| |
| +---sddpg - RDDSQL PostegreSQL backend
| |
| +---sddsqlt3 - RDDSQL SQLite3 backend
| |
| +---xhb - xHarbour compatibility

12 / 23
 Harbour Beginners' Guide v1.2

|
|
+---doc - Documentation and white-paper
|
|
+---extras - Sample files, libraries and tools ported to Harbour.
| |
| +---dbu - CA-Cl*pper DBU database utility
| |
| +---gfspell - Grumpfish Speller library
| |
| +---gtwvw - WVW library (GUI)
| |
| +---guestbk - Guest Book example with HTML
| |
| +---hbdoc - Harbour documentation generator tool
| |
| +---hbdroid - Android specific functions (very early stage)
| |
| +---hbusb - USB
| |
| +---hbvpdf - vPDF
| |
| +---hbxlsxml - XLS/XML
| |
| +---httpsrv - uHTTPD micro web server
| |
| +---ps32 - PostScript 32
| |
| +---rddado - RDD ADO to manage Microsoft ADO
| |
| +---rl - CA-Cl*pper RL
| |
| +---superlib - Superlib
| |
| +---template - Harbour library project template
|
|
+---html - HTML readers to create documentation
|
|
+---include - Include files for Harbour and 'C'
|
|
+---lib - Run-time libraries for each platform/compiler
|
|
+---tests - Harbour tests folder

13 / 23
 Harbour Beginners' Guide v1.2

10. Now you will 'configure' Harbour. It is enough to just open the command prompt and define the PATH
environment variable to include Harbour's 'bin' folder. Then to test if everything is OK we will move to the
'tests' folder and execute this command: 'hbmk2 hello' (or 'hello.prg' ). 'hbmk2' stands for 'Harbour Make
(version 2)' and it is a very complete utility to build Harbour applications and to help the developer to find
functions on the libraries (you will know more about it later). Now that HBMK2 did the whole job for us and
built the .EXE then let's execute it. Just type hello and press <ENTER>. You should see 'Hello, world!' -
That's a typical program test. You can see the whole process on [Fig.10]:

Fig.10 - Configuring the environment for Harbour and building the first test program 'Hello, world!'

14 / 23
 Harbour Beginners' Guide v1.2

11. HBMK2 is a nice utility. It was created by one of the developers 'Viktor Szakáts' and has plenty of
features. To know the basics how to use it just type 'hbmk2' and read the information it will give you. To
have a complete list of features you have to type 'hbmk2 -help' [Fig.11]. Since the list is pretty long it is
recommended to direct the output to a text file and open with a text viewer/editor (f.e. NotePad). To do so
just type 'hbmk2 -help >Help.txt' then just open the generated 'Help.txt' with any text file reader (f.e:
NotePad, WordPad, etc...) or you can also read the on line help file directly from GitHub.

Fig.11 - Hbmk2 basic syntax and options

15 / 23
 Harbour Beginners' Guide v1.2

12. Let's create two .PRG and build them to have an example with more than one built with hbmk2. Follow
it on [Fig.12]:

Fig.12 - Creating two .PRG using the command 'copy con...' (to save press Ctrl+Z)

16 / 23
 Harbour Beginners' Guide v1.2

13. Let's list the programs we just created typing 'dir my*' and to build (create the .EXE) just type: 'hbmk2
mytest mytest2' [Fig.13]:

Fig.13 - Build two or more .PRG with HBMK2

14. Execute the just created program typing: 'mytest' to test it and see if it works [Fig.14]:

Fig.14 - Testing the application built with HBMK2

17 / 23
 Harbour Beginners' Guide v1.2

15. Let's do the same but with the help of a 'Harbour Project' file (.HBP) that will have listed two or more
.PRG and eventual options to HBMK2. Create the file 'project.hbp' (can be any name) typing: 'copy con
project.hbp' (to save press Ctrl+Z). To build the .EXE you will type: 'hbmk2 project' (or 'project.hbp')
[Fig.15]. It will do basically the same as in the previous example.

Fig.15 - Creating and building a 'Harbour Project' file

18 / 23
 Harbour Beginners' Guide v1.2

16. HBMK2 is also useful to find functions on the libraries. For example let's do a research based on the
following string: 'disp'. So just type: 'hbmk2 -find disp'. All the functions that have that string on its name
will be shown with the library that they belong to [Fig.16]:

Fig.16 - Using hbmk2 to list all the functions that contain the string 'disp'

17. HBMK2 can create a full list of functions in Harbour. You can create a text file with that list typing:
'hbmk2 -find * >Manual.txt' [Fig.17a]. Please note that you will have to use 'WordPad' to open it [Fig.17b]:

Fig.17a - Creating a text file with a list of all the Harbour functions

19 / 23
 Harbour Beginners' Guide v1.2

Fig.17b - Opening the list of Harbour functions with 'WordPad'

Conclusion

20 / 23
 Harbour Beginners' Guide v1.2

Conclusion

Bring fun back to programming xBase!

It is time to do your own tests.

Try to build your old program with Harbour and see what happens but before you start some details should
be taken in consideration.

Before building an old code (f.e: made for Clipper®). Do these 3 basic changes:

1. Make sure that the starting PROCEDURE or FUNCTION is called 'Main()'. Harbour always
needs it as the starting point of the program.

2. Configure the size of the screen with SETMODE( 25,80 ). Since you are building 32 bit
applications and the command line is not as it was in the old days of DOS then you need
to inform the size of your screen to the system. You can play with that and try other
sizes (f.e: 50x80, 25x132, etc...)

3. Replace any functions from external libraries that are not include in Harbour by Harbour
(Note)
equivalents (it has many extended functions) or by rewriting the code

(Note)
It is common to try to build and get some 'Error: Unresolved external' messages. It happens basically because
Harbour did not find the functions your code is referring to.
The main reasons are libraries that are not being linked to the code (HBMK2 usually lists what libraries are missing)
or special functions that Harbour doesn't know or that belong to external libraries that don't exist in Harbour. To solve
the last one you may create dummy functions that return acceptable values just to make the building process to work
and as you go you have to replace those dummy by real ones (alternatives found in Harbour extensions or just
rewriting what is missing).

OK, now you should be able to do more tests. You will be amazed to see your old programs working again
as a real 32 bit application that runs even in 64 bit systems!

You have a problem and you can't find the answer? First search on the Harbour Users' list archive because
it may be something others asked before.
If you still have questions just drop a message on the list and be ready to help others whenever you can.
Be connected!

21 / 23
 Harbour Beginners' Guide v1.2

You can find more information on these websites although these are just a few of many other sources of
information:

o Harbour on Wikipedia: http://en.wikipedia.org/wiki/Harbour_(software)

o Harbour official reference guide: http://harbour.github.io/doc/ Harbour Reference Guide
o Alexander Kresin's - Harbour for beginners: http://www.kresin.ru/en/hrbfaq.html
o José Quintas' - Harbour doc: http://www.harbourdoc.com.br/
o Giovanni Di Maria's - Harbour docs: http://www.elektrosoft.it/tutorials.asp
o CA-Clipper® 5.3 guides: http://x-hacker.org/ng/53guide/
o xHarbour official reference guide: http://www.xharbour.com/xhdn/
o Marinas GUI - Harbour manual: http://www.marinas-gui.org/projects/harbour_manual/
o Fivetech Sofware. - Harbour docs: http://www.fivetechsoft.com/harbour-docs/harbour.html
o Gamero's - Harbour docs: https://github.com/zgamero/sandbox/wiki
o Harbour docs: http://vivaclipper.wordpress.com/
o Maximo's Harbour docs: http://harbourlanguage.blogspot.fr/
o Harbour docs: http://cch4clipper.blogspot.fr/
o Harbour docs (PDF): http://code.google.com/p/fivewin-
contributions/downloads/detail?name=harbour.pdf
o Example of GUI using Harbour MiniGUI: http://clipper64bits.blogspot.fr/p/minigui_21.html
o Harbour MiniGUI Extended: http://www.hmgextended.com/
o MigSoft Harbour docs: http://mig2soft.com/
o Harbour MiniGUI: http://www.hmgforum.com/
o Harbour QT Contribs: https://groups.google.com/forum/#!forum/qtcontribs

And do not forget to inscribe yourself on the Harbour Users’ list to exchange information, ask questions,
learn coding technics and know more about Harbour.

It is also recommended to inscribe on the Harbour Developers’ list to know about updates, improvements
and bug-fixes. Attention this list is reserved to the developers and to subjects related to the Harbour
language development so do not post there your doubts about the use of Harbour – use the Harbour-users
list instead.

There is also the commercial "xHarbour's Language Reference Guide" that you can buy for a very small
(Note)
price and I personally highly recommend you to just get one .

The 'Reference Guide' doesn't include some Harbour extensions but it is the best documentation you may
find today. It was specifically made for xHarbour® (paid commercial extension of Harbour) but will cover
most of the Harbour and for sure it will be more than enough for anyone migrating from other xBase
languages to Harbour. It comes in practical .CHM and .PDF formats [Fig.18].

(Note)
The Harbour Project, its developers and the autor of this guide do not have any affiliation with the commercial
xHarbour® or with the sells of the 'xHarbour's Language Reference Guide' and the recommendation is done in sole
good faith that it will be really helpful to programmers coming to Harbour.

22 / 23
 Harbour Beginners' Guide v1.2

Fig.18 - xHarbour's Language Reference Guide in practical .CHM format

Notice
The guide can be copied and distributed freely.
Any questions about this guide, sugestions, corrections, etc... can be directed to the author by email

Have fun and good Harbouring!

23 / 23