PasHi Build Instructions

Introduction

These instructions show how to build the PasHi command line program and, optionally, PasHiGUI - the GUI front end to PasHi.

The programs are written in Object Pascal and are targeted at Delphi XE.

The Delphi IDE can be used to modify the source and to perform test builds. Final builds should be built using the provided makefiles.

Dependencies

Libraries

PasHi

No libraries are required to build PasHi

PasHiGUI

PasHiGUI requires PJWdwState.pas from the DelphiDabbler Window State Components, v5.6.1 or later. A copy of the required file is included in the Src\GUI\Imported directory. There is no need to install the components into the DelphiIDE.

Delphi VCL

You need the relevant Delphi VCL in order to compile the programs.

Build Tools

The following tools are needed to build the programs.

Delphi

A copy of Delphi is required to build the object Pascal code. Delphi XE is the preferred compiler.

You can use the Delphi IDE to edit the code and test compile it. The makefiles require the following command line tools:

DCC32

The Delphi command line compiler.

Not available with starter editions of Delphi.

RC

The Microsoft resource compiler. Used to compile the main resource file.

BRCC32

The Borland resource compiler. Used to compile version information resources from temporary resource files emitted by VIEd (see below).

The following environment variables are associated with these tools:

DELPHIROOT - required unless DELPHIXE is set.

Should be set to the install directory of the version of Delphi being used. DCC32, BRCC32 and RC are expected to be in the Bin sub-directory of DELPHIROOT.

DELPHIXE - optional

If you are using Delphi XE this environment variable may be set to its install directory. When DELPHIXE is specified DELPHIROOT will be ignored and DELPHIXE will be used instead.

Borland MAKE

This is the make tool that ships with Delphi. You can use any version that works.

DelphiDabbler Version Information Editor (VIEd)

This tool is used to compile version information (.vi) files into intermediate resource source (.rc) files. Version 2.11.2 or later is required. Version Information Editor can be obtained from https://delphidabbler.com/software/vied.

The program is expected to be on the path unless its install directory is specified by the VIEDROOT environment variable.

Inno Setup

The Unicode version of the Inno setup command line compiler is needed to create CodeSnip's install program. v5.4.0 (u) or later is required as is a compatible version of the ISPP pre-processor. You can get Inno Setup with ISPP at https://www.jrsoftware.org/isinfo.php. Choose the Unicode version. If you already have the ANSI version the Unicode version can be installed alongside it - just use a different install directory and program group name.

The program is expected to be on the path unless its install directory is specified by the INNOSETUP environment variable.

Zip

This program is used to create release files. You can get a Windows command line version at http://stahlforce.com/dev/index.php?tool=zipunzip.

The program is expected to be on the path unless its install directory is specified by the ZIPROOT environment variable.

Preparation

Configure the environment.

The first step is to configure the required DELPHIROOT or DELPHIXE environment variables.

Next, set any of the optional VIEDROOT, INNOSETUP and ZIPROOT environment variables that are needed to specify the path to any tools that are not on the system path.

You can configure environment variables either by modifying your system environment variables or by creating a batch file that you run before performing the build.

Get the Source Code

If you don't already have it, you need to get the PasHi source code, (which includes the source for PasHiGUI).

The source code is maintained in the delphidabbler/pashi Git repository on GitHub. Either clone or fork the repo into a directory on your computer.

Source code for PasHi's latest release can be found in the master branch while development code is maintained in the develop branch. New features are developed in branches whose name begins with feature. You can also download the code of one of the releases by selecting the relevant tag.

If you want to submit any modifications to the source code, please create a new feature branch off the develop branch, commit your modifications to it and then submit a pull request on GitHub.

Configure the Source Tree

After obtaining the source code you should have the following directory structure:

./
  |
  +-- Config                - config files to be installed with PasHi
  |
  +-- Docs                  - documentation
  |
  +-- Src                   - source code for PasHi
  |   |
  |   +-- Assets            - assets required to build PasHi's resources
  |   |
  |   +-- GUI               - source code of the GUI application, PasHiGUI
  |   |   |
  |   |   +-- Assets        - assets required to build PasHiGUI's resources
  |   |   |
  |   |   +-- Imported      - 3rd party source code used for GUI application
  |   |
  |   +-- Install           - install program scripts
  |
  +-- Test                  - contains test file

Don't worry if you also have a Build directory and sub-directories - all will become clear.

Before you can get hacking, you need to prepare the source code tree. Open a command console and run any script you have created to set the required environment variables. Then navigate into the Src sub-folder and do:

Src> Make config

You may need to replace Make with the full path to Make if it isn't on the path, or if the Make that runs isn't the Borland / CodeGear / Embarcadero version. If this is the case try:

Src> "%DELPHIROOT%\Bin\Make" config

or

Src> "%DELPHIXE%\Bin\Make" config

depending on which environment variable you have set.

Once Make config has completed, your folder structure should have acquired a Build folder and sub-folders and now look like this:

./
  +-- Build                 - receives all files created by the build process
  |   |
  |   +-- Bin               - receives object files and .res files for PasHi
  |   |
  |   +-- Exe               - receives executable code
  |   |
  |   +-- Release           - receives release files
  |
  +-- Config                - config files to be installed with PasHi
  |
  +-- Docs                  - documentation
  |
  +-- Src                   - source code for PasHi
  |   |
  |   +-- Assets            - assets required to build PasHi's resources
  |   |
  |   +-- GUI               - source code of the GUI application, PasHiGUI
  |   |   |
  |   |   +-- Assets        - assets required to build PasHiGUI's resources
  |   |   |
  |   |   +-- Imported      - 3rd party source code used for GUI application
  |   |
  |   +-- Install           - install program scripts
  |
  +-- Test                  - contains test file

Make will have created a .cfg file from the template in the Src folder. .cfg files are needed for DCC32 to run correctly. This new file will be ignored by Git.

If you also want to compile PasHiGUI you must now do:

Src> cd GUI
Src\GUI> Make config
Src\GUI> cd ..

This runs a separate makefile in the Src\GUI sub-directory and further configures the source tree to enable PasHiGUI to be compiled. The source tree should have been changed slightly to look like this:

./
  +-- Build                 - receives all files created by the build process
  |   |
  |   +-- Bin               - receives object files and .res files for PasHi
  |   |   |
  |   |   +-- GUI           - receives object files and .res files for PasHiGUI
  |   |
  |   +-- Exe               - receives executable code
  |   |
  |   +-- Release           - receives release files
  |
  +-- Config                - config files to be installed with PasHi
  |
  +-- Docs                  - documentation
  |
  +-- Src                   - source code for PasHi
  |   |
  |   +-- Assets            - assets required to build PasHi's resources
  |   |
  |   +-- GUI               - source code of the GUI application, PasHiGUI
  |   |   |
  |   |   +-- Assets        - assets required to build PasHiGUI's resources
  |   |   |
  |   |   +-- Imported      - 3rd party source code used for GUI application
  |   |
  |   +-- Install           - install program scripts
  |
  +-- Test                  - contains test file

Make will also have created the required .cfg file in the Src\GUI directory.

If you are intending to use the Delphi IDE to compile PasHi, you should also do:

Src> Make resources

and, for PasHiGUI:

Src> cd GUI
Src\GUI> Make resources
Src\GUI> cd ..

This compiles the resource files that the IDE needs to link into compiled executables.

You are now ready to build the source.

Building The Programs

Creating The Executables

Once the source tree has been configured, and before you can build the Pascal code, you must create the program's resources. For PasHi do:

Src> Make resources

and for PasHiGUI do:

Src> cd GUI
Src\GUI> Make resources
Src\GUI> cd ..

And now you can build the Pascal code:

Src> Make pascal

or

Src> cd GUI
Src\GUI> Make pascal
Src\GUI> cd ..

Should you want to build an executable from a clean source tree there is a shortcut. Simply running:

> Make

on its own is the same as doing:

> Make config
> Make resources
> Make pascal

So, to build PasHi and PasHiGUI and place PasHi.exe and PasHiGUI.exe in the Build\Exe folder do this:

Src> Make
Src> cd GUI
Src\GUI> Make
Src\GUI> cd ..

There's a shortcut for building PasHiGUI: using the main makefile just do:

Src> Make pashigui

When both the PasHi and PasHiGUI executables have been built you can create the setup program. This is done from the main makefile with:

Src> Make setup

Creating the Release zip file

Once the setup program has been generated you can create a zip file containing the setup program and the required documentation files. You create the zip by doing:

Src> Make release

Note that this only works with the makefile in the Src directory: the release target is not supported by Src\GUI\Makefile.

By default the release file is called dd-pashi.zip. You can change this name by defining the RELEASEFILENAME enviroment variable or macro. For example, you can name the release MyRelease.zip by doing:

Src> Make -DRELEASEFILENAME=MyRelease release

Release zip files are always placed in the Build\Release directory.

One-shot Build and Release

When you are ready to create a release there is a shortcut you can use to configure the source tree, build the executables and the setup program, and finally package the release zip file. Use the following command:

Src> Make all

Once again you can change the release file name using the RELEASEFILENAME environment variable or macro:

Src> Make -DRELEASEFILENAME=MyRelease all

Clean Up

Various temporary files and directories are created by the IDE. These can be deleted by running:

Src> Make clean

This command is only available in the makefile in the Src directory and acts on the whole source tree, including the GUI sub-tree.

Be warned that this command removes the __history folders that Delphi uses to record earlier versions of files.

Make clean leaves behind the files and directories created by Make config. To delete these files and directories in addition to performing a normal clean run:

Src> Make deepclean

Once again this command operates on both the Src and Src\GUI directories.

Testing

A test file, named Test.pas, is provided in the Test directory. This file can be used to test the output of PasHi. It contains some unusual but valid constructs that push the program to its limits.

Test.pas was not designed to compile, so do not add it to the project.

License & Copyright

If you are planning to re-use or modify any of the code, please see the file LICENSE.md for an overview of the open source licenses that apply to the source code.

LICENSE.md also provides copyright information.