The Xbase++ ProjectBuilder

The Xbase++ ProjectBuilder - PBUILD.EXE
The Xbase++ ProjectBuilder - PBUILD.EXE
The Xbase++ ProjectBuilder è uno strumento per gestire progetti software completi. Un progetto
consiste in almeno un file EXE ma può anche comprendere svariati file EXE e/o DLL. La
descrizione di un progetto è contenuta in un file project. Questo è un file ASCII con estensione
XPJ(Xbase++ ProJect). Elenca tutti i dati necessari per creare un progetto. Per esempio, nome del
file sorgente,informazioni per il compilatore e il linker o quale file eseguibile deve essere creato
dal file sorgente.
Creazione di un file project (XPJ file)
Il modo più semplice per creare un file project è usare un file ASCII con la lista dei nomi di tutti i
sorgenti PRG che fanno parte del progetto. Così può essere creato il file con il comando DIR :
DIR /b *.prg > project.txt
PBUILD @project.txt
L' output del comando DIR è diretto nel file PROJECT.TXT. Questo file può essere facilmente
modificato usando un semplice editor di testi per rimuovere i nomi dei file PRG che si trovano
nella directory corrente ma che non fanno parte del progetto,ad esempio. Il ProjectBuilder
(PBUILD.EXE) legge così un file e crea da questo un template per un file project con
l'estensione XPJ (questo per Xbase++ ProJect).
Per piccoli progetti, la struttura base di un file project può anche essere creata velocemente con
un editor. Il seguente esempio mostra un file project per il programma CUSTOMER.EXE che
richiede solo quattro file PRG :
01:
02:
03:
04:
05:
06:
07:
08:
09:
10:
11:
[PROJECT]
DEBUG = yes
GUI
= no
CUSTOMER.XPJ
12:
11:
PRINT.PRG
VIEWCUST.PRG
// Definizioni project-wide
// La radice del progetto
[CUSTOMER.XPJ]
CUSTOMER.EXE
// Lista di tutti i file EXE e DLL
// del progetto
[CUSTOMER.EXE]
CUSTOMER.PRG
GETCUST.PRG
// Lista di tutti i sorgenti degli
// EXE e/o DLL separatamente
L'esempio mostra le principali caratteristiche di un file XPJ : è diviso in diverse parti, ognuna
delle quali cominciano con un nome simbolico racchiuso in parentesi quadre. La prima sezione
deve essere sempre chiamata [PROJECT]. Questo è il punto di partenza per il ProjectBuilder ed
elenca definizioni valide per l'intero progetto. In questo esempio, un programma contenente
Creazione di un file project (XPJ file)
informazioni di debug è stato creato come applicazione in modalità testo (lines 2 and 3). Alla fine
della lista di definizioni (line 4), appare il nome della sezione successiva che è stata analizzata
dal ProjectBuilder. Questa sezione è la radice del progetto ed elenca tutti i file eseguibili che
fanno parte del progetto, o rispettivamente, che devono essere inseriti dopo dal cliente. Questo
include sia i file EXE che i file DLL. Ogni nome di file eseguibile è usato di nuovo come il
nome di un'altra sezione che elenca i nomi dei file sorgente da cui sono creati i file eseguibili.
Come risultato, la struttura di un file XPJ rappresenta le dipendenze che esistono tra file sorgente
e file target di un progetto. Per esempio, il file prima menzionato CUSTOMER.EXE è il file
target che dipende da quattro file PRG , o sorgenti, rispettivamente. Ogni volta che cambia un
sorgente, il target deve essere aggiornato. Il ProjectBuilder analizza le dipendenze tra sorgente e
target usando un file project e aggiornando l'intero progetto per apportare le ultime modifiche.
L'esempio sopra mostra solo la struttura base di un file XPJ come può essere facilmente creato
con un editor. Comunque, la maggior parte delle dipendenze possono esistere tra differenti file
dello steso progetto.Queste includono, per esempio,dipendenze tra CH->PRG, PRG->OBJ, OBJ>EXE o OBJ->DLL e DEF->LIB. Il ProjectBuilder è capace di trovare tutte queste numerose
dipendenze automaticamente non appena la struttura base del file project è cretata. Per questo il
file PBUILD.EXE comincia con lo switch /g (g sta per generate):
PBUILD customer.xpj /g
Lo switch /g fa sì che il PBUILD.EXE analizzi tutte le dipendenze che esistono all'interno del
progetto. Il ProjectBuilder allora espande un file project (elementare) e aggiunge tutte le
informazioni omesse al file XPJ. Questo libera del tutto il programmatore da tante battute,
specialmente per i grandi progetti. Ad esempio, PBUILD.EXE espande l'esempio precedente di
file XPJ di 20 linee. Come risultato il file project cresce da 11 a 31 linee:
01:
02:
03:
04:
05:
06:
07:
08:
09:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
21:
[PROJECT]
COMPILE
COMPILE_FLAGS
DEBUG
GUI
LINKER
LINK_FLAGS
RC_COMPILE
RC_FLAGS
CUSTOMER.XPJ
=
=
=
=
=
=
=
=
xpp
/q
yes
no
alink
// Informazioni compiler e linker
// precedente omesse
arc
[CUSTOMER.XPJ]
CUSTOMER.EXE
[CUSTOMER.EXE]
// $START-AUTODEPEND
COLLAT.CH
GET.CH
MEMVAR.CH
PROMPT.CH
SET.CH
// Dipendenze create
// automaticamente
Creazione di un file project (XPJ file)
22:
23:
24:
25:
26:
27:
28:
29:
30:
31:
STD.CH
CUSTOMER.OBJ
GETCUST.OBJ
PRINT.OBJ
VIEWCUST.OBJ
// $STOP-AUTODEPEND
CUSTOMER.PRG
GETCUST.PRG
PRINT.PRG
VIEWCUST.PRG
Le modifiche compaiono nella sezione [PROJECT] , dove tutte le informazioni omesse per il
compilatore e linking sono aggiunte. Inoltre, la sezione [CUSTOMER.EXE] ora contiene una
lista di file di cui il ProjectBuilder ha trovato dipendenze. Questo automaticamente crea la lista
racchiusa dai marcatori. // $START-AUTODEPEND e // $STOP-AUTODEPEND nella riga 16 e
27. Entrambi i marcatori indicano un'area nel file project che potrebbe essere modificata
automaticamente quando il PBUILD.EXE è chiamato successivamente insieme con lo switch /g.
Perciò, un file project non deve essere modificato tra questi marcatori o le modifiche in quest'area
potrebbero essere perse.
Creazione di un progetto
Quando un file project che include tutte le dipendenze è generato, il progetto è creato, o
aggiornato, rispettivamente,dall'attivazione PBUILD.EXE e specificando l'appropriato file
project, se necessario . Di default,il ProjectBuilder cerca il file PROJECT.XPJ nella directory
corrente. Dunque, ognuna delle seguenti possibilità crea un progetto:
1)
PBUILD
2)
PBUILD customer
3)
PBUILD customer.prj
In primo luogo, il ProjectBuilder crea il progetto che è descritto nel file PROJECT.XPJ. Dopo
richiede che il file CUSTOMER.XPJ sia disponibile nella directory corrente (XPJ è l'estensione
di default per il file project) , finchè alla terza chiamata, un nome di file completo indica il file
project. Dopo l'attivazione, il ProjectBuilder analizza le dipendenze tra i file sorgente e target. Se
un file sorgente è stato cambiato dall'ultima chiamata al PBUILD.EXE, per esempio se il file
sorgente è più nuovo del file target, il ProjectBuilder crea nuovamente la corrispondenza con i
targets (EXE o DLL). Solo dopo le modifiche dei sorgenti sono elaborati dal ProjectBuilder, il
tempo per aggiornare complessi progetti è quindi ridotto in larga misura.
Laa sezione [PROJECT] in un file XPJ
La sezione [PROJECT] in un file XPJ
Tutte le informazioni che possono essere elencate nella sezione [PROJECT] sono descritte sotto.
Ogni file project deve cominciare con la sezione [PROJECT] che contiene le definizioni valide
per l'intero progetto (project-wide definitions):
COFF_LINKER=
Questa definizione opzionale può essere usata per definire il linker da
attivare dal ProjectBuilder quando l'OBJ_FORMAT= è settato su COFF
(Common Object File Format). Se COFF_LINKER= non è definito in
questo caso, il ProjectBuilder usa il linker definito con LINKER=.
COMPILE=
Indica il nome del compilatore Xbase++. Esso è sempre XPP.
COMPILE_FLAGS= Tutti gli switch del compilatore da settare sono definiti quì. Nota che
esistono diverse definizioni OBJ_DIR= e DEBUG= per gli switch /o e
/b.
DEBUG=
Questa definizione può essere settata su YES (debug version) o su NO
(non debug version). File eseguibili sono creati di conseguenza con o
senza informazioni di debug. Un file eseguibile deve essere creato con
DEBUG=YES in modo che possa essere monitorizzato con il debugger.
GUI=
Se un programma deve girare in modalità testo, deve essere settato
GUI=NO . Ogni volta che un programma realizza un output grafico,
che sia con Gra..() functions o con l'uso di Xbase Parts, deve essere
definito GUI=YES.
LINKER=
Questa definizione indica il nome del linker usato per creare file EXE o
DLL da file OBJ. Sarebbe il linker che incluso con la versione specifica
per sistema operativo di Xbase++.
LINK_FLAGS=
Tutti i flag del linker che non sono inclusi in GUI= e DEBUG= sono
elencati in questa definizione. Comunque, se il flag /PM e /DE sono
usati anche quì, ignorano le corrispondenti definizioni di GUI= e
DEBUG=.
OBJ_DIR=
Facoltativamente, la directory per i file OBJ può essere definita. Il
compilatore crea i file OBJ in questa directory, ed il linker la cerca per
trovare questi file. Solo una directory può essere settata.
Note: Il settaggio OBJ_DIR incide solo sui file OBJ elencati nella nella
sezione del file project delimitata con // $START-AUTODEPEND //
$STOP-AUTODEPEND. PBuild completa il nome di questi file OBJ
con la directory OBJ_DIR affinchè non siano specificate informazioni
sul path per i file elencati nella sezione auto-dependency. In aggiunta i
file OBJ possono essere specificati con path completo fuori dalla
sezione auto-dependency.
Laa sezione [PROJECT] in un file XPJ
OBJ_FORMAT=
Due valori possono essere usati per questa definizione per scegliere il
formato dei file object: COFF (Common Object File Format) o OMF
(Object Module Format). Il ProjectBuilder fa partire il Compiler ed
aziona il AIMPLIB.EXE, se necessario, usando gli switch
corrispondenti /coff o /omf. Inoltre, il linker definito con
COFF_LINKER= o OMF_LINKER= è usato nel build process.
OMF_LINKER=
Questa definizione opzionale può essere usata per definire il linker da
azionare dal ProjectBuilder quando OBJ_FORMAT= è settato su OMF
(Object Module Format). Se OMF_LINKER= non è definito in questo
caso, il ProjectBuilder il linker definito con LINKER=.
RC_COMPILE=
Questa definizione contiene il nome del compilatore di risorse venduto
con Xbase++. Normalmente, le risorse addizionali sono usate solo per
applicazioni GUI.
OS/2
Queste sono note addizionali alla fine di questa sezione per le
piattaforme OS/2.
RC_FLAGS=
Il flag per il compilatore di risorse è settato con questa definizione.
<SECTION>
Tutte le entries nella sezione [PROJECT] definite senza segno di
uguaglianza sono usate come riferimento alla successiva sezione userdefined che viene analizzata dal ProjectBuilder. Normalmente, solo una
sezione addizionale (the root section) è referenziata. A questo punto
deve esserci almeno una sezione user-defined.
Note: Le definizioni elencate nella sezione [PROJECT] sono valide per l'intero progetto.
Comunque, possono anche apparire nella sezione user-defined. In questo caso, sono valide solo
per una sezione. Se le definizioni sono trasferite al PBUILD.EXE dalla riga di comando usando
lo switch /d switch, tutte le definizioni nel file project con lo stesso nome saranno ignorate.
Compilatore di risorse per OS/2
Le dipendenze di risorse wether sono dichiarate nei file ARC o RC, le opzioni RC_COMPILE=
deve essere settata su arc o rc. Se è usato il file ARC, il Project Builder attiva prima ARC.EXE
(Alaska resource compiler) e dopo RC.EXE (OS/2 resource compiler). ARC.EXE traduce i file
ARC in file RC che possono essere compilati da RC.EXE.
Sezione User-defined nel file XPJ
Dopo la sezione [PROJECT],la sezione user-defined è elencata nel file project. Il nome della
prima sezione user-defined (la root section) deve essere indicata nella sezione [PROJECT], come
mostra il seguente esempio:
[PROJECT]
DEBUG = YES
ROOT
// project-wide definition
// prima sezione user-defined
Sezione User-defined nel file XPJ
[ROOT]
file1.EXE
file2.DLL
[file1.EXE]
<PRG files for the EXE file>
[file2.DLL]
DEBUG = NO
// section-wide definition
<PRG files for the DLL file>
La prima sezione user-defined elenca tutti i file eseguibili (targets) creati dal ProjectBuilder. Per
ogni target,esiste una sezione user-defined che ha lo stesso nome. Elenca i file PRG (sorgenti)
per quel target. I sorgenti sono normalmente solo file PRG, ma possono anche essere file
resource se richiesti da un'applicazione GUI.I file di risorse sono compilati da un compilatore di
risorse e linkati per essere file eseguibili.
Quando un file target sta per essere creato come una libreria dinamica (DLL file), il nome di file
corrispondente deve includere l'estensione DLL. Il ProjectBuilder crea automaticamente tutti i
file necessari per la creazione della DLL. Questo include il file di espoortazione delle definizioni
(DEF file) e il file di importazione libreria (LIB file). L'ultimo deve essere linkato ad un EXE che
usa le funzioni contenute nella DLL.
Quando un file project contiene multiple sezioni user-defined, è sufficiente scrivere solo il file
sorgente per ogni sezione (file PRG e file di risorse, se necessario). Il file project può quindi
essere esteso alla descrizione di tutte le dipendenze tra sorgente e targets con l'attivazione di
PBUILD.EXE con lo switch /g.
Sezione User-defined nel file XPJ
Opzioni per PBUILD.EXE
Il ProjectBuilder viene lanciato dalla riga di comando digitando PBUILD. Se non è specificato un file project
file, il ProjectBuilder cerca il file PROJECT.XPJ e crea il progetto descritto in questo file. La descrizione
generale per la chiamata è:
PBUILD @<file>
or
PBUILD [<XPJ file>] [<options>]
@<file>
Il carattere @ indica un file che elenca tutti i sorgenti che fanno partedel progetto.
<file> è un file ASCII che contiene il nome di un file sorgente per ogni riga. Può essere
creato molto facilmente digitando DIR /b *.PRG > PROJECT.LST dalla riga di
comando,per esempio. Da questo file, il ProjectBuilder crea un file project con lo stesso
nome ma con una differente estensione (XPJ). Il nome <file> è aanche usato per i file
eseguibili da creare.
<XPJ file>
Quando un progetto non è descritto nel file PROJECT.XPJ, il nome del file project
deve essere specificato nella riga di comando. L'estensione di default è XPJ.
/? or /h
Visualizza le informazioni sulle opzioni del PBUILD.EXE. Lo switch /? fornisce solo
informazioni e non può essere combinato con altri switches.
/a
Lo switch /a costringe il ProjectBuilder ad eseguire una compilazione completa ed un
ciclo di link per ogni sorgente del progetto. Questo ricostruisce un intero progetto
nonostante non ci siano cambiamenti nel file sorgente dall'ultima modifica del progetto.
/c
Lo switch /c (clean) cancella tutti i file binari dell'intero progetto creato dal
ProjectBuilder (OBJ, EXE, EXP, DEF, LIB, DLL and RES files).
/d<id>[=<val>]
La definizione <id> in un file project può essere settata sul valore <val> usando lo
switch /d dalla riga di comando. Per esempio, digitando PBUILD /dDEBUG=NO si
costruisce un progetto senza informazioni di debug anche se DEBUG=YES è
specificato nella sezione [PROJECT]. Lo switch /d, quindi, cambia provvisoriamente le
definizioni senza cambiare il file project.
/g[<name>]
Specificando lo switch /g si induce il ProjectBuilder ad analizzare il progetto per
dipendenze. Quindi genera una lista di tutti i file da cui dipendono i target. Questa
opzione deve essere usata per espandere la
struttura base di un file project o quando sono cambiate le dipendenze. La struttura
fondamentale di un file XPJ copre solo i file PRG e target (EXE o DLL). Un completo
file XPJ , tuttavia, elenca file con estensione CH, OBJ, ARC, DEF e LIB (DEF e LIB
sono usati per la creazione di file DLL).
Opzionalmente, un nuovo file project può essere creato specificando <name>. Se il
nome del file viene omesso, un file project esistente viene sovrascritto.
/k
Nel corso del processo di build vengono creati dei file temporanei che vengono
cancellati automaticamente quando il ProjectBuilder ha finito. Usando l'opzione /k (for
keep) si impedisce al ProjectBuilder di cancellare i file temporanei.
/l
Quando un file DLL è parte di un progetto, il ProjectBuilder automaticamente crea il
corrispondente file DEF (Export definition files) e LIB (import libraries). Normalmente
questo non è necessario quando un file PRG è cambiato ma solo quando il numero,
serie o identificatore della funzione esportata cambia nella DLL.
Per esempio, se una funzione in un file PRG è modificato dall'inserimento di alcune
righe di codice, il file PRG deve essere compilato e la DLL deve essere linkata.
Comunque, le definizioni esportate e la libreria importata non richiedono di essere
Sezione User-defined nel file XPJ
ricostruite in questo caso. Quindi, lo switch /l sopprime automaticamente la creazione
dei file DEF e LIB.
/n
Con /n, il ProjectBuilder visualizza solo tutti i passi necessari per aaggiornare un
progetto senza far eseguire le azioni corrispondenti (compilatore e linker non sono
attivati).
/v
Lo switch /v attiva la modalità verbose del ProjectBuilder.