CodeSnip is written in Object Pascal and is targeted at Delphi XE. Compilation with earlier compilers is not guaranteed. The code will require some changes to compile on Delphi XE2 or later.
The are currently two editions of CodeSnip: the standard edition and the portable edition. They both share the same code base and the different editions are created using conditional compilation. These instructions show how to build either edition.
The Delphi XE IDE can be used to modify the source and to perform test builds. Final builds should be created using the provided makefile.
Several DelphiDabbler and other 3rd party libraries and components are
required to compile CodeSnip, most of which are included in the code
repository in the Src/3rdParty directory. Code not included in
the repository is noted below.
The Indy 10 Internet components ship with Delphi XE. If you prefer to work with the latest release you can download it from http://www.indyproject.org/. If you download a copy of Indy 10 you should compile the source code separately with the same version of Delphi that is being used to compile CodeSnip.
Regardless of whether you are using the version of Indy 10 supplied with
Delphi or if you have downloaded and compiled your own version, you must set
the INDY10 environment variable to the directory where you
placed the compiled code.
Changes were made to the parameter lists of the TWorkBeginEvent and TWorkEvent events between early and later releases of Indy 10. Specifically, earlier versions use type Integer for the AWorkCount parameter of TWorkEvent and the AWorkCountMax parameter of TWorkBeginEvent, while later versions use Int64.
CodeSnip's source code uses conditional compilation to provide the
correct event handler signatures – and it makes an intelligent guess
at which signature to use depending on the version number provided by the
Indy library code. Should the program fail to compile with an error in the
Web.UDownloadMonitor unit, you should check the event signatures in
your Indy IdComponent unit and then define the
INDY_WORKEVENT_INT64 environment variable if Int64
parameters are required or INDY_WORKEVENT_INT32 if
Integer parameters are used.
Goes without saying really, but you need the RTL and VCL that ships with Delphi.
The following tools are required to build CodeSnip.
A copy of the Delphi XE command line compiler is required to build the object Pascal code from the provided makefile.
You can use the Delphi IDE to edit the code and test compile it, but final builds should be created using the makefile, which requires the following tools that are supplied with Delphi:
DCC32
BRCC32
.rc) files.
GenTLB
ExternalObj.tlb type
library from source code in ExternalObj.ridl.
TLibImpl
ExternalObj.idl.
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.
INDY10 - required
INDY_WORKEVENT_INT64 or
INDY_WORKEVENT_INT32 - optional
This is the make tool that ships with Delphi. You can use any version that works.
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
http://www.delphidabbler.com/software/vied.
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 stores various
HTML, JavaScript, CSS and images into HTML resources. Version 1.1 or later
is required.
The HTML Resource Compiler can be obtained from
http://www.delphidabbler.com/software/htmlres.
The program is expected to be on the path unless its install directory is
specified by the HTMLRESROOT environment variable.
The Unicode version on the Inno setup command line compiler is needed to create CodeSnip's install program. v5.5.2 (u) or later is required. Earlier (Unicode) versions may work, but this is not guaranteed.
You can get Inno Setup at http://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. 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.
Note: 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
INDY10
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 the preferred version of
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
Set INDY_WORKEVENT_INT64 or INDY_WORKEVENT_INT32
if necessary (explained above).
If you don't already have it, download or checkout the CodeSnip source code. There are several options:
> svn checkout https://svn.code.sf.net/p/codesnip/code/trunk PATH
> svn checkout svn://svn.code.sf.net/p/codesnip/code/trunk PATH
PATH is the directory where you want to place the
working copy. You will not be able to commit changes unless you join
the project, when a different check out URL is used.
> svn export https://svn.code.sf.net/p/codesnip/code/trunk PATH
> svn export svn://svn.code.sf.net/p/codesnip/code/trunk PATH
PATH is the directory where you wish to store the
code.
trunk with tags/XXXX
where XXX specifies the version.
After checking out or downloading and extracting the source code you should have the following directory structure:
./
|
+-- Docs - documentation
| |
| +-- ChangeLogs - program change log files
| |
| +-- 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
| | |
| | +-- Branding - image files used for CodeSnip branding
| | |
| | +-- 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 Bin, Exe and / or
Release directories don't worry - all will become clear.
Subversion users may also see the usual .svn hidden
directories. 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 and navigate into the Src sub-folder. Run any script you
have created to set environment variables then do:
> 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 CodeGear / Embarcadero version. 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 completed your folder structure should
have acquired the following new folders, if they weren't present already:
./ | +-- Bin - receives object files for CodeSnip | ... | +-- Exe - receives executable code and compiled help file | +-- Release - receives release files | ...
If the Bin folder already existed, it will have been emptied.
In addition, Make will have created a .cfg file from
template in the Src folder. This .cfg file is needed
for DCC32 to run correctly. The file will be ignored by Subversion.
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.
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 the last 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 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 Exe folder, but this time
it is named CodeSnip-p.exe
To build the help file just do
> Make help
The setup program requires that the CodeSnip excutable and the
compiled help file are already present in the 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 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 the files that are included in a release.
The release file for the standard edition of CodeSnip includes the
setup file along with ReadMe.txt from the Docs
directory. Both must be present.
Build the release by doing:
> Make release
By default the release file is named dd-codesnip.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.zip release
The release file for the portable edition includes the portable executable
file, CodeSnip-p.exe, the help file CodeSnip.chm and
several files from the Docs directory. All must be present.
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.zip release
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.
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
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 maintain 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.