About Directive Files¶

Introduction to directive files¶

Paquet Builder introduces a specific file type called "directive file": Paquet Builder's directive files are given the extension .pbd. They are text based and they contain instructions for Paquet Builder in order to create a package. Directive files are useful for external applications which need to create packages (for instance, the Paquet Builder's shell extension works with directive files) or modify existing projects (transforms).

We recommend you to save directive files in UTF-8 format (with or without BOM).

How to open and execute directives.

How do directive files work?¶

Directives files work like the old Windows configuration (.ini extension) files. Below you can see an example:

; Paquet Builder Directive File
; Version 1.1

[DirectiveVariables]
MYVERSION=1.0

[General]
Title=My archive {$MYVERSION$} 
ProjectTemplate=c:\mywork\myproject\baseproj.pbpx
OutputDir=c:\mywork\myproject\output
OutputName=myarc.exe
Company=G.D.G. Software
EXEtype=0 ;32-bit
IsWizard=1
StorePaths=1
Folder=c:\mywork\source\
SubFolders=1
Icon=c:\mywork\myproject\media6.ico

[Source]
0=c:\mywork\myproject\source\*.* 
1={$PBDIRECTPATH$}\data source files\*.xml

They must contain the "General" section but you can also have several additional sections like "Source", "Templates", "Components", "CustomValues", "Variables", "DirectiveVariables", etc.

General Section¶

The "General" section contains parameters that configure the package. If a parameter is not specified, then the default value is used (or the one of the template project). Parameters can be specified in any order you wish. Note about Boolean type: use 0 or 1. 1 means true, 0 means false.

• BinFolder: defines the root folder for the temporary bin output folder where the compiler places its temporary resources.

• CheckRights: if you want to check for administrative rights. Boolean type.

• Company: defines the company name. MANDATORY if you use the command-line compiler.

• CompressionCPUThreads: number of CPU threads that will be used for compression (LZMA2 required). Integer type.

• CompressionEngine: defines the Unpacking Engine for files. Integer, three values possible: 0=Let Paquet Builder decide for me (default) - 1=small engine - 2=full-featured engine.

• CompressionHeader: enables/disables compression of file headers. Boolean type.

• CompressionLevel: sets the compression level for 7-Zip. Integer from 0 (store - no compression) to 4 (ultra compression).

• CompressionLZMA2: enables/disables LZMA2 use instead of LZMA. Boolean type.

• CompressionSolid: enables/disables solid compression. Boolean type.

• Copyright: changes the copyright (version info) for the package.

• CryptFilenames: lets you encrypt filenames in 7-zip archive. Boolean type.

• DestFolder: defines the destination folder for files. Do not use it if you create a Setup package.

• DigitalSign: indicates whether the package should be digitally signed. Boolean type.

• Email: changes the company email.

• EncryptFiles: encrypts files when compressing using the password defined by KeyProtect. Boolean type.

• EndPrompt: modify the prompt to be displayed at end.

• EXEType: defines bitness (x64 or x86) for the package EXE file. 0 = 32-bit (default) ; 1 = 64-bit.

• ExistingArchive: instead of listing files to be compressed, you can specify the full path to an existing archive (7-Zip). If you use this property, then the "Source" section becomes useless, but you can still use it.

• FileDesc: sets the package's file description in the Version Information resource.

• FileDescUninst: sets the uninstaller's file description in the Version Information resource.

• FileVerNum: sets the package's file version number in the Version Information resource.

• Folder: indicates the folder to be used as the root folder for storing path information.

• HideProgress: indicates whether the progress indicator is displayed or not. Boolean type.

• Homepage: changes the URL to your company website.

• Icon: full path to the icon file to be used for the package.

• IconUninst: full path to the icon file to be used for the uninstaller.

• InstallMSI: boolean type (two values 1 (true) or 0 (false) - default = 0). Indicates whether the file whose path is defined by SetupExec is a Windows Installer MSI file (or MSP).

• IsWizard: boolean type (two values 1 (true) or 0 (false)). Indicates whether the package's user interface should have a wizard theme or a standard theme.

• KeepExistingProjectFiles: if you work with the ProjectTemplate property and your project did contain files, this property tells Paquet Builder whether it should keep the existing files or reset the file list when adding files specified by the directive file. This property is ignored if NoSourceSection is set to "1".

• KeyProtect: password to be used for encrypting files.

• LiveUpdate: causes Paquet Builder to perform a live update of all files and components when the template project is loaded. Only works if ProjectTemplate is specified. Boolean type.

• MinimumElevatedRights: only read if RequestElevatedRights is set to "1". 0 = Require Administrator ; 1 = Highest Available.

• MinimumUserRights: only read if CheckRights is set to "1". 0 = administrative ; 1 = power user rights.

• MultiVolumeArc: tells Paquet Builder to create a multi-volume archive. Boolean type: 1 means true, 0 means false. You can set the volume size with VolumeSize.

• NoSourceSection: indicates that there is no Source section in the directive file. Boolean type: 1 means true, 0 means false. You should use this property only if you also specify a project template with ProjectTemplate.

• OutputDir (required): defines the path to the output directory where the package file is created and temporary files stored.

• OutputName (required): defines the filename of the package file, do not forget the extension (EXE or 7Z if creating an archive file).

• OverwriteReadOnly: indicates whether files with read-only attribute should be overwritten. Boolean type.

• PackMode (required): specifies the type of project to create. Remember that if you create a Setup type, you need to specify the setup loader at least. Values: 0: Standard ; 1: Setup ; 2: Archive.

• PasswordToAsk: lets you specify the password that will be asked to end users ("Ask end user for the following password"). If the password is specified, "Ask end user for the following password" is automatically ticked on.

• PFXFile: by default, this is the path to the PFX file used for digital signing if SignCertifLocation=0. If SignCertifLocation=1, this is the certificate subject name. Finally, if SignCertifLocation=2, this is the certificate thumbprint.

• PFXKey: optional password for the PFX file.

• ProdVerNum: sets the package's file product number in the Version Information resource.

• Project: specifies the path to the project file that Paquet Builder should create when compiling the package. Leave the field blank if you do not want Paquet Builder to create a project file.

• ProjectTemplate: if you would like to use an existing project and modify its parameters, then specify the full path to this project file. Paquet Builder will open it first, read all of these settings, then it will perform the changes indicated by the directive file and finally optionally compile the package. This property is useful if you wish to create similar packages but with different components, files or parameters.

• ReplaceStartup: defines if locked files have to be replaced at Windows startup. Boolean type.

• RequestElevatedRights: if you want to request elevated rights (UAC). Boolean type.

• SetupExec: if a "Package for Setup" is created, then you must specify the path to the installation loader. Otherwise use this property to specify a document or program file to be run after the files extraction.

• SetupParams: specify the command line parameters to pass to the run program (SetupExec).

• ShowCompSelDlg: indicates whether the Select Components dialog box should be displayed or not. Boolean type.

• SignCertifLocation: location of the code signing certificate. Three possibles values: 0=PFX File / 1=Windows Certificate Store / 2=Certificate Thumbprint. Please refer to the code signing topic.

• SignMethod: message digest method. Three possibles values: 0=SHA-256 and SHA-1 digests / 1=SHA256 only / 2=SHA1 only. Please refer to the code signing topic.

• SignURL: optional URL to an information page about the package.

• Silent: activates the silent mode or not. Boolean type.

• SizeCheck: activates the size check or not. Boolean type.

• StartPrompt: modify the prompt to be displayed at startup.

• StoreKey: do not ask end users at runtime for the password: store it. Boolean type.

• StorePaths: defines whether Paquet Builder stores path information or not. Be sure to specify the relative folder using the "Folder" directive (see above). Boolean type.

• SubFolders: defines whether Paquet Builder should include sub-folders when adding folders and wildcards. Boolean type.

• Title (required): defines the title for the package.

• UseLocalDirForTemp: if True, the package will unpack its temporary folder in a subfolder of its directory and not in the user's temporary directory. Boolean type.

• Trademarks: changes the trademarks (version info) for the package.

• VolumeSize: the desired volume size in bytes for each volume file when creating a multi-volume archive.

• WizBanner: indicates the image to be used for the wizard header (top right side) if you create a wizard package. Refer to user interface.

• WizLabel: changes the label text for the wizard if you create a wizard package. Refer to user interface.

• WizSplash: indicates the watermark image (window left side) to be used if you create a wizard package. Refer to user interface.

Source Section¶

The "Source" section is the list of files that should be included. It can contain wildcards. It must be an ordered list: each entry begins with its number in the list and points to a path or a file. Allowed: single files, wildcards (*. + extension : *.* for instance). Paquet Builder can include sub directories when adding an entire folder: use the "SubFolders" property described above.

Paths must be full paths (including drive). If you want to use relative paths, work with the {$PBDIRECTPATH$} directive variable which points to the folder that contains the directive file. See directive variables below.

Example:

[Source]
0=c:\mywork\myproject\source\*.*
1=c:\mywork\myproject\readme.txt
2=c:\windows\system\cabinet.dll
3=c:\mywork\myproject\shared\*.obj 
4={$PBDIRECTPATH$}\source\*.exe

Components Section¶

This section lets you create components or configure the properties of existing ones. Please first refer to the Component Overview help topic before using this section.

The Components section is a list of the components that should be created. It must be an ordered list: each entry begins with its number in the list and points to the component name.

Example:

[Components]
0=Documentation
1=Pictures
2=SystemData 

When processing a Component entry of the "Components" section, Paquet Builder will look for two other sections associated to the component. These sections are called "{Component Name}.Source" and "{Component Name}.Properties", where {Component Name} designates the name of the component in the "Components" section. For example, if the component name is "Documentation", the two sections should be "Documentation.Source" and "Documentation.Properties".

The "Main" component is always created and the "Source" section above actually corresponds to the files that should be added to the Main component. You can however still configure the properties of the Main component using the section "Main.Properties" (see the last example below).

{Component Name}.Source Section¶

Indicates the list of files that should be added to the component "{Component Name}" (must be referenced in the Components section). It works exactly as the "Source" section above so please refer to this paragraph for further information. You can also link the component to a source folder and use live-update to automatically add files to the component.

{Component Name}.Properties Section¶

Defines the properties of the associated component "{Component Name}". This section is optional.

Includes the following parameters:

• CustomDestinationFolder: optional custom destination folder for all files in the component. For instance: %COMTEMPLATESDIR%\The templates.

• Description: description associated with the component.

• FileMaskInclude: lets you indicate optional filename masks for adding files. For instance: *.exe|*.dll|*.xls. See further explanation: Optional Filename Mask for Inclusion.

• FileMaskExclude: lets you indicate optional filename masks for excluding files. For instance: *.bak. See further explanation: Optional Filename Mask for Exclusion.

• IncSubFolders: whether files in subfolders of the source folder should be included or not. Boolean type.

• InstallDef: indicates whether the component is installed by default or not. Boolean type.

• NoDisplay: if set to "1" (true), the component is not displayed in the Select Components dialog box. Boolean type.

• Required: indicates whether end users can turn on/off the component or not. Boolean type.

• RootFolder: if StoringPath is set to "1", RootFolder must indicate the path of the root folder.

• SourceFolder: the path to the source folder if the component is linked to it.

• SourceLinked: is the component linked to a source folder? Boolean type. If true, you must specify the source folder and Paquet Builder will do a live-update for the component after processing the Source section.

• StoringPath: three possible values (0, 1 or 2) - 0 by default. Defines how path information should be stored for the files inside the component.

  • 0: uses global settings (that you can also configure in the General section above).
  • 1: uses the root folder specified by RootFolder.
  • 2: no path information should be stored, only filenames.
  • 3: uses the component's source folder specified by SourceFolder.

• Title: title of the component which should appear in the Select Components dialog box.

• Variable: name of the variable associated to the component. Must begin with VCOMP and enclosed into two % symbols. By default: %VCOMP{component name}%.

Templates Section¶

The "Templates" section includes the list of rich content files that should be used with specific dialogs like Welcome Screen, Readme, License Agreement or Final Screen. An entry should be the name of the dialog followed by = and then by the full path to the rich text file to be used.

• Welcome: indicates the HTML file to be used for the Welcome screen.

• StartReadme: indicates the HTML file to be used for the Starting Readme.

• EndReadme: indicates the HTML file to be used for the After Extraction Readme.

• End: indicates the HTML file to be used for the End screen.

• LicAg: indicates the HTML file to be used for the license agreement.

Some entries are ignored if you do not create a Wizard package (refer to user interface).

Example:

[Templates]
Welcome=c:\mywork\myproject\welcom1.htm
StartReadme=c:\mywork\myproject\readme.htm
End=c:\mywork\myproject\final.htm

Variables Section¶

The "Variables" section lets you create custom variables or update existing ones. Since these variables can be used anywhere in your Paquet Builder project, especially with custom actions, you can use the Variables section to modify them directly from directive files.

Example:

[Variables]
%MYVAR%=1
%MYVAR2%=Something else

Note that Paquet Builder defines these variables and sets their values by generating a "Perform operation on a variable" custom action for each variable at the top of the Initialization event.

CustomValues Section¶

The "CustomValues" section lets you specify custom values for fields that should be set when loading the directive file. These custom values are generally not available through the General section.

Example:

[CustomValues]
urk.Text=MyProgram215
ucd.Text=My Uninstaller

urk.Text indicates that we should set the field whose ID is urk to MyProgram215. urk is the internal name for the Unique Registry Key field. The same for ucd which is the ID for Control Panel Description.

To get the ID for a specific field, please post your query to the forum.

Example of directive file with components¶

The following directive file creates two components called "Documentation" and "Pictures" in addition to the "Main" one. It will also display the Select Components dialog box to allow end users to choose which components they wish to install.

; Paquet Builder Directive File
; Version 1.1

[General]
Title=My archive 1
OutputName=direct1.exe
OutputDir=C:\My Documents\pb\Output
IsWizard=1
StorePaths=0
SubFolders=0
Icon=C:\My Documents\pb\installer.ico
ShowCompSelDlg=1

[Components]
0=Documentation
1=Pictures

[Source]
0=C:\My Documents\Works\Application Demo\bin\*.*

[Main.Properties]
Description=Main Application Files
NoDisplay=1
; This component is installed by default. No need to show it to end users.

[Documentation.Source]
0=C:\My Documents\Works\Application Demo\help\*.chm

[Documentation.Properties]
Description=Installs the documentation of the application (recommended)
Title=Documentation
StoringPath=1
RootFolder=C:\My Documents\Works\Application Demo 

[Pictures.Source]
0=C:\My Documents\Works\Application Demo\pictures\*.*
1=C:\My Documents\My pictures\templates\*.jpg

[Pictures.Properties]
Description=Installs the pictures to be used with the application.
Title=Sample pictures 

Example of simple directive file without source:¶

; Paquet Builder Directive File

[General]
Title=My archive 1
NoSourceSection=1
OutputName=direct 2.exe
OutputDir=C:\My Documents\pb\Output
ProjectTemplate=C:\My Documents\pb\debug\testmsi1.pbpx
LiveUpdate=1 

This directive is only intended to change the name of the output file and refresh the file list. Paquet Builder will just load our testmsi1.pbpx project, perform a live update, change the package filename and that's all. You can of course add more parameters if you wish.

Directive Variables¶

Since full paths must be used in directives, this can be problematic when you are moving your source files and directive to a third-party machine such as a build server. That's why Paquet Builder offers some built-in directive variables: you can use them to replace absolute paths with relative ones.

You can also specify your own directive variables that will be replaced automatically: see below.

Directive variables can be used anywhere in your directive's contents (General, Source, Components... sections) but they are not defined in Paquet Builder (so do not use them in the GUI fields nor in your project).

List of directive variables¶

Example¶

Your directive file is available at C:\Users\Joe\Documents\Software\Distribution\Directive1.pbd

Without variables, you have to use full paths like:

[Source]
1=C:\Users\Joe\Documents\Software\Distribution\Source Files\*.*
2=C:\Users\Joe\Documents\Software\Distribution\Documentation\*.chm

With directive variables:

[Source]
1={$PBDIRECTPATH$}\Source Files\*.*
2={$PBDIRECTPATH$}\Documentation\*.chm

{$PBDIRECTPATH$} will be replaced by C:\Users\Joe\Documents\Software\Distribution because it's the path to the directive file.

Then, you can move your source files and directive to another location, such as:

G:\Build\Directive1.pbd

In that case, {$PBDIRECTPATH$} will be replaced by G:\Build

Define your own directive variables¶

You can define your own directive variables in the [DirectiveVariables] section.

For instance, the following code defines two directive variables:

; Paquet Builder Directive File
[DirectiveVariables]
MYVERSION=1.0
PROGRAMOUTPUT=installer version

Then you can use these directive variables anywhere else in the directive file.

Syntax: {$YOURVARIABLENAME$}

Example with the two previously-defined variables:

; Paquet Builder Directive File
[General]
Title=My archive {$MYVERSION$}
OutputName={$PROGRAMOUTPUT$} {$MYVERSION$}.exe
OutputDir=C:\My Documents\pb\Output