Breve introduzione all'utilizzo di Harbour    

Harbour è un linguaggio di programmazione open source che si ispira al Clipper, sviluppato dalla Nuntucket, negli anni '80,  come compilatore per il linguaggio di programmazione/interrogazione del database DBIII, per il quale era fornito solo un interprete.
Il compilatore Clipper riscosse un notevole successo sino alla metà degli anni '90 quando la Computer Associates, che nel frattempo aveva acquisito il prodotto, decise di porre fine al suo sviluppo poiché non ritenne opportuno investire per sviluppare una nuova versione di prodotto compatibile con Windows-95.

Tale decisione avrebbe potuto decretare la morte di Clipper ma le cose sono andate diversamente perché alcuni programmatori decisero di continuare a supportare il linguaggio sviluppando dei compilatori alternativi. Fra le soluzioni proposte una delle più interessanti è certamente Harbour, un software open source, distribuito sotto una licenza GPL modificata che consente lo sviluppo di applicazioni proprietarie (http://www.harbour-project.org/license.html).

L'unico neo di questo ottimo progetto è la documentazione. Molti potenziali utenti  si trattengono dall'intraprendere lo sviluppo di progetti con Harbour a causa  della difficoltà  di reperire le informazioni necessarie per cominciare ad usarlo. In realtà vari siti forniscono una ricca documentazione circa i possibili usi "avanzati" (come la programmazione ad oggetti o l'interfacciamento delle librerie grafiche) ma apparentemente manca una guida per chi sta muovendo i primi passi. 
Spero che queste mie poche note contribuiranno a risolvere il problema.

Installazione

Nota: questo documento presenta la procedura di installazione degli eseguibili sotto Windows. I lettori interessati ad installare Harbour sotto altri sistemi operativi (Linux, MS-DOS, OS2) sono rimandati al fondo del documento dov'è illustrata la procedura di installazione di Harbour a partire dai sorgenti.

Volendo provare Harbour bisogna innanzitutto procurarsi il pacchetto di installazione che può essere scaricato gratuitamente dal sito: http://www.harbour-project.org/. In questo tutorial faremo riferimento alla versione per Windows (pacchetto harbour-3.0.0-win.exe).

Scaricato il pacchetto per avviare l'installazione basterà cliccare su di esso. Si aprirà la finestra del Wizard. Cliccate su "Next" per andare avanti. La schermata successiva vi chiederà di confermare l'accettazione dei termini della licenza. Premete "Next". Quindi apparirà una terza finestrella che vi consentirà di scegliere i componenti che desiderate installare. Vi suggerisco di installare anche  l'IDE (occorre selezionarlo, vedi figura). 

La schermata successiva consente di scegliere la directory in cui saranno installati i file., solitamente C:\hb30. Proseguite premendo Next".

La procedura di installazione proseguirà quindi con la creazione della directory selezionata e la copia dei file.

Il processo termina con l'introduzione di una nuova voce nel menu START e con l'aggiunta di una icona di collegamento alla directory di istallazione sul desktop.

Completamento dell'installazione
Per poter effettivamente utilizzare gli strumenti installati bisogna completare l'installazione configurando le variabili d'ambiente (environment variables) così come si faceva con Clipper.
Se si lavora da riga di comandi si potrà riciclare il vecchio batch file di Clipper sostituendo semplicemente il nome della directory:


In caso contrario, se si intende utilizzare l'IDE, bisognerà configurare le variabili seguendo la procedura suggerita da Windows che cambia in funzione della versione di sistema operativo utilizzata.

Utilizzando Windows-2000 o Windows-XP basta editare il file AUTOEXEC.BAT utilizzando l'editor di configurazione di sistema.
Cliccate su START e quindi su "Esegui" .
Nella casella "Apri" scrivete: SISEDIT e confermate premendo "OK".
Aggiungete le seguenti linee.


NB: nel caso in cui le variabili d'ambiente INCLUDE, LIB, OBJ fossero già presenti dovete aggiungere solo il riferimento alla directory C:\HB30 preceduto da punto e virgola al fondo della riga preesistente altrimenti qualche altro compilatore già installato potrebbe smettere di funzionare.
Ad esempio se il file AUTOEXEC.BAT contiene già la stringa:


dovete rimpiazzarla con


e così via.

Se invece usate Windows-7 per modificare le variabili d'ambiente dovrete seguire una procedura più laboriosa.
Cliccate su START.
Aprite il "Pannello di Controllo".
Selezionate "Sistema e sicurezza".
Cliccate su "Sistema".
Selezionate le "Impostazioni del sistema avanzate".
Cliccando su "Variabili d'ambiente" si aprirà una finestra di dialogo che vi consentirà di modificare una alla volta le variabili d'ambiente: INCLUDE, LIB, OBJ e PATH.

Uno sguardo al contenuto della directory c:\hb30

Al termine dell'installazione la directory c:\hb30 conterrà nove subdirectory, il programma di disinstallazione e una mezza dozzina di file di testo contenenti spiegazioni varie. Si consiglia in particolar modo di leggere il contenuto dei file COPYING e INSTALL; il primo riporta il testo della licenza sotto la quale Harbour viene rilasciato, mentre il secondo fornisce indicazioni circa la procedura di installazione e l'utilizzo del compilatore.

Passando ad esaminare le subdirectory troviamo:

addons

bin           contiene i file eseguibili di Harbour.

comp       directory in cui è installato il compilatore C “mingw”

contrib     contiene contributi di vari sviluppatori che utilizzano Harbour.

doc          documenti.

examples file di esempio.

include     file da includere per utilizzare le funzioni contenute nelle librerie.

lib            librerie.

test          routine de test di regressione.

Prima di cominciare ad utilizzare Harbour sarebbe altamente auspicabile leggere a documentazione contenuta nella directory c:\hb30\doc. In particolare può essere utile esaminare il file “dirstruct.txt” che descrive l'organizzazione della directory di installazione di Harbour (facendo purtroppo riferimento all'installazione sotto Linux che è molto più articolata). Si consiglia inoltre di esaminare il file “clipper.txt” che illustra alcune nuove funzionalità introdotte in Harbour che non erano presenti nel linguaggio originale. I file “cmdline.txt” e “cmdopt.txt”trattano delle opzioni di compilazione, “class.txt” e “destruct.txt” della programmazione ad oggetti, eccetera. Gli argomenti su cui focalizzare la vostra attenzione dipendono dai vostri interessi e dalla vostra precedente esperienza come programmatori in linguaggio Clipper.

Curiosamente i file che illustrano la licenza sotto la quale sono rilasciate le librerie grafiche Qt non sono contenuti nella directory c:\hb30\doc bensì nella directory c:\hb30\bin. Prima di intraprendere lo sviluppo di un nuovo progetto che prevede l'impiego di un'interfaccia grafica si suggerisce di prendere visione dei suddetti file perché le condizioni di rilascio delle Qt sono diverse da quelle di Harbour.

La directory c:\hb30\bin contiene tutti gli eseguibili (esclusi quelli riconducibili al compilatore C che si trovano in c:\hb30\comp) compreso l'ambiente di sviluppo grafico “hbide.exe”.

Il primo programma

Per quanto concerne la prassi di utilizzo, Harbour consente di scegliere fra due modalità di lavoro: si può compilare da riga di comando come si faceva con Clipper oppure si può optare per un ambiente di sviluppo a finestre (HBIDE), lavorando a progetti.

Qualunque sia la nostra scelta, prima di procedere conviene creare una directory di lavoro per le prove (c:\hb30\prove) e un semplice programma “HELLO.PRG”:

PROCEDURE Main()

? "Hello World!"

RETURN

Scritte le tre righe di codice precedenti e salvato il file possiamo provarlo immediatamente da linea di comando digitando:

                        hbrun hello.prg <INVIO>

in alternativa possiamo compilare il file utilizzando il comando:

                        hbmk2 hello.prg <INVIO>

e poi eseguire il programma digitando:

                        hello <INVIO>

Volendo utilizzare HBIDE bisognerà innanzitutto accedere alla directory c:\hb30\bin.

Cliccate quindi sulla voce corrispondente al file hbide.exe per aprire la finestra corrispondente ed eseguirlo.

Cliccate quindi su File, quindi su New, ed infine su Project; si aprirà la finestra di Explorer.

Posizionatevi sulla directory c:\hb30 dove creerete la directory “prova2” (o più precisamente c:\hb30\prova2), che sceglierete cliccando su “choose”.

Creerete quindi il programma da compilare cliccando su File, quindi New ed infine su Source (dovrebbe essere selezionata la directory creata in precedenza c:\hb30\prova2).

Create il file hello2.prg che verrà immediatamente aperto nell'area centrale della finestra di HBIDE.

Copiate o scrive all'interno il testo dell'esempio precedente, aggiungendo la scritta “Ciao!”:

PROCEDURE Main()

? "Hello World!"

? "Ciao!"

RETURN

Passate poi a considerare il progetto (file “hello.hbp” aperto sotto forma di form nella porzione destra della finestra.

Riempile le voci corrispondenti al nome del progetto (Project Title) e quella associata al nome del file eseguibile (“Output Name”) indicando un nome che vi piace, ad esempio “hello2”.

Cliccate poi sulla linguetta “HBP” e quindi sull'icona gialla ritraente una cartella.

Quando si aprirà la finestra della selezione dei sorgenti (“Select Sources”) selezionate il file “hello2.prg” creato poc'anzi.

Confermate cliccando su “Save”

Fatto ciò è possibile compilare i file sorgenti che costituiscono il progetto cliccando sull'icona arancione ritraente un muro. In alterativa aprite il menu “Build” e cliccate su “Build Project” che genererà il programma eseguibile.

A questo punto si potrebbe lanciare il programma generato(ad esempio usando il comando “Build and Lunch”) senonché si tratta di un programma fatto per girare in modalità console visualizzando subito i risultati, per cui quando lo si fa partire si apre una finestra, il programma viene eseguito in una frazione di secondo quindi la finestra viene subito richiusa, per cui non si riesce a vedere niente

Per vedere se l'eseguibile lavora correttamente occorre lanciarlo da una finestra di DOS.

Se usate Windows-XP, cliccate su START, tutti i programmi, Accessori, Prompt dei comandi.

Quando si aprirà la finestra nera di DOS digitate

CD C:\HB30\PROVA2 <INVIO>

e quindi

hello2 <INVIO>

Otterrete il risultato mostrato nella figura sottostante.

Nel caso in cui invece voleste cimentarvi con un hello world grafico vi rimando agli ottimi tutorial del Gruppo Eratostene (www.gruppoeratostene.com/harbour/harbour-tutorials.htm).

A beneficio dei più impazienti: create un nuovo file di progetto “hello4.hbg” e copiate all'interno il seguente codice:

#
# $Id$
#

-3rd=hbide_version=1.0
-3rd=hbide_title=HELLO4
-3rd=hbide_output=HELLO4

hbqt.hbc
-w3 -es2
hello4.prg

Quindi create il file “hello4.prg” contenente il seguente codice (derivato dal primo esempio del tutorial di Giovanni Di Maria)::

#include "hbqtgui.ch"

PROCEDURE Main ()
LOCAL oWnd
oWnd := QMainWindow ()
oWnd : setWindowTitle ( " Hello World!" )
oWnd : resize ( 300 , 200 )
oWnd : show ()
QApplication (): exec ()
RETURN
// END SOURCE

Salvate tutto.

Aprite quindi il file “hello4.hbp” come progetto in HBIDE e rigenerate il progetto utilizzando l'opzione “Build and Launch” (icona del muro con la freccia blu). Al termine della build verrà eseguito automaticamente il codice generato che aprirà una finestra di Windows avente per titolo “Hello World!”.

INSTALLAZIONE DI HARBOUR DAI SORGENTI

La procedura di installazione a partire dai sorgenti si utilizza tipicamente in tre casi:

1. se non sono disponibili degli eseguibili compilati specificatamente per il nostro sistema operativo (potrebbe essere il caso degli utenti Linux che utilizzano distribuzioni non supportate ufficialmente dal team di sviluppatori di Harbour);
2. quando si desidera disporre dell'ultimissima versione del compilatore (ad esempio perché contiene la correzione di un errore che era stato segnalato);
3. se si vogliono studiare i sorgenti per capire meglio come funziona il compilatore o si desidera contribuire allo sviluppo di Harbour.
   

L'installazione a partire dai sorgenti ha due prerequisiti: (1) dovete disporre di un compilatore C installato correttamente e (2) vi occorrono i sorgenti.

(1) Circa il primo punto se usate Linux non dovrebbero esserci problemi poiché quasi tutte le distribuzioni forniscono il compilatore GNU preinstallato proprio per in casi come questo. Se invece usate Windows avete solo l'imbarazzo della scelta; io ad esempio ho utilizzato OpenWatcom 1.9, un compilatore open source scaricabile gratuitamente da softpedia.
Negli altri casi prima di procedere alla ricompilazione dei sorgenti di Harbour dovrete assicurarvi che sulla vostra macchina sia installato un compilatore C e che le corrispondenti variabili d'ambiente siano settate correttamente.

(2) Per reperire i sorgenti nel sito ufficiale di Harbour posizionate il mouse su downloads, selezionate Binaries & Source e quindi oppure cliccate sulla voce source della lista (oppure cliccate sul seguente link http://sourceforge.net/projects/harbour-project/files/source/).
Vi sarà offerta la possibilità di scegliere la versione del programma che desiderate scaricare. In genere si tratterà di scegliere fra l'ultima release stabile (3.0.0) o la versione con le ultime modifiche apportate dagli sviluppatori (nigtly).

Nota per i meno smaliziati:
I sorgenti chiaramente sono indipendenti dal sistema operativo nel senso che contengono tutte le informazioni necessarie per rigenerare gli eseguibili a condizione di disporre di un compilatore C correttamente installato.

Supponendo di aver deciso di scaricare l'ultima versione stabile (harbour-3.0.0.tar.gz), ottenuti i sorgenti dovrete espandere il pacchetto compresso; sotto Linux non c'è problema, mentre gli utenti di Windows potrebbero essere costretti a procurarsi un programma di decompressione come 7Zip.
Espanso il pacchetto, entrate nella directory harbour-3.0.0, troverete i file con tutto l'occorrente per generare gli eseguibili che vi occorrono.
A questo punto non vi resta che digitare il comando di compilazione che dipende dal sistema operativo considerato:

Windows
Gli utenti di Windows hanno la possibilità di scegliere fra due opzioni: generare un eseguibile a 32 piuttosto che a 64bit. Per generare un eseguibile Win-32 cliccate su win-make, se invece preferite un eseguibile Win-64 eseguite w64-make.
Indipendentemente dall'opzione prescelta la procedura dovrebbe procedere automaticamente facendo tutto ciò che occorre.

MS-DOS
Per generare gli eseguibili per MS-DOS eseguite dos-make.

OS2
Gli utenti di OS2 dovranno invece lanciare os2-make.

LINUX
Volendo installare Harbour sotto Linux compilando i sorgenti bisognerà aprire un terminale (shell),  posizionarsi nella directory in cui sono stati copiati i file di installazione (ad esempio ~/harbour-3-0-0) e impartire il comando make install.
Nel caso in cui la procedura di installazione non andasse a buon fine provate a ripeterla usando i privilegi di superuser.
Al termine dell'installazione per verificarne la correttezza potete provare a compilare il programma hello.prg che trovate nella directory ~/harbour-3-0-0/tests.
Digitate:

      $ cd tests
      $ hbmk2 hello.prg
      $ ./hello

Dovrebbe apparire la scritta 'Hello world!' sullo schermo; in caso contrario (assumendo che harbour sia stato compilato usando gcc) rimanendo nella directory tests provate a digitare:

      $ ../bin/linux/gcc/hbmk2 hello.prg
      $ ./hello    

Se compare la scritta 'Hello world!' significa che la compilazione è stata effettuata correttamente ma non sono state configurate le variabili d'ambiente nel qual caso dovrete provvedere di persona.



BIBLIOGRAFIA

Giovanni Di Maria, Harbour HowTo Tutorial,

Giovanni Di Maria, HBQT-Tutorial.

NB: se utilizzate i due tutorial di cui sopra (sono fatti bene per cui a mio avviso ne vale la pena), fate attenzione ad usare le funzioni di copia e incolla di Windows perché inseriscono degli spazi in posti imprevisti. Compilando i programmi di esempio si rischia che questi non funzionino, non perché sono sbagliati ma perché la funzione di copia e incolla ha aggiunto degli spazi che non avrebbero dovuto esserci.