Writing Delphi Components - Creating and Installing Packages

If you want your components to have a design time presence (placed on the toolbar and be able to set parameters via the Object Inspector), then they must be placed in a package and installed in the IDE.

Though it is not documented anywhere, you need to know that packages can only be installed in the same version of Delphi that was used to compile them. (The *.dcu files are version dependent.) This means that if you share some component

either you release the source code (so it can be installed in any version)
or you compile a package in every version of Delphi (including those that are not yet released)

Of course, this brings up the question of how to make components available in C++ Builder. (Maybe I'll figure this out later.)

Installing Components - Single Directory Manual Installation Example, Debugging
Creating a Package | Creating a Package Collection
Supporting Multiple Delphi Versions | References

Installing Components

You'd think this was documented somewhere. (Actually, the help contains a significant amount of information on this. However, it is very difficult to find and to understand.)

(In the help, you can try Installing component packages. However, it does not mention the required resource file. To find this, search the help for installing components, select Compiling components into packages, and click on Installing component packages.)

To use a unit in another program, all you need is the *.dcu (Delphi Compiled Unit) file. Components are a bit more complicated - they need to be registered so that their icons will be displayed on the toolbar, and they need to execute at design time so that they can paint themselves and make appropriate property assignments.

To accomplish this, you will need at least 2 files in addition to the *.dcu files - PackageName.bpl, and PackageName.dcp. If any of the included units include a resource file (either *.res or *.dcr), then all those files will also be necessary. (See Creating a Package to generate these.)

PackageName.dpk, PackageName.dcu, and the *.pas files included in the package do not need to be distributed. (They are used to build the package, they are not needed to use it.)

Ext	Description	Comment
pas	Pascal source code	Do not need to distribute, but required to step through the code during debug
dcu	Delphi Compiled Unit	One for each pas-file. Must distribute if the exe does not call the associated bpl-file (dll-file). (Project / Options... / Packages / Build with runtime packages is disabled.) There is also a dcu-file associated with the dpk-file. This one should not be distributed.
bpl	Borland package library	Run-time dll, must distribute. Also used when Project / Options... / Packages / Build with runtime packages is enabled.
dcp	Delphi compiled package	Must distribute, used at Design-time, contains Design-time code for all the dcu-files
dpk	Delphi package	Source file that defines the package. Create via File / New... /New / Package.
pce	Package Collection Editor	The source file used to define a dpc-file.
dpc	Delphi Package Collection	This is a collection of the files needed to install one or more packages. Create this using Tools / Package Collection Editor.
hlp toc cnt	Component help file Borland Help Contents Menu MS Help Contents Menu	Provides context sensitive help for the component

When moving a package to another machine, copy

PackageName.bpl and PackageName.dcp from Machine1\Delphi5\Projects\bpl to the Machine2\Delphi5\Lib.

(These are the default directories. I actually use different directories and modify Delphi so that it can find them. See Tools / Environment Options... / Library.)

Also copy the design time resource file

PackageName.dcr to the Delphi lib directory. (If you use an *.res file, make sure that it does not contain a MAINICON and does not contain any "deleted" icons.)

Then Install the package using

Component / Install Packages (Install is also a button in the Package dialog box.) Install includes the component buttons on the component tool palette.

Notes:

The *.bpl (Borland package library) file resources can be read by the Resource Hacker.
dcl_xxx - Design time Component Library, xxx should identify you or your company
Your dcl_xxx.bpl files reference vcl50.bpl.
*.dcp and *.dcu files must be in the Delphi Library Path.
When present, an *.dpc (package collection) file contains the other files (dcp, dcu, bpl). Therefore, it is the only file needed. (Note that dpc <> dcp.)
To add your component to an existing package,
- Select File / Open... / *.dpk
- Add the appropriate source files
- Press compile

Single Directory Manual Installation Example

This assumes that you already have a package and the necessary help files. It also assumes that you want to install all the related files in a single directory (not necessarily the best approach) instead of scattering it around like Borland suggests (has some advantages).

Under C:\Program Files\Borland\Delphi5, create the directories Packages\[PackageName]
Enter the directory via Tools / Environment options... / Library / Library path
I used - $(DELPHI)\Packages\[PackageName]
Copy [PackageName].bpl and [PackageName].dcp to the new directory
Install the package via Component / Install Packages...
- Press the Add button
- Select your bpl file (the default directory is C:\Program Files\Borland\Delphi5\Projects)
- At this point, the component(s) will be visible in the tool bar and can be placed on a form ... however, the form won't compile
For each *.pas file listed in [PackageName].dpk, copy the corresponding *.dcu file to the new directory
Copy each *.dcr file listed in [PackageName].dpk to the new directory
If there are any actions, copy the associated *.dfm files to the new directory (these contain the icons)
Copy the help files (hlp, toc, cnt) to the new directory and install (link) them

Runtime Packages

In general, I prefer to build complete exe files that don't use any dll's other than those provided by Windows (and even that is pretty risky). However, if Project / Options... / Packages / Build with runtime packages is checked, then the [PackageName].bpl file is used (at run time) instead of the *.dcu files (at compile time). Since (at this point) the *.bpl file is not in the windows search path, your program will not run until you add it to the path.

You can place a copy of the *.bpl file in one of these directories

Path on my system	Extensions
C:\Program Files\Borland\Delphi5\Bin	bpl, dll
C:\Program Files\Borland\Delphi5\Projects\Bpl	its up to you
C:\Program Files\Borland\Delphi5\Projects	exe (default output directory)
Same directory as your exe	exe (custom output directory)

or you can modify your system's search path (I don't recommend this).

In one test case (just a simple form), the exe file was 15 kb using bpl's, and 356 kb using dcu's. (In another test, just a form and no components, it was 14 kb and 298 kb.)

Debugging

When developing components, be sure to have the *.dcu file in the search path

Project / Options... / Directories / Search path

In order to debug a component (set break points), the *.dcu and *.pas files should be in the same directory or at least the source file needs to be in the Debug Source Path (Project / Options... / Directories).

In order to step through vcl code, the *.dcu files are already in the search path. Therefore, you only need to include the *.pas files in Delphi5\Source\Vcl in the Debug Source Path.

It appears that there may be a small difference between machines. Today (5-2003), I had to enable the use of Debug DCUs in order to step through the VCL files - Project / Options... / Compiler / Use Debug DCUs - and Delphi5\Source\Vcl was NOT in the Debug Source Path. I don't know how I was able to step through the VCL before.

Creating a Package

To place a component on the toolbar, you need to create a package.

From the Delphi menu, select
In the package window, make sure that Contains is highlighted and click Add. Include all the applicable *.pas files.
Including *.dcu files (one of the options) seems to have no purpose - it still tries to find the *.pas files when it compiles.
Click the Options button
- On Description tab - the Description should contain a generic identifier that represents your brand and a phrase the describes the package. If this is omitted, then only the filename and path will be displayed when you look at the list of installed packages.
- On Version Info tab - CompanyName, FileDescription, FileVersion - Though these are stored in only the *.dof and *.res files, they should be entered.
Save the package via File / Save. It does not matter if you save the package before or after the files are added, either way, the hideous long path names are used ... I really prefer shorter relative path names. (Delphi 6 uses relative names.)
Press Compile to produce *.dcu files for each *.pas file and one for the package itself. It also produces the *.bpl and *.dcp files.
Use Install to add the package to the Windows registry and place the components on the toolbar.

The package definition is stored as plain text in dcl_xxx50.dpk. You can add additional components by editing and recompiling this file. (By convention, I name package files as dcl_[package_ID][Delphi_Version] - dcl - Delphi Compiled Library.)

By default, your *.bpl and *.dcp files are placed in

C:\Program Files\Borland\Delphi5\Projects\Bpl

In general, this is good because it is already in the necessary path definitions. However, I prefer to keep everything related to a project in a single directory tree. As a result, I suggest that you change

Project / Options... / Directories/Conditionals / Unit output directory	
Project / Options... / Directories/Conditionals / BPL output directory
Project / Options... / Directories/Conditionals / DCP output directory

to point elsewhere. (BPL output directory is not available in Delphi 6, but appears to be controlled via DCP output directory.) I suggest a tree something like

dcl_xxx           Readme.txt                                  How to install the package
dcl_xxx\Help      *.hlp, *.cnt, *.toc
dcl_xxx\Source    *.pas, *.dfm                                *.dfm has Action icons
dcl_xxx\Lib_50    *.dcu, *.bpl, *.dcp, *.dfm, dcl_xxx50.dpk   Version specific files
dcl_xxx\Lib_60    *.dcu, *.bpl, *.dcp, *.dfm, dcl_xxx60.dpk   Version specific files

I have also used this structure

dcl_xxx50         *.dcu, *.bpl, *.dcp, *.dfm, Readme.txt      Version specific files
dcl_xxx50\Help    *.hlp, *.cnt, *.toc
dcl_xxx50\Source  *.pas, *.dfm                                *.dfm has Action icons

This will allow you to zip the tree and distribute a smaller file.

I do not suggest using

Tools / Environment Options... / Library / BPL output directory
Tools / Environment Options... / Library / DCP output directory

to change the output directories because that will affect all projects ... and only a specific project should be assigned to a directory that is named for it.

Note: In Delphi 5, the output paths can not be set using the Delphi menu. Instead, you have to manually edit dcl_xxx50.dof (stored in ini file format).

[Directories]
OutputDir=
UnitOutputDir=..\Lib_50
PackageDLLOutputDir=..\Lib_50
PackageDCPOutputDir=..\Lib_50

I have tested this with relative paths, as shown above.

Creating a Package Collection

A package collection can contain multiple packages. A package collection contains the required *.dcu files and the optional *.pas and *.res files. It also instructs the installer where to place the files.

However, because the resulting file is over 2 Mb, and redistributes a file (vcl50.bpl) that should never (IMHO) be redistributed, I do not suggest using this. (vcl50.bpl is required for the package to install ... but it is either already on the developer's machine or the user has the wrong version of Delphi. On the other hand, vcl50.bpl is required on an end user's machine if the application is configured to "Build with runtime packages".)

To create a new collection, from the Delphi menu, select Tools / Package Collection Editor.

Identify your package collection under Author/Vendor name and add a couple of directories to the Directory list. The Directory name is what appears in the comboboxes. For example

source - C:\Program Files\BORLAND\Delphi5\Source\mcTools
dcu's  - C:\Program Files\BORLAND\Delphi5\Lib\mcTools
Help   - C:\Program Files\BORLAND\Delphi5\Help\mcTools

In the editor, select Add a package from either the menu or the toolbar. Once you've included a package, select Add a file group (it helps a lot if you name your group - it gives you something to click on later). You should probably have several groups - the *.dcu files are mandatory, but you might make the source files optional. Click the Auto... button to locate ALL the source and/or *.dcu files referenced in the package. Now go through and delete all the Delphi files. (My files were at the bottom of the list. I scrolled to the bottom and selected the first Delphi file above my files. Then, I scrolled to the top of the list, held down the shift key, and clicked the first file in the list. I simply deleted the selected files.)

Compiled     - 2,256K
Not compiled -   280K
vcl50.bpl    - 1,976K  There should be a way to not redistribute this

I tried removing vcl50.bpl from the package - then it wouldn't compile.

Supporting Multiple Delphi Versions

The DCU's made for one version of Delphi won't work in another version.

That's right - you must recompile your components for each Delphi version. (I don't remember seeing this in any of the references.)

I tried to install a component compiled in Delphi 5 into Delphi 6 ... an error said that it required vcl50.bpl. So I found that and placed it in C:\WINDOWS\system32, but it is not compatible with vcl60.bpl because they both have the same objects.

As a result, I had to re-compile the source in Delphi 6.

Because of this, I recommend that you always include a Delphi version indicator in the package filename.

This is copied from the Delphi 5 help (from Deploying packages)

Distributing packages to other developers

If you distribute runtime or design-time packages to other Delphi developers, be sure to supply both .DCP and .BPL files. You will probably want to include .DCU files as well.

Notice that it does not say that packages will only work with the same version of Delphi that they are compiled on.

BTW, Delphi 5 packages require vcl50.bpl, but Delphi 6 packages require rtl.dcp and sometimes vcl.dcp. When a Delphi 5 package is automatically "converted" to Delphi 6, only vcl.dcp is required. (go figure) The following excerpts are from various *.dpk files

Delphi 5 - dcl_mc50.dpk

  requires
    vcl50;

Delphi 6 after a conversion from Delphi 5

  requires
    vcl;

Delphi 6 - new package file

  requires
    rtl,
    vcl;

References

Teach Yourself Borland Delphi 4 in 21 Days, good reference.
Creating Components is very good.
Custom Component Development
DelphiByDesign
Introduction to Component Building by Ray Konopka
Developing Custom Delphi Components

Author: Robert Clemenzi - clemenzi@cpcug.org