Creating a project file (XPJ file) Foundation

The easiest way to create a project file is by using an ASCII file which lists the names of all PRG sources which are part of a project. Such a file can be created with the DIR command:

DIR /b *.prg > project.txt 

PBUILD @project.txt 

The output of the command DIR is directed into the file project.txt. This file can easily be modified using a simple text editor to remove names of PRG files which are located in the current directory but are not part of the project, for example. The ProjectBuilder (pbuild.exe) reads such a file and creates from it a template for a project file with the extension .xpj (this stands for Xbase++ ProJect).

For small projects, the basic structure of a project file can also be created quickly with an editor. The following example shows a project file for the program customer.exe which needs only four PRG files:

01:  [PROJECT] 
02:     DEBUG                 = yes       // Project-wide definitions 
03:     TARGET_DIR            = .\run 
04:     project.xpj                       // The root of the project 
05:               
06:  [project.xpj]                        // List all EXE and DLL 
07:     customer.exe                      // files of the project here 
08: 
09:  [customer.exe]                    
10:     INTERMEDIATE_DEBUG    = .debug 
11:     INTERMEDIATE_RELEASE  = .release 
12:     GUI                   = no 
13:     customer.prg                      // List all sources for each 
14:     getcust.prg                       // EXE and/or DLL file separately 
15:     print.prg 
16:     viewcust.prg 

The example shows the major characteristic of an XPJ file: it is divided into different sections, each of which begins with a symbolic name enclosed in square brackets. The first section must always be named [PROJECT]. It is the entry point for the ProjectBuilder and lists definitions valid for the entire project. In this example, a program containing debug information is to be created (line 2). At the end of the definitions list (line 4), the name of the next section which is to be analyzed by the ProjectBuilder appears. This section is the root of the project and is typically named project.xpj. Only one such section can exist in an XPJ file. The section lists all executable files which are part of the project, or which must be distributed later to customers, respectively. This includes both EXE and DLL files. Each name of an executable file is used again as the name for another section which lists the names of the source files the executable file is created from.

As a result, the structure of an XPJ file represents the dependencies which exist between source and target files of a project. For example, the beforementioned file customer.exe is a target file which depends on four PRG files, or sources, respectively. Whenever a source is changed, the target must be updated. The ProjectBuilder analyzes the dependencies between source and target using a project file and updates an entire project to reflect the latest changes.

The example above shows only the basic structure of an XPJ file as it can be easily created with an editor. However, many more dependencies can exist between different files of the same project. These include, for example, dependencies between CH->PRG, PRG->OBJ, OBJ->EXE or OBJ->DLL and DEF->LIB files. The ProjectBuilder is able to detect all of these numerous dependencies automatically once the basic structure of a project file is created. For this, PBUILD.EXE is started with the /g switch (g for generate):

pbuild customer.xpj /g 

The switch /g causes pbuild.exe to analyze all dependencies that exist within a project. The ProjectBuilder then expands a (rudimentary) project file and adds all missing information to the XPJ file. This frees a programmer from quite a lot of typing, especially for large projects. For instance, the ProjectBuilder expands the previous example XPJ file by 19 lines. As a result, the project file grows from 16 to 35 lines:

01:  [PROJECT] 
02:     VERSION               = 2.2 
03:     DEBUG                 = yes 
04:     TARGET_DIR            = .\run 
05:     project.xpj 
06: 
07:  [project.xpj] 
08:     customer.exe 
09: 
10:  [customer.exe]               
11:     COMPILE               = xpp       // Missing compiler and linker 
12:     COMPILE_FLAGS         = /q        // information is added 
13:     GUI                   = no 
14:     LINKER                = alink 
15:     LINK_FLAGS            = 
16:     RC_COMPILE            = arc 
17:     RC_FLAGS              = 
18:     INTERMEDIATE_DEBUG    = .debug 
19:     INTERMEDIATE_RELEASE  = .release 
20:  // $START-AUTODEPEND                 // Automatically created 
21:     collat.ch                         // dependencies 
22:     get.ch 
23:     memvar.ch 
24:     prompt.ch 
25:     set.ch 
26:     std.ch 
27:     customer.obj 
28:     getcust.obj 
29:     print.obj 
30:     viewcust.obj 
31:  // $STOP-AUTODEPEND 
32:     customer.prg 
33:     getcust.prg 
34:     print.prg 
35:     viewcust.prg 

Changes appear in the [customer.exe] section, where all missing information for compiling and linking is added. Furthermore, this section now contains a list of files for which the ProjectBuilder has detected dependencies. This automatically created list is enclosed by the markers // $START-AUTODEPEND and // $STOP-AUTODEPEND in lines 20 and 31. Both markers indicate an area in the project file which may be changed automatically when pbuild.exe is called subsequently together with the /g switch. Therefore, a project file should not be altered between these markers as changes in this area can get lost.