<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!--
* Build.html
*
* Instructions for building CodeSnip.
*
* $Rev$
* $Date$
*
* ***** BEGIN LICENSE BLOCK *****
*
* Version: MPL 1.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with the
* License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
* the specific language governing rights and limitations under the License.
*
* The Original Code is Build.html
*
* The Initial Developer of the Original Code is Peter Johnson
* (http://www.delphidabbler.com/).
*
* Portions created by the Initial Developer are Copyright (C) 2009 Peter
* Johnson. All Rights Reserved.
*
* Contributors:
* NONE
*
* ***** END LICENSE BLOCK *****
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<html>
<head>
<title>
Building CodeSnip
</title>
<style>
body {
font-family: sans-serif;
}
dt.spaced {
margin-top: 0.5em;
}
h1 {
text-align: center;
}
h2 {
padding-bottom: 0.25em;
border-bottom: 1px silver solid;
}
.indent {
margin-left: 2em;
}
ul.spaced li,
ol.spaced li {
margin-top: 0.5em;
}
</style>
</head>
<body>
<h1>
CodeSnip Build Instructions
</h1>
<h2>
Introduction
</h2>
<p>
<em>CodeSnip</em> 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.
</p>
<p>
These notes apply only to source code of releases 3.1.0 of <em>CodeSnip</em>
and later. For any earlier version please see the file named
<code>ReadMe-Src.txt</code> that will be in either the root directory or the
<code>Docs</code> sub-directory.
</p>
<h2>
Dependencies
</h2>
<p>
Several libraries and components are required in to compile
<em>CodeSnip</em>:
</p>
<dl>
<dt class="spaced">
Version Information Component by DelphiDabbler
</dt>
<dd>
Used to access the program's version information resources. The code is
available from
<a
href="http://www.delphidabbler.com/software/verinfo"
>http://www.delphidabbler.com/software/verinfo</a>. v3.1.1 or later is
required.
</dd>
<dt class="spaced">
System Information Unit by DelphiDabbler
</dt>
<dd>
Provides various pieces of information about the computer system and
operating system. The unit is available from
<a
href="http://www.delphidabbler.com/software/sysinfo"
>http://www.delphidabbler.com/software/sysinfo</a>. v3.1 or later is
required.
</dd>
<dt class="spaced">
Window State Components by DelphiDabbler
</dt>
<dd>
Used to maintain and restore the state of the program window. The code
is available from
<a
href="http://www.delphidabbler.com/software/wdwstate"
>http://www.delphidabbler.com/software/wdwstate</a>. v5.3 or later is
required.
</dd>
<dt class="spaced">
Stream Extension Classes by DelphiDabbler
</dt>
<dd>
Used in manipulating <em>TStream</em>s. The classes are available from
<a
href="http://www.delphidabbler.com/software/streams"
>http://www.delphidabbler.com/software/streams</a>. v2.0.1 or later is
required.
</dd>
<dt class="spaced">
Indy Internet Components
</dt>
<dd>
These components are supplied with Delphi 2006. Note that v9 is
required. You need to configure Delphi 2006 to use Indy v9 rather than
Indy v10. If you haven't got Indy 9 you can download it from
<a
href="http://www.indyproject.org"
>http://www.indyproject.org</a>.
</dd>
</dl>
<p>
Other necessary third party code is included in the <em>CodeSnip</em>
repository.
</p>
<h3>
DelphiDabbler libraries
</h3>
<p>
You should download the DelphiDabbler code libraries and install them all
together into a package or at least ensure that the compiled
<code>.dcu</code> files are all in the same folder. It's easiest to use the
Delphi IDE to do this.
</p>
<p>
Set the <code>DELPHIDABLIB</code> enironment variable to the folder where
you placed the compiled library code.
</p>
<h3>
Indy libraries
</h3>
<p>
If you download a copy of Indy you should compile the source code and create
the necessary package(s).
</p>
<p>
Regardless of whether you're using the version of Indy 9 supplied with
Delphi or if you've downloaded and compiled your own version, you should set
the <code>INDY9</code> environment variable to the folder where you placed
the compiled code.
</p>
<h3>
Delphi VCL
</h3>
<p>
Goes without saying really, but you need the Delphi VCL in order to compile
this code.
</p>
<h2>
Build Tools
</h2>
<p>
The following tools are required to build <em>CodeSnip</em>.
</p>
<h3>
Delphi
</h3>
<p>
A copy of Delphi is required to build the object Pascal code. Delphi 2006
is preferred.
Delphi 2007 and 2008 should be able to compile the source. Delphi 2009 and
later may work, but the code hasn't been written with Delphi 2009's Unicode
support in mind, so there may be problems.
Delphis earlier than 2006 can't be used. The code depends on language
features introduced in Delphi 2006.
</p>
<p>
You can use the Delphi IDE to edit the code and test compile it. The
makefile requires the following command line tools:
</p>
<dl>
<dt class="spaced">
<code>DCC32</code>
</dt>
<dd>
The Delphi command line compiler.
</dd>
<dt class="spaced">
<code>BRCC32</code>
</dt>
<dd>
The Borland resource compiler. Used to compile various resource source
(<code>.rc</code>) files.
</dd>
<dt class="spaced">
<code>TLibImpl</code>
</dt>
<dd>
Type library importer tool. Used to create a Pascal unit that describes
code contained in <code>ExternalObj.idl</code>.
</dd>
</dl>
<p>
The following environment variables are associated with these tools:
</p>
<dl>
<dt class="spaced">
<code>DELPHIROOT</code>
- required unless <code>DELPHI2006</code> is
set.
</dt>
<dd>
Should be set to the install directory of the version of Delphi being
used. <code>DCC32</code>, <code>BRCC32</code> and <code>TLibImpl</code>
are expected to be in the <code>Bin</code> sub-directory of
<code>DELPHIROOT</code>.
</dd>
<dt class="spaced">
<code>DELPHI2006</code> - optional
</dt>
<dd>
If you are using Delphi 2006 this environment variable should be set
to the Delphi install directory. When specified <code>DELPHIROOT</code>
will ignore its own value and use the value of <code>DELPHI2006</code>
instead.
</dd>
<dt class="spaced">
<code>DELPHIDABLIB</code>
- required unless <code>DELPHIDABLIB2006</code> is set.
</dt>
<dd>
Should be set to the directory where the compiler can find the required
DelphiDabbler library compiled units. The code in this directory must
have been compiled with the same version of Delphi used to compile
<em>CodeSnip</em>.
</dd>
<dt class="spaced">
<code>DELPHIDABLIB2006</code> - optional
</dt>
<dd>
If you are using Delphi 2006 this enviroment variable may be set to
the install directory of the library code described above. When set the
value of this variable is used by <code>DELPHIDABLIB</code> regardless
of its own value.
</dd>
<dt class="spaced">
<code>INDY9</code> - required
</dt>
<dd>
Must be set to the directory where the Indy 9 components are installed.
The code must have been built with the same version of Delphi used to
compile <em>CodeSnip</em>.
</dd>
</dl>
<h3>
Borland MAKE
</h3>
<p>
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.
</p>
<h3>
Microsoft Software Development Kit
</h3>
<p>
The MS SDK is required for its MIDL IDL compiler. This tool is needed to
build <code>ExternalObj.idl</code> into a <code>.tlb</code> file.
</p>
<p>
MIDL requires the use of Microsoft's <code>CL.exe</code> C Pre-processor
which in turn requires <code>mspdb**.dll</code>, 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:
</p>
<ul class="spaced">
<li>
The path to <code>CL.exe</code>. This will probably be in a sub folder
of a MS Visual Studio installation folder. For example
<code>C:\Program Files\Microsoft Visual Studio 9.0\VC\bin</code>
</li>
<li>
The Common Visual studio binary directory where <code>mspdb**.dll</code>
is located. For example:
<code>C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE</code>.
</li>
</ul>
<p>
The <code>MSSDK</code> environment variable must be set and contain the
MS SDK install directory. <code>MIDL.exe</code> must be in the
<code>Bin</code> sub-directory of <code>MSSDK</code> and the required
include files must be in the <code>Include</code> sub-directory.
</p>
<p>
You can use a batch file with contents similar this to set the path and the
<code>MSSDK</code> environment variable before building <em>CodeSnip</em>:
</p>
<pre class="indent">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</pre>
<h4>
Build Without MIDL or the MS SDK
</h4>
<p>
If you don't already have the MS SDK it's a big job to download and install
it just to compile one <code>.tlb</code> file. (The SDK is huge).
Therefore there's an alternative that means you can compile without the SDK.
This is decribed in the section
<a
href="#nomidl"
>Editing and Compiling Without MIDL</a> below.
</p>
<p>
If you take this route, there's no need to set <code>MSSDK</code> or modify
the path.
</p>
<h3>
DelphiDabbler Version Information Editor (VIEd)
</h3>
<p>
This tool is used to compile version information (<code>.vi</code>) files
into intermediate resource source (<code>.rc</code>) files. Version 2.11.2
or later is required.
Version Information Editor can be obtained from
<a
href="http://www.delphidabbler.com/software/vied"
>http://www.delphidabbler.com/software/vied</a>.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>VIEDROOT</code> environment variable.
</p>
<h3>
DelphiDabbler HTML Resource Compiler (HTMLRes)
</h3>
<p>
HTMLRes is used to compile <code>HTML.hrc</code> 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
<a
href="http://www.delphidabbler.com/software/htmlres"
>http://www.delphidabbler.com/software/htmlres</a>.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>HTMLRESROOT</code> environment variable.
</p>
<h3>
Inno Setup
</h3>
<p>
The Inno setup command line compiler is used to create <em>CodeSnip</em>'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 <a
href="http://www.innosetup.com/"
>http://www.innosetup.com/</a>.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>INNOSETUP</code> environment variable.
</p>
<h3>
Microsoft HTML Help Compiler (HHC)
</h3>
<p>
This command line compiler is supplied with Microsoft HTML Help Workshop. It
is used to compile the <em>CodeSnip</em> help file.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>HHCROOT</code> environment variable.
</p>
<h3>
Zip
</h3>
<p>
This program is used to create <em>CodeSnip</em>'s release file.
You can get a Windows command line version at
<a
href="http://stahlforce.com/dev/index.php?tool=zipunzip"
>http://stahlforce.com/dev/index.php?tool=zipunzip</a>.
</p>
<p>
The program is expected to be on the path unless its install directory is
specified by the <code>ZIPROOT</code> environment variable.
</p>
<h2>
Preparation
</h2>
<h3>
Configure the environment.
</h3>
<p>
The first step is to configure the required environment variables.
</p>
<ul>
<li>
<code>DELPHIROOT</code> or <code>DELPHI2006ROOT</code>
</li>
<li>
<code>DELPHIDABLIB</code> or <code>DELPHIDABLIB2006</code>
</li>
<li>
<code>INDY9</code>
</li>
<li>
<code>MSSDK</code>
</li>
</ul>
<p>
Update the <code>PATH</code> environment variable to include the paths that
MIDL needs (explained above) along with any other paths needed to access
build tools.
</p>
<p>
If you are not using MIDL then there is no need to modify the
<code>PATH</code> variable or set <code>MSSDK</code>. Instead you can
define <code>IGNOREMIDL</code> by setting it to some value, e.g.
<code>set IGNOREMIDL=1</code>.
</p>
<p>
Set any of the optional environment variables that are needed to specify the
path to any tools that are not on the system path.
</p>
<p>
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.
</p>
<h3>
Get the Source Code
</h3>
<p>
If you don't already have it, download the <em>CodeSnip</em> source code.
How to go about that is explained at
<a
href="http://www.delphidabbler.com/software/codesnip/download"
>http://www.delphidabbler.com/software/codesnip/download</a>. If necessary,
extract the source code into a folder, preserving the directory structure.
</p>
<h3>
Configure the Source Tree
</h3>
<p>
After checking out or downloading and extracting the source code you should
have the following directory structure:
</p>
<pre>./
|
+-- 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</pre>
<p>
If, by chance you also have a <code>Bin</code>, <code>Exe</code> and
<code>Release</code> directory don't worry - all will become clear.
Subversion users will also see the usual <code>.svn</code> hidden
directories. If you have done some editing you may also see occasional
hidden <code>__history</code> folders.
</p>
<p>
Before you can get hacking, you need to prepare the code tree. Open a
command console and navigate into the <code>Src</code> sub-folder. Run any
script you have created to set the required environment variables then do:
</p>
<pre class="indent">> Make config</pre>
<p>
You may need to replace <code>Make</code> with the full path to
<code>Make</code> if it isn't on the path, or if the <code>Make</code> that
runs isn't the Borland / CodeGear version. If this is the case try:
</p>
<pre class="indent">> %DELPHIROOT%\Bin\Make config</pre>
<p>
or
</p>
<pre class="indent">> %DELPHI2006%\Bin\Make config</pre>
<p>
depending on which environment variable you have set.
</p>
<p>
Once <code>Make config</code> has completed your folder structure should
have acquired the following new folders:
</p>
<pre>./
|
+-- Bin - receives object files for CodeSnip
| |
| +-- InstallHelper - receives object files for CSSetupHelper
...
|
+-- Exe - receives executable code and compiled help file
|
+-- Release - receives release files
|
...</pre>
<p>
If the <code>Bin</code>, <code>Exe</code> and <code>Release</code> folders
already existed they will have been emptied.
In addition, <code>Make</code> will have created <code>.cfg</code> and
<code>.bdsproj</code> files from templates in the <code>Src</code> and
<code>Src\InstallHelper</code> folders.
<code>.cfg</code> files are needed for DCC32 to run correctly and
<code>.bdsproj</code> files enable the use of the Delphi IDE. These files
will be ignored by Subversion.
</p>
<p>
If you are intending to use the Delphi IDE to compile code, you should also
do:
</p>
<pre class="indent">> Make resources
> Make typelib
> Make autogen</pre>
<p>
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.
</p>
<p>
You are now ready to modify the code if required and to build the source.
</p>
<h3 id="nomidl">
Editing and Compiling without MIDL
</h3>
<p>
If you don't have the MIDL compiler you need to get hold of a pre-compiled
copy of the <code>ExternalObj.tlb</code> type library and tell Make to skip
the MIDL compiling stage.
</p>
<h4>
Getting The Type Library
</h4>
<ol class="spaced">
<li>
If necessary download a resource file editor. XN Resource Editor will
do the job. You can get that from
<a
href="http://www.wilsonc.demon.co.uk/d10resourceeditor.htm"
>http://www.wilsonc.demon.co.uk/d10resourceeditor.htm</a>.
</li>
<li>
Get a suitable copy of the <em>CodeSnip</em> executable. This must have
been compiled from the same version of <code>ExternalObj.idl</code> as
that included in the source tree. (Use File | Open in XN Resource
Editor).
</li>
<li>
Open <code>CodeSnip.exe</code> 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
<code>ExternalObj.tlb</code> in the <code>Bin</code> folder in your
configured source tree. (Use Resource | Export Resource in XN Resource
Editor).
</li>
</ol>
<p>
If you are working on the latest development tree from the code repository
you should get <code>ExternalObj.tlb</code> from the latest release of
<em>CodeSnip</em>, <strong>unless</strong> <code>ExternalObj.idl</code>
has been changed since the last release. In this case when you must use MIDL
to build the <code>.idl</code> file, because a suitable <code>.tlb</code>
file won't be available.
</p>
<h4>
Editing the Type Library
</h4>
<p>
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
<code>ExternalObj.tlb</code>. This opens the type library. Edit as required
then save the changes. Delete any <code>*_TLB</code> files that appear.
</p>
<p>
If you do make changes you should also use the type library editor's
<em>Export to IDL</em> button to save a copy of the IDL in
<code>ExternalObj.idl</code> in the <code>Src</code> 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 <code>ExternalObj.idl</code>
before saving!
</p>
<p>
You must regenerate the associated Pascal file. Do this by running:
</p>
<pre class="indent">> Make autogen</pre>
<h4>
Telling Make to Ignore MIDL
</h4>
<p>
You now need to prevent Make from trying to compile the <code>.idl</code>
file in the absence of MIDL. Do this by defining an environment variable
called <code>IGNOREMIDL</code>. This can be done from the command line or
a batch file by doing:
</p>
<pre class="indent">
> set IGNOREMIDL=1</pre>
<p>
Alternatively, always call Make with the <code>-DIGNOREMIDL</code> switch.
</p>
<h2>
Building CodeSnip
</h2>
<p>
You have several options:
</p>
<ul>
<li>
Build the <em>CodeSnip</em> Executable
</li>
<li>
Build the Help File.
</li>
<li>
Build the Setup Program.
</li>
<li>
Build the Release Zip File.
</li>
<li>
Build and Release Everything.
</li>
<li>
Clean Up.
</li>
</ul>
<p>
Each of these options is described below. All except the last assume that
<code>Make config</code> has been run.
</p>
<h3>
Build the CodeSnip Executable
</h3>
<p>
This is the most common build and has a simple command:
</p>
<pre class="indent">> Make codesnip</pre>
<p>
This is the same as doing this sequence of commands:
</p>
<pre class="indent">> Make typelib
> Make resources
> Make autogen
> Make pascal</pre>
<p>
The <em>CodeSnip</em> executable will be placed in the <code>Exe</code>
folder.
</p>
<p>
If you are building without MIDL, and have a suitable copy of
<code>ExternalObj.tlb</code> already in the <code>Bin</code> directory you
must either have defined the <code>IGNOREMIDL</code> environment variable or
you must do:
</p>
<pre class="indent">> Make -DIGNOREMIDL codesnip</pre>
<p>
This is the same as doing:
</p>
<pre class="indent">> Make -DIGNOREMIDL typelib
> Make resources
> Make autogen
> Make pascal</pre>
<h3>
Build the Help File
</h3>
<p>
To build the help file just do
</p>
<pre class="indent">> Make help</pre>
<h3>
Build the Setup Program
</h3>
<p>
The setup program requires that the <em>CodeSnip</em> and the compiled help
file are present in the <code>Exe</code> directory.
<code>CSInstallHelper.exe</code> must also be present in the same folder.
</p>
<p>
We've already shown how to build <em>CodeSnip</em> and the help file.
<code>CSInstallHelper.exe</code> is built by doing:
</p>
<pre class="indent">> Make installhelper</pre>
<p>
As an aside, you can make all the required files by doing:
</p>
<pre class="indent">> Make exes</pre>
<p>
<code>Make exes</code> will require the use of the <code>-DIGNOREMIDL</code>
switch if MIDL is not available.
</p>
<p>
Once you have built all the required files you build the setup file by
doing:
</p>
<pre class="indent">> Make setup</pre>
<p>
The setup program is named <code>CodeSnip-Setup-x.x.x.exe</code>, where
x.x.x is the version number extracted from <em>CodeSnip</em>'s version
information. It is placed in the <code>Exe</code> directory.
</p>
<h3>
Build the Release Zip File
</h3>
<p>
Once the setup file has been created you can create a zip file containing
the setup file along with <code>ReadMe.txt</code> from the <code>Docs</code>
directory. If either file is missing the release fails. Build the release by
doing:
</p>
<pre class="indent">> Make release</pre>
<p>
By default the release file is called <code>dd-codesnip.zip</code>. You can
change this name by defining the <code>RELEASEFILENAME</code> macro or
enviroment variable. For example, you can name the file
<code>MyRelease.zip</code> by doing:
</p>
<pre class="indent">> Make -DRELEASEFILENAME=MyRelease.zip release</pre>
<h3>
Build and Release Everything
</h3>
<p>
You can do a clean build of everything, and generate the release zip file
simply by doing:
</p>
<pre class="indent">> Make</pre>
<p>
without specifying a target. This is the equivalent of:
</p>
<pre class="indent">> Make config
> Make exes
> Make setup
> Make release</pre>
<p>
<strong>Warning:</strong> You should not run this command if MIDL is not
available since <code>Make config</code> will delete any <code>.tlb</code>
file you have placed manually in the <code>Bin</code> directory.
</p>
<h3>
Clean Up
</h3>
<p>
Various temporary files and directories are created by the IDE. These can be
deleted by running.
</p>
<pre class="indent">> Make clean</pre>
<p>
Be warned though that this command removes the <code>__history</code>
folders that Delphi uses to maintain earlier versions of files.
</p>
<h2>
Copyright
</h2>
<p>
If you are planning to re-use or modify any of the code, please see the file
<code>SourceCodeLicenses.txt</code> in the <code>Docs</code> directory for
an overview of the various open source licenses that apply to the
<em>CodeSnip</em> source code.
</p>
</body>
</html>
