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

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.)

When moving a package to another machine, copy

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

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

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

Notes:


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).


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

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

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. 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

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 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

I have also used this structure

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

I do not suggest using

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).

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

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.)

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)

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


References


Author: Robert Clemenzi - clemenzi@cpcug.org
URL: http:// cpcug.org / user / clemenzi / technical / Languages / Delphi / Packages.html