The package generator comes in two different version: Graphical User
Interface (pgEdit.exe) and Command Line (pg.exe). They both work from
the same set of XML configuration files, pgEdit having the advantage to
allow you to safely edit the source XML files. Here is the flow diagram:
Package XML
Source Files |
Each package XML source file
indicates which files are to be included in the package, which other
packages this package depends on and various compilation options such
as PFLAGS (Pascal Flags) for C++ Builder. All inclusions and
dependencies can be conditionally altered by a compilation directive. A runtime package should have a '-R' suffix, while a design time package should have a '-D' suffix. Hence, JvCore-R.xml is a runtime package source file while JvCore-D.xml is a design time package source file. |
XML Configuration File |
This file contains the
declaration of models that the package generator will use to generate
the files. Each model declares targets (one version of Delphi, C++
Builder or Kylix), the format of the filenames to output, the location
of
package files and optionally an include file. |
Template
Files |
These files are skeletons for
the final output files. They contain special markers that will get
replaced by values taken from the XML configuration file and the
Package Source XML files to generate the final output files. |
Include
File |
It is possible to specify
conditions for inclusion of packages and source files in packages. The
conditions are read from the include file given to the package
generator. Because the syntax of these conditions can be quite complex,
the packages must be regenerated whenever the given include file has
changed so that packages are synchronised with it. If you don't
regenerate the packages, you may have errors when compiling the
packages. |
Existing Output Files |
If the files to be generated
already exist, they will be used to determine if any change was done to
them since the last time they were generated. If unchanged, the output
files
will be left untouched. |
<?xml
version="1.0" encoding="iso-8859-1"?> |
Node |
Parent
Node |
Description |
||||||||
Package |
none (root
node) |
This is the root node. Its only
properties are Name and Design. Name is obviously the name of the
package while Design is 1 when the package is a designtime package, 0
when it is a run time package. The root node doesn't have to be called
package, but it MUST have those two properties. |
||||||||
Description |
Package |
This is the description of the
package as it will be displayed in the IDE. |
||||||||
ClxDescription |
Package |
This is the description of the
package as it will be displayed in the IDE, when the package is
generated for a CLX target. |
||||||||
GUID |
Package |
Delphi 2005 requires a GUID to
be present in bdsproj files. This is the value that will be used as
replacement for the %GUID% marker, allowing you to put such a GUID in a
file if required. This is read as a string value, no verification is
made to ensure that the value actually is a valid GUID. |
||||||||
C5PFlags |
Package |
The package files for C++
Builder 5 contain a special node to allow for passing extra arguments
to
the pascal compiler. This node indicates the value to use for the
PFLAGS node in C++ Builder 5 packages. In the example above, we added
-LUCJcl50 to indicate to link the file CJcl50.dcp into the package.
Options are separated by spaces and if followed by a string in
parenthesis, the string is considered to be a condition. If the
condition doesn't exist when the file is generated, the option is
removed. For instance, if you type -LUCJcl50(USEJVCL) then if USEJVCL
is not defined in the include file, -LUCJcl50 will be removed from the
final PFLAGS value. This final value will be the replacement for
%C5PFLAGS% in
template files. |
||||||||
C6PFlags |
Package |
This node has the same
meaning as C5PFlags but for C++ Builder 6, hence being the replacement
for %C6PFLAGS% |
||||||||
C10PFlags |
Package |
This node has the same
meaning as C6PFlags but for C++ Builder 10, hence being the replacement
for %C10PFLAGS%. If the node is absent, the value of C6PFlags is used. |
||||||||
C5Libs |
Package |
In some rare occasions, it may
be necessary to indicate some extra libraries to the C++ linker. This
happened for instance with the Network related packages in the JVCL as
they required wininet.lib. The value here should be a space separated
list of library files and will be the replacement for %C5LIBS% |
||||||||
C6Libs |
Package |
This node has the same meaning
as C5Libs but will be the replacement for %C6LIBS% |
||||||||
C10Libs |
Package |
This node has the same meaning
as C6Libs but will be the replacement for %C10LIBS%. If the node is
absent, the value of C6Libs is used. |
||||||||
ImageBase |
Package |
A string that will be the
replacement for %IMAGE_BASE%. It's recommended use is to set the base
of the image in a compiler directive. This node is not compulsory, an
empty string being used by default. |
||||||||
VersionMajorNumber |
Package |
A string that will be the
replacement for %VERSION_MAJOR_NUMBER%. It's
recommended use is to store the major version number. This node is not compulsory, an empty string being used as a default. |
||||||||
VersionMinorNumber |
Package |
A string that will be the
replacement for %VERSION_MINOR_NUMBER%. It's
recommended use is to store the minor version number. This node is not compulsory, an empty string being used as a default. |
||||||||
ReleaseNumber |
Package |
A string that will be the
replacement for %RELEASE_NUMBER%. It's
recommended use is to store the release number. This node is not compulsory, an empty string being used as a default. |
||||||||
BuildNumber |
Package |
A string that will be the
replacement for %BUILD_NUMBER%. It's
recommended use is to store the build number. This node is not compulsory, an empty string being used as a default. |
||||||||
Requires |
Package |
This node is only the parent of
all the 'package' nodes, indicating the packages required
by
the current package. |
||||||||
Contains |
Package |
This node is only the parent of all the 'file' nodes, indicating the files contained in the current package. | ||||||||
Package |
Requires |
Each package node in a Require
node indicates a package that the current package requires in order to
be
compiled. It must have the following three attributes:
|
||||||||
File |
Contains |
Each File node in a Contains
node indicates a file to include in the package. It must
have the following four attributes:
|
<?xml
version="1.0" encoding="iso-8859-1"?>
</ClxReplacements> </model> |
Node |
Parent
Node |
Description |
||||||||||||||||||||||||||||
Configuration |
node (root
node) |
This is the root node of the XML
file. It doesn't have to have any attributes and may be named
differently, but doing so would mean that pgEdit.exe needs to be
changed to
cope with the modification. pg.exe doesn't care. |
||||||||||||||||||||||||||||
pgEdit |
Configuration |
This node contains all the
subnodes required by pgEdit to save its state when closed down. The
state includes the values of various component fields, the size of the
form,
its position etc. |
||||||||||||||||||||||||||||
models |
Configuration |
This node holds the model nodes,
those nodes being the actual configuration described in this file. |
||||||||||||||||||||||||||||
model |
models |
Each model node defines a
generation model that can be used by the package generator. The first
five
attributes are compulsory and serve the following purpose:
|
||||||||||||||||||||||||||||
targets |
model |
This node holds the target
nodes, one node for each target your suite can support. |
||||||||||||||||||||||||||||
aliases |
model |
This node holds the alias nodes,
one node for each target alias you want to provide. In the example
above, using "Delphi" in a target node in a package XML source file is
equivalent to using "d7,d7p". The aliases are not resolved recursively
and are not case sensitive. You don't have to define the 'all' alias,
as it will be derived from the list of targets. |
||||||||||||||||||||||||||||
ClxReplacements |
model |
This node, if it exists, holds
the replacement nodes, one node per filename replacement. These
replacements will only occur on the filename of the contained files for
a package, and only when the target being generated is marked as CLX. |
||||||||||||||||||||||||||||
target |
targets |
Each target node must have at
least the name attribute. All other attributes are optionnal:
|
||||||||||||||||||||||||||||
alias |
aliases |
Each alias node must have those
two attributes:
|
||||||||||||||||||||||||||||
replacement |
ClxReplacements |
Each replacement node must have
those two attributes:
|
State |
Marker |
Description |
Standard Line |
<%%%
START REQUIRES %%%> |
Must be alone on the line. Goes
to the 'Requires Section' state. |
<%%% START FILES %%%> | Must be alone on the line. Goes
to the 'Files Section' state. |
|
<%%% START FORMS %%%> | Must be alone on the line. Goes
to the 'Forms Section' state. |
|
<%%% START LIBS %%%> | Must be alone on the line. Goes
to the 'Libs Section' state. |
|
%NAME% |
Replaced by the name of the
output file. |
|
%XMLNAME% |
Replaced by the name of the
package XML source file. |
|
%GUID% |
Replaced by the value from the
GUID node in the package XML source file. |
|
%DESCRIPTION% |
Replaced by the description of
the package. If the target for which the generation occurs is marked as
being CLX, the CLX description is used here. |
|
%C5PFLAGS% |
Replaced by the value from the
c5pflags node in the package XML source file, after it has been
processed for conditions. |
|
%C6PFLAGS% | Replaced by the value from the c6pflags node in the package XML source file, after it has been processed for conditions. | |
%IMAGE_BASE% |
Replaced by the value from the
ImageBase node in the package XML source file. |
|
%VERSION_MAJOR_NUMBER% |
Replaced by the value from the VersionMajorNumber node in the package XML source file. | |
%VERSION_MINOR_NUMBER% |
Replaced by the value from the VersionMinorNumber node in the package XML source file. | |
%RELEASE_NUMBER% |
Replaced by the value from the ReleaseNumber node in the package XML source file. | |
%BUILD_NUMBER% |
Replaced by the value from the BuildNumber node in the package XML source file. | |
%TYPE% |
Replaced by 'DESIGN' or 'RUN'
depending on the type of the package. |
|
%type% |
Replaced by 'd' or 'r' according
to the type of the package. |
|
%DATETIME% |
Replaced by the current date and
time adjusted to UTC, formatted according to the string 'dd-mm-yyyy
hh:nn:ss' and followed by ' UTC'. You should only use this marker once in the entire template for the difference detection mechanism to work correctly. Please see the detailed description of the generation process for more details. |
|
Requires
section |
%NAME% |
The name of the package being
required, taken from the package node in the package XML source
file. As explained before, the name may be modified according to the
format for the current model and the current target. |
<%%% END
REQUIRES %%%> |
Must be alone on the line.
Returns to the 'Standard Line' state. |
|
Files
section Forms section |
%FILENAME% | The name of the source file as
taken from the 'file' node in the package XML source file. If the
target for which the generation occurs is marked as CLX, then the CLX
replacements will occur on this value, as well as on all the others
applicable in this state. |
%UNITNAME% |
The name of the source file
without any path information and without the extension. |
|
%Unitname% |
Same as %UNITNAME% but the
replacement is all in lower case except for the first letter which is
converted to upper case. |
|
%FORMNAME% |
The name of the form, if any.
Taken from the formname attribute of the 'file' node in the package XML
source file. |
|
%FORMTYPE% |
The type of the form, if any. |
|
%FORMNAMEANDTYPE% |
The name and the type of the
form put together. If no type was specified in the formname attribute,
then this is equivalent to %FORMNAME%. |
|
%FORMPATHNAME% |
The name of the dfm file
containing the definition of the form. No extension is added, it
is simply the filename with the extension removed. |
|
Files section |
<%%% END FILES %%%> |
Must be alone on the line. Returns to the 'Standard Line' state. |
Forms section |
<%%% END FORMS %%%> |
Must be alone on the line. Returns to the 'Standard Line' state. |
Libs
section |
%FILENAME% |
The filename of the library file. |
%UNITNAME% |
The filename of the library
file, without any path information or extension. |
|
<%%% END LIBS %%%> |
Must be alone on the line. Returns to the 'Standard Line' state. |
Repeating
section |
Description |
Requires |
The lines read while in this
state will be replaced for every package required by the one being
generated. That is, for every 'package' node found in the package XML
source file. The markers will be replaced before output is written. |
Libs |
The lines read while in this
state will be replaced for every library to be included in the package
being generated. That is, for every name in the space delimited value
of
the 'C5Libs' or 'C6Libs' node in the package XML source file. The node
used depends on the target for which the generation takes place. If the
target environment is not C and/or its version is not 5 or 6, the
generator will most likely trigger an Access Violation exception. |
Files |
The lines read while in this
state will be replaced for every file to be included in the package
being generated. That is, for every 'file' node found in the package
XML
source file. The markers will be replaced before output is written. |
Forms |
This section follows the same
repeat conditions as the Files section, except that a 'file' node will
only be used if its 'formname' attribute is not empty. |
C++ Builder package files, however, are XML files and do not support
conditional compilation directives. The only way to reproduce the
behaviour supported by Delphi is to regenerate the packages every time
the
include file is modified. This is because the package generator
analyses the include file (if told to do so by the model) and outputs a
conditioned line if the condition is defined in the include file.
Before the generation process takes place, the include file is parsed
to determine which conditions are defined. A list of 'defines' is
created from the file, and each 'define' has a list of 'ifdefs'
associated with it. This list indicates which other conditions must or
must not be defined for this one to be defined. Let's consider this
simple file:
{$DEFINE
DIRECT_DEFINE} |
<b-exp> | ::= <b-term> ( [ "|" | "||" | "^" ] <b-term> )* |
<b-term> |
::= <b-notfactor> ( [ "&" | "&&" ] <b-notfactor> )* |
<b-notfactor> | ::= <b-factor> | "!" <b-factor> |
<b-factor> | ::= "(" <b-exp> ")" | <ident> |
! |
not |
&,
&& |
and |
|,
|| |
or |
^ |
xor |
!A
&& (B || C) || (D && E) && F || G || H |
-h |
Displays a help message,
reminder of the available options, then exits. |
-m=MODEL |
Indicates the model to use. The
model must exist in the configuration file. Defaults to 'JVCL'. |
-x=CONFIGFILE |
Indicates the location of the
xml configuration file. Defaults to 'pg.xml'. If 'pg.xml' does not exists, defaults to 'pgEdit.xml'. This has been done to allow for the usage of one xml file shared by both pg.exe and pgedit.exe. |
-t=TARGETS |
Indicates the targets to build
as a list of comma separated target names. You should not indicate any
personal targets here. Defaults to 'all'. |
-p=PATH |
Indicates the root path for the
packages. Defaults to the value defined in the model to use. |
-r=PREFIX |
Indicates the prefix for the
packages. Defaults to the value defined in the model to use. |
-f=FORMAT |
Indicates the format of the name
of packages. Defaults to the value defined in the model to use. |
-i=INCLUDEFILE |
Indicates the name of the
include file to parse. Defaults to the value defined in the model to use. |
In any case, please feel free to contact the JVCL team.