CodeSnip is written in Object Pascal and is targeted at Delphi 2006. The Delphi IDE can be used to modify the source and to perform test builds. Final builds should be built using the provided makefile, but you can get away with using the IDE if you don't change any resources.
Several libraries and components are required in to compile CodeSnip:
Other necessary third party code is included in the CodeSnip repository.
You should download the DelphiDabbler code libraries and install them all
together into a package or at least ensure that the compiled
.dcu files are all in the same folder. It's easiest to use the
Delphi IDE to do this.
Set the DELPHIDABLIB enironment variable to the folder where
you placed the compiled library code.
If you download a copy of Indy 10 you should compile the source code and create the necessary package(s).
Regardless of whether you're using the version of Indy 10 supplied with
Delphi or if you've downloaded and compiled your own version, you should set
the INDY10 environment variable to the folder where you placed
the compiled code.
Goes without saying really, but you need the Delphi VCL in order to compile this code.
The following tools are required to build CodeSnip.
A copy of Delphi is required to build the object Pascal code. Delphi 2006 is the preferred, and minimum, compiler.
Delphi 2007 should be able to compile the source. I've been told that the code will not compile on Delphi 2009, and I assume that applies to Delphi 2010 also. Note: Support for the "Unicode Delphis" is planned and when complete the targetted compiler will change to Delphi 2010.
You can use the Delphi IDE to edit the code and test compile it. The makefile requires the following command line tools:
DCC32
BRCC32
.rc) files.
TLibImpl
ExternalObj.idl.
The following environment variables are associated with these tools:
DELPHIROOT
- required unless DELPHI2006 is
set.
DCC32, BRCC32 and TLibImpl
are expected to be in the Bin sub-directory of
DELPHIROOT.
DELPHI2006 - optional
DELPHIROOT
will ignore its own value and use the value of DELPHI2006
instead.
DELPHIDABLIB
- required unless DELPHIDABLIB2006 is set.
DELPHIDABLIB2006 - optional
DELPHIDABLIB regardless
of its own value.
INDY10 - required
This is the make tool that ships with Delphi. You can use any version that works. I've tested the version that ships with Delphi 2006.
The MS SDK is required for its MIDL IDL compiler. This tool is needed to
build ExternalObj.idl into a .tlb file.
MIDL requires the use of Microsoft's CL.exe C Pre-processor
which in turn requires mspdb**.dll, where ** is a number that
depend version of Visual Studio used. I use MIDL v7 and mspdb80.dll from the
Windows 2008 (v6.1) platform SDK. So that MIDL can find these files you
need to update your system PATH to include:
CL.exe. This will probably be in a sub folder
of a MS Visual Studio installation folder. For example
C:\Program Files\Microsoft Visual Studio 9.0\VC\bin
mspdb**.dll
is located. For example:
C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE.
The MSSDK environment variable must be set and contain the
MS SDK install directory. MIDL.exe must be in the
Bin sub-directory of MSSDK and the required
include files must be in the Include sub-directory.
You can use a batch file with contents similar this to set the path and the
MSSDK environment variable before building CodeSnip:
if not "%PATHSET%" == "" goto end set MSSDK=C:\Program Files\Microsoft SDKs\Windows\v6.1 set PATH=%PATH%;C:\Program Files\Microsoft Visual Studio 9.0\VC\bin set PATH=%PATH%;C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE set PATHSET=1 :end
If you don't already have the MS SDK it's a big job to download and install
it just to compile one .tlb file. (The SDK is huge).
Therefore there's an alternative that means you can compile without the SDK.
This is decribed in the section
Editing and Compiling Without MIDL below.
If you take this route, there's no need to set MSSDK or modify
the path.
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 Inno setup command line compiler is used to create CodeSnip's install program. The compiler is supplied with Inno Setup v5.2.3 or later. The ISPP pre-processor v5.2.3 or later is also required. You can get Inno Setup at http://www.innosetup.com/.
The program is expected to be on the path unless its install directory is
specified by the INNOSETUP environment variable.
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.
The first step is to configure the required environment variables.
DELPHIROOT or DELPHI2006ROOT
DELPHIDABLIB or DELPHIDABLIB2006
INDY10
MSSDK
Update the PATH environment variable to include the paths that
MIDL needs (explained above) along with any other paths needed to access
build tools.
If you are not using MIDL then there is no need to modify the
PATH variable or set MSSDK. Instead you can
define IGNOREMIDL by setting it to some value, e.g.
set IGNOREMIDL=1.
Set any of the optional 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.
If you don't already have it, download the CodeSnip source code. How to go about that is explained at http://www.delphidabbler.com/software/codesnip/download. If necessary, extract the source code into a folder, preserving the directory structure.
After checking out or downloading and extracting the source code you should have the following directory structure:
./
|
+-- Docs - documentation
| |
| +-- Design - documents concerning design
| |
| +-- Updates - notes about program updates
| |
| +-- Archive - historical update notes: pre svn
|
+-- Src - main CodeSnip source code
|
+-- 3rdParty - third party source
|
+-- AutoGen - 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
|
+-- InstallHelper - source for install helper program
| |
| +-- Res - resources for install helper program
|
+-- Res - container for various types of resources
|
+-- HTML - html, css, js and images included in resources
|
+-- Img - images included in resources
|
+-- Misc - other resources
If, by chance you also have a Bin, Exe and
Release directory don't worry - all will become clear.
Subversion users will also see the usual .svn hidden
directories. If you have done some editing 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 the required 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 Borland / CodeGear version. If this is the case try:
> %DELPHIROOT%\Bin\Make config
or
> %DELPHI2006%\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:
./ | +-- Bin - receives object files for CodeSnip | | | +-- InstallHelper - receives object files for CSSetupHelper ... | +-- Exe - receives executable code and compiled help file | +-- Release - receives release files | ...
If the Bin, Exe and Release folders
already existed they will have been emptied.
In addition, Make will have created .cfg and
.bdsproj files from templates in the Src and
Src\InstallHelper folders.
.cfg files are needed for DCC32 to run correctly and
.bdsproj files enable the use of the Delphi IDE. These files
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.
You are now ready to modify the code if required and to build the source.
If you don't have the MIDL compiler you need to get hold of a pre-compiled
copy of the ExternalObj.tlb type library and tell Make to skip
the MIDL compiling stage.
ExternalObj.idl as
that included in the source tree. (Use File | Open in XN Resource
Editor).
CodeSnip.exe in the resource file editor. You need to
find the TYPELIB resource type. There should only be one, language
neutral, TYPELIB resource. Select this and export it as
ExternalObj.tlb in the Bin folder in your
configured source tree. (Use Resource | Export Resource in XN Resource
Editor).
If you are working on the latest development tree from the code repository
you should get ExternalObj.tlb from the latest release of
CodeSnip, unless ExternalObj.idl
has been changed since the last release. In this case when you must use MIDL
to build the .idl file, because a suitable .tlb
file won't be available.
You can edit the type library from the Delphi IDE. Start the IDE select
File | Open, change the file type to Type Library and navigate to
ExternalObj.tlb. This opens the type library. Edit as required
then save the changes. Delete any *_TLB files that appear.
If you do make changes you should also use the type library editor's
Export to IDL button to save a copy of the IDL in
ExternalObj.idl in the Src folder. The license in
the original code must be restored and you can add yourself as a
contributor, so take a copy of the license from ExternalObj.idl
before saving!
You must regenerate the associated Pascal file. Do this by running:
> Make autogen
You now need to prevent Make from trying to compile the .idl
file in the absence of MIDL. Do this by defining an environment variable
called IGNOREMIDL. This can be done from the command line or
a batch file by doing:
> set IGNOREMIDL=1
Alternatively, call Make with the -DIGNOREMIDL switch.
You have several options:
Each of these options is described below. All except the last assume that
Make config has been run.
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 will be placed in the Exe
folder.
If you are building without MIDL, and have a suitable copy of
ExternalObj.tlb already in the Bin directory you
must either have defined the IGNOREMIDL environment variable or
you must do:
> Make -DIGNOREMIDL codesnip
This is the same as doing:
> Make -DIGNOREMIDL typelib > Make resources > Make autogen > Make pascal
To build the help file just do
> Make help
The setup program requires that the CodeSnip and the compiled help
file are present in the Exe directory.
CSInstallHelper.exe must also be present in the same folder.
We've already shown how to build CodeSnip and the help file.
CSInstallHelper.exe is built by doing:
> Make installhelper
As an aside, you can make all the required files by doing:
> Make exes
Make exes will require the use of the -DIGNOREMIDL
switch if MIDL is not available.
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.
Once the setup file has been created you can create a zip file containing
the setup file along with ReadMe.txt from the Docs
directory. If either file is missing the release fails. Build the release by
doing:
> Make release
By default the release file is called 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
You can do a clean 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
Warning: You should not run this command if MIDL is not
available since Make config will delete any .tlb
file you have placed manually in the Bin directory.
Various temporary files and directories are created by the IDE. These can be deleted by running.
> Make clean
Be warned though that this command removes the __history
folders that Delphi uses to maintain earlier versions of files.
If you are planning to re-use or modify any of the code, please see the file
SourceCodeLicenses.txt in the Docs directory for
an overview of the various open source licenses that apply to the
CodeSnip source code.