# CodeSnip Build Instructions

## Introduction

CodeSnip is written in Object Pascal and is targeted at Delphi XE. Compilation with other compilers is not guaranteed.

For an explanation of why CodeSnip still uses Delphi XE see FAQ 11 of the CodeSnip Compiling & Source Code FAQs.

The are currently two editions of CodeSnip: the standard edition and the portable edition. They both share the same code base: the different editions are created using conditional compilation. These instructions show how to build either edition.

## Dependencies

Several DelphiDabbler and other 3rd party libraries and components are required to compile CodeSnip. They are all included in the code repository in the `Src/3rdParty` directory.

It goes without saying that you will also need the RTL and VCL that ships with Delphi.

## Build Tools

The following tools are required to build CodeSnip.

### Delphi

All the following tools that ship with Delphi XE are required:

`MAKE`
  The make tool – do not use the Microsoft make tool.
`DCC32`
  The Delphi command line compiler.
`BRCC32`
  The Borland resource compiler. Used to compile various resource source (`.rc`) files.
`GenTLB`
  Type library generator. Used to create the `ExternalObj.tlb` type library from source code in `ExternalObj.ridl`.
`TLibImpl`
  Type library importer tool. Used to create a Pascal unit that describes code contained in `ExternalObj.ridl`.

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 `TLibImpl` are expected to be in the `Bin` sub-directory of `DELPHIROOT`.
`DELPHIXE` - optional
  This environment variable can be set to the Delphi XE install directory. When `DELPHIXE` is defined `DELPHIROOT` will be set to the value of `DELPHIXE`.

### DelphiDabbler Version Information Editor (VIEd)

This tool is used to compile version information (`.vi`) files and any associated macro file(s) into intermediate resource source (`.rc`) files. Version 2.15.0 or later is required. Version Information Editor can be obtained from https://github.com/delphidabbler/vied/releases.

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

### DelphiDabbler HTML Resource Compiler (HTMLRes)

HTMLRes is used to compile `HTML.hrc` which adds various HTML, JavaScript, CSS and images to HTML resources. Version 1.1 or later is required. The HTML Resource Compiler can be obtained from https://github.com/delphidabbler/htmlres/releases.

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

### Inno Setup

The Unicode version of the Inno Setup v5 command line compiler is needed to create CodeSnip's install program. v5.5.2(u) or later is required.

Warning: Do not use Inno Setup v6. This will fail to compile the setup script. Inno Setup 6 does not support Windows 2000 or XE, while CodeSnip still does.

You can get Inno Setup at https://www.jrsoftware.org/isinfo.php. Choose the Unicode version and ensure that the ISPP pre-processor is installed. 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 path to Unicode Inno Setup's install directory will be looked for in the `INNOSETUP_U` environment variable, or, if that is not set, in the `INNOSETUP` environment variable. If neither of these is set then the correct version of Inno Setup is expected to be on the path.

Note: Inno Setup is not required if you are creating only the portable edition of CodeSnip since that edition does not have an install program.

### Microsoft HTML Help Compiler (HHC)

This command line compiler is supplied with Microsoft HTML Help Workshop. It is used to compile the CodeSnip help file.

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

### Zip

This program is used to create CodeSnip's release file. The InfoZip version of zip is required. You can get a Windows command line version at http://stahlforce.com/dev/index.php?tool=zipunzip.

Warning: The above link is `http` only. If you or your browser object to the insecure link you can download an identical version from delphidabbler.com, using the `https` protocol. See https://delphidabbler.com/extras/info-zip.

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

You do not need Zip if you do not intend to create release files.

## Preparation

### Configure the environment.

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.

#### Step 1

Configure the required environment variables. Compilation will fail if these environment variables are not set:

- `DELPHIROOT` or `DELPHIXE`

#### Step 2

Update the `PATH` environment variable to include `%DELPHIROOT%\Bin` as its first path, i.e. do:

    > set PATH=%DELPHIROOT%\Bin;%PATH%

You do not have to do this but it means you can run `Make` from the command line without having to specify its path every time.

#### Step 3

Set any of the following environment variables that are needed to specify the path to any tools that cannot be found on the path:

- `VIEDROOT`
- `HTMLRESROOT`
- `INNOSETUP_U` or `INNOSETUP`
- `HHCROOT`
- `ZIPROOT`

### Get the Source Code

The source code is maintained in the `delphidabbler/codesnip` Git respository on GitHub. Source code can be obtained in three ways:

1. Fork the project from GitHub and then clone your forked repository.

2. Clone the existing repository using:

       > git clone https://github.com/delphidabbler/codesnip.git

3. Download the source of a specific release from the project's Releases section on GitHub – just choose the version you want.

If you are intending to contribute code to the project please read the most up to date version of the project's read-me file before doing so.

Important: If you are planning to fork CodeSnip and to develop and release your own application derived from the CodeSnip code base then some changes to the code are required under the terms of the CodeSnip license. See the Conditions For Release of Modified Code section below for details.

### Configure the Source Tree

After forking the repository or downloading and extracting the source code you should have the following directory structure:

    ./
      |
      +-- Docs                    - documentation
      |   |
      |   +-- Design              - documents concerning program design
      |      |
      |      +-- FileFormats      - documentation of CodeSnip's file formats
      |
      +-- Src                     - main CodeSnip source code
      |   |
      |   +-- 3rdParty            - third party & DelphiDabbler library source code
      |   |
      |   +-- AutoGen             - receives automatically generated code
      |   |
      |   +-- Help                - help source files
      |   |   |
      |   |   +-- CSS             - CSS code for help files
      |   |   |
      |   |   +-- HTML            - HTML files included in help file
      |   |   |
      |   |   +-- Images          - images included in help file
      |   |
      |   +-- Install             - setup script and support code
      |   |   |
      |   |   +-- Assets          - files required for inclusion in install program
      |   |
      |   +-- Res                 - container for files that are embedded in resources
      |       |
      |       +-- CSS             - CSS files
      |       |
      |       +-- HTML            - HTML files
      |       |
      |       +-- Img             - image files
      |       |   |
      |       |   +-- AltBranding - image files used for 3rd party branding
      |       |   |
      |       |   +-- Branding    - image files used for CodeSnip branding only
      |       |   |
      |       |   +-- Egg         - image files for 'Easter Egg'
      |       |
      |       +-- Misc            - other resources
      |       |
      |       +-- Scripts         - scripting files
      |           |
      |           +-- 3rdParty    - 3rd party scripting files
      |
      +-- Tests                   - contains test code
          |
          +-- Src                 - test source code
              |
              +-- DUnit           - test source code that uses the DUnit framework

If, by chance you also have a `_build` directory don't worry - all will become clear. Git users may also see the usual `.git` hidden directory. If you have done some editing in the Delphi IDE you may also see occasional hidden `__history` folders.

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

    > Make config

You may need to replace `Make` with the full path to `Make` if it isn't on the path. If this is the case try:

    > %DELPHIROOT%\Bin\Make config

or

    > %DELPHIXE%\Bin\Make config

depending on which environment variable you have set.

Once `Make config` has run your folder structure should have acquired the following new folders, if they weren't present already:

    ./
      |
      +-- _build                  - contains all the build files
      |   |
      |   +-- bin                 - receives object files for CodeSnip
      |   |
      |   +-- exe                 - receives executable code and compiled help file
      |   |
      |   +-- release             - receives release files
      |       |
      |       +-- ~tmp~           - store for temp files ceated in release process
      |
      ...

If the `_build/bin` folder already existed, it will have been emptied. In addition, `Make` will have created a `.cfg` file from a template in the `Src` folder. This `.cfg` file is needed for DCC32 to run correctly. The file will be ignored by Git.

#### Using the Delphi IDE

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

    > Make resources
    > Make typelib
    > Make autogen

This compiles the resource files that the IDE needs to link into compiled executables, compiles the type library from IDL code and generates the Pascal file that provides an interface to the type library.

If you wish to build the portable edition of CodeSnip you also need to do:

    > Make -DPORTABLE resources

and define the `PORTABLE` conditional define in Project Options. The standard name for the portable exe file is `CodeSnip-p.exe`, but the IDE will generate `CodeSnip.exe`. You can rename the file manually.

After you have gone through these steps you can edit Pascal code and test compile from the Delphi IDE. However if you change any files compiled into resources, or the type library, or run a clean up, then you must repeat the above steps and do a complete build from the IDE.

Note that building with the make file insted of the IDE performs all the above steps automatically.

## Building CodeSnip

This section guides you through building CodeSnip from the command line, not from the IDE.

You have several options:

1. Build the CodeSnip Executable
2. Build the Help File.
3. Build the Setup Program.
4. Build the Release Zip File.
5. Build and Release Everything.
6. Clean Up.

Each of these options is described below. All except options 5 and 6 assume that `Make config` has been run.

Note: This information applies only to building CodeSnip itself, not to building and using the code in the `Test` directory.

### Build the CodeSnip Executable

This is the most common build and has a simple command:

    > Make codesnip

This is the same as doing this sequence of commands:

    > Make typelib
    > Make resources
    > Make autogen
    > Make pascal

The CodeSnip executable, named `CodeSnip.exe` will be placed in the `_build\exe` folder.

#### Portable edition

To build the portable edition of CodeSnip you must either define the `PORTABLE` environment variable or do:

    > Make -DPORTABLE codesnip

Again the executable is placed in the `_build\exe` folder, but this time it is named `CodeSnip-p.exe`

### Build the Help File

To build the help file just do

    > Make help

The compiled help file will be written to the `_build\exe` folder.

The same help file is used for the standard and portable editions.

### Build the Setup Program

The setup program requires that the CodeSnip executable and the compiled help file are already present in the `_build\exe` directory.

As an aside, you can make all the required files by doing:

    > Make exes

Once you have built all the required files you build the setup file by doing:

    > Make setup

The setup program is named `CodeSnip-Setup-x.x.x.exe`, where x.x.x is the version number extracted from CodeSnip's version information. It is placed in the `_build\exe` directory.

If the SpecialBuild string is defined in CodeSnip's version information the string will be appended to the setup file name like this `CodeSnip-Setup-x.x.x-SPECIALBUILD`.

#### Portable edition

CodeSnip's portable edition does not use a setup file so `Make setup` does nothing except print a message if it is run when the `PORTABLE` symbol is defined.

### Build the Release Zip File

Make can create zip files containing all the files that are included in a release. Zip files are written to the `_build\release` directory.

#### Standard edition

The release zip file for the standard edition requires that the setup files is already present in the `_build\exe` directory.

The release file includes the setup file along with `ReadMe.txt` that is automatically generated from `Docs\ReadMe-standard.txt`.

Build the release by doing:

    > Make release

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

    > Make -DRELEASEFILENAME=MyRelease release

Note that the `.zip` extension should not be included in the file name.

#### Portable edition

The release zip file for the portable edition cannot be created until the CodeSnip excutable and the compiled help file are already present in the `_build\exe` directory.

The release file includes the portable executable file, `CodeSnip-p.exe`, the help file `CodeSnip.chm`, `Docs\License.html` and `ReadMe.txt` that is automatically generated from `Docs\ReadMe-portable.txt`.

Build the portable release by doing:

    > Make -DPORTABLE release

By default the release file is named `dd-codesnip-portable.zip`. You can change this name by defining the `RELEASEFILENAME` macro or enviroment variable. For example, you can name the file `MyPortableRelease.zip` by doing:

    > Make -DPORTABLE -DRELEASEFILENAME=MyPortableRelease release

Once again note that the `.zip` extension should not be included in the file name.

Warning: If you are building both the standard and portable releases with custom file names, make sure you supply a different value of the `RELEASEFILENAME` macro for each release, otherwise the last built release will overwrite the first.

#### Including version numbers in zip file names

A version number can be suffixed to the release zip file name by defining the `VERSION` macro. This macro works with both the `PORTABLE` and `RELEASEFILENAME` macros.

For example to appended version number 4.22.0 to the zip file name on a standard edition build, with the default file name do:

    > Make -DVERSION=4.22.0 release

This will create a zip file named `codesnip-exe-4.22.0.zip`.

A more complex example would be to append the same version number to a portable edition build named `MyPortableRelease`. Do:

    > Make -DPORTABLE -DRELEASEFILENAME=MyPortableRelease -DVERSION=4.22.0 release

This time the resulting zip file will be named `MyPortableRelease-4.22.0.zip`.

### Build and Release Everything

You can do a complete build of everything, and generate the release zip file simply by doing:

    > Make

without specifying a target. This is the equivalent of:

    > Make config
    > Make exes
    > Make setup
    > Make release

To perform a complete build of the portable edition of CodeSnip do

    > Make -DPORTABLE

Note that the `RELEASEFILENAME` and `VERSION` macros that can be used for customising zip file names can be used here too.

There is also a quicker way to build a release, but you must provide a version number to use it. First navigate up to the repository root. Then run

    > Deploy 9.9.9

where `9.9.9` is the release version number.

This command will build both the standard and portable executables, the help file, the standard edition setup file and finally create the release zip files for both editions, with the release version number incorporated in the file names.

Using `Deploy 9.9.9` is the equivalent of doing:

    > cd Src
    > Make -DVERSION=9.9.9
    > Make -DPORTABLE -DVERSION=9.9.9
    > cd ..

### Clean Up

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

    > Make clean

Warning: This command removes the `__history` folders that Delphi uses to roll back to earlier versions of files.

## Running the Tests

At present all tests use the DUnit unit testing framework and are combined into a single test application.

To compile the tests, open the `Src\CodeSnip.groupproj` group project file in the Delphi XE IDE. Now select the CodeSnipTests.exe target in the project manager and compile.

If they were not already present `Bin` and `Exe` sub-directories will have been created in the `Tests` directory. The `Exe` directory contains the DUnit test program while `Bin` contains intermediate binaries.

You can compile the tests as either a GUI application (default) or as a console application. For details please see the comments in `Tests\Src\DUnit\CodeSnipTests.dpr`.

## License

The majority of CodeSnip's original source code is licensed under the Mozilla Public License v2.0. The are a few exceptions, mainly relating to third party source code and image files. For full details of all applicable licenses please read `License.html` in the `Docs` directory.

## Conditions For Release of Modified Code

If you are intending to release your own application based on the CodeSnip source code you must either change the source code as described below or seek written permission to use the DelphiDabbler CodeSnip branding. To seek such permission please use the CodeSnip Issue Tracker on GitHub.

### Required Changes

The changes are required to remove DelphiDabbler CodeSnip copyrighted branding from the program, to prevent interference with existing CodeSnip installations and to remove any implied endorsement of the modified release. You must:

1. Replace the files in the `Src\Res\Img\Branding` directory with copies of the identically named placeholder files in the `Src\Res\Img\AltBranding` directory. The placeholder files are Public Domain, so you may use them as-is, edit them or replace them. If you delete the files in `Src\Res\Img\Branding` without copying the placeholder files across then CodeSnip will fail to build.

2. Replace all relevant references, in source code and documentation, to the names "CodeSnip" and "DelphiDabbler" with your own company and program name. Relevant occurences are:

   - Wherever the names may be displayed in the GUI.
   - Wherever the names may be displayed by the installer.
   - Wherever the names occur in directory names. In particular do not use the names in the program's `%ProgramData%` and `%AppData%` sub-directories.
   - Anywhere else that use of the names could imply endorsement of the modified code.

3. Provide your own license file with content compatible with the requirements of the CodeSnip license as it relates to the code reused from the CodeSnip source tree. Do not edit or re-use `Docs/License.html`.

4. Modify source code and documentation where necessary to acknowledge the origins of the program's source code, documentation and images, in accordance with the CodeSnip license.

Note that the CodeSnip license can be found in `Docs\License.html`.

If you are unsure about whether your changes meet the license requirements then you can seek clarification by creating an issue on the aforementioned Issue Tracker.