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.
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.
The following tools are required to build CodeSnip.
All the following tools that ship with Delphi XE are required:
MAKE
DCC32
BRCC32
.rc) files.
GenTLB
ExternalObj.tlb type
library from source code in ExternalObj.ridl.
TLibImpl
ExternalObj.ridl.
The following environment variables are associated with these tools:
DELPHIROOT - required unless DELPHIXE is set.
DCC32, BRCC32 and TLibImpl
are expected to be in the Bin sub-directory of
DELPHIROOT.
DELPHIXE - optional
DELPHIXE is defined
DELPHIROOT will be set to the value of
DELPHIXE.
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.
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.
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.
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.
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.
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.
Configure the required environment variables. Compilation will fail if these environment variables are not set:
DELPHIROOT or DELPHIXE
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.
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
The source code is maintained in the delphidabbler/codesnip Git respository on GitHub. Source code can be obtained in three ways:
Fork the project from GitHub and then clone your forked repository.
Clone the existing repository using:
> git clone https://github.com/delphidabbler/codesnip.git
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.
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.
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.
This section guides you through building CodeSnip from the command line, not from the IDE.
You have several options:
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.
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.
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
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.
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.
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.
Make can create zip files containing all the files that are included in a release.
Zip files are written to the _build\release directory.
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.
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.
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.
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 ..
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.
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.
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.
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.
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:
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.
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:
%ProgramData% and %AppData% sub-directories.
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.
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.