Created by: gwideman, Jan 14, 2012 5:16 am
Revised by: gwideman, Feb 1, 2012 6:26 am (33 revisions)

[Work in progress]
Doc and notes on Delphi packages: the files involved and their roles in the process of creating component libraries and applications which use them.

Overview of files and processes involved in creating and using packages

The following table shows files involved in creating packages and using them in an application (at least my current understanding).
Variants show alternatives for how the application links to the library:
  • Application linked statically to the library's constituent files (dcus)
  • Application linked dynamically to a runtime package.
  • So far as I can tell, there isn't a way to "link statically to the compiled package".
Variants show alternative for how the design-time package incorporates the library's constituent files:
  • The design-time library (bpl) can be linked statically to the library's constituent files, thus including all their code in the bpl.
  • The design-time library can link dynamically to the runtime library bpl, so requiring the IDE to load both the design-time and runtime bpl.
Read across to see which files are used to create which other files, and read down to see where each file is later used.
(To isolate the image for printing, right-click > View image, or similar)

Open questions

The chart shows some question marks. These generally revolve around where exactly a library's dcp file is needed or used. Here are the uncertain cases.
  • Application using runtime libraries:
    • I am convinced that the linker needs the dcp file to know how to create calls from the application to the bpl.
    • Does the compiler or linker also need the dcus? Supposedly the dcp contains all the dcu interface information, so the dcus should be superfluous.
  • IDE loading a design-time package (so as to include components on the palette).
    • I am unsure whether the IDE needs the .dcp file for the design-time library, because I would think that the IDE could find out all it needs from the bpl itself using RTTI. However, that may not be the case.

Paths to files used in packages, and projects which use them

Below is a table summarizing the directory locations and path settings involved, as I currently understand it.
This table duplicates the previous one's use of color to signify in/out/execute, and adds an indication of how the location of each kind of file is established, and how files of that role are later found. Again, read across to see which files are used to create which other files, and read down to see where each file is later used.
Of some interest are the cases where a file is found by a path setting that is different from the setting used to create the file -- these are cases where an aberrant setting causes trouble.
(To isolate the image for printing, right-click > View image, or similar)
More details in the sections below.

Delphi path-related environment variables

Variables used to compose dirs for various IDE functions
Entire Delphi installation
exe, dll, bpl, jdbg, tlb, subversion
No such dir
...\[platform]\[release] contains: dcu (incl vcl.SomeUnit.dcu), dcp (incl dclSomeUnit.dcp). Also dfm for TeeXxx)
C:\Users\Public\Documents\RAD Studio\9.0
I don't like this under User branch. I overrode $BDSCOMMONDIR to:
[Note 1]
  • Bpl
  • Dcp
  • Demos
  • hpp
  • Styles
C:\Users\graham\Documents\RAD Studio\Profiles
No such dir
C:\Users\graham\Documents\RAD Studio\Projects
Exists. Contains a few aborted compiled files, probably from accidental saves of newly created "Unit1.pas" etc.
C:\Users\graham\Documents\RAD Studio\9.0
No such dir


1. Unexpectedly, Delphi's "Environment Variables > System variables" don't appear to come from Windows' environment variables, at last not in XE2. Instead they seem to come from C:\Users\[username]\AppData\Roaming\Embarcadero\BDS\9.0\environment.proj, which contains an XML listing of such variables. I don't know the implications of editing that, so opted to override BDSCOMMONDIR via the IDE function for that.
I also:
  • Moved subdirs
  • Changed system PATH for the Bpl directory
Finally, it turns out that this change disrupted the installation (in the IDE) of my one installed component, which had to be reinstalled. Evidently installation entails an absolute path to the component's files.

Delphi "Library paths"

The following table shows paths used by the IDE, and specified in two places:
  • IDE level: IDE Tools > Options > Envt Options > Library
  • Project level:Some project > Options > Delphi Compiler
    • ... which also allows specifying separate options for each target platform, and for release vs debug
The defaults shown are from a newish install of Delphi XE2, and the project settings on a fresh project.
Path for...
IDE-level option
IDE-level defaults
Project option
Project defaults
.dcu files. If corresponding source files are present, IDE compiles these first, to (re)create he .dcus.
Library path
  • $(BDSLIB)\$(Platform)\release;
  • $(BDSUSERDIR)\Imports;
  • $(BDS)\Imports;
  • $(BDS)\include;
  • C:\Program Files (x86)\FastReports\LibD16;
  • $(BDS)\RaveReports\Lib;
  • C:\Program Files (x86)\Raize\CS5\Lib\RS-XE2\Win32
Search path
Blank (but includes project's directory).
Do settings here take precedence over IDE-level defaults?
debug version of .dcus (primarily for libraries)
Debug DCU path
(Not applic, as project has separate release/debug search path?)
source files for referenced library units that the current project depends upon. Only for viewing and debugger purposes; not involved in conpiling.
Browsing path
  • $(BDS)\source\rtl\common;
  • $(BDS)\source\rtl\win;
  • $(BDS)\source\ToolsAPI;
  • $(BDS)\source\Internet;
  • etc....
DelphiCompiler > Compiling > Debugging > Use debug .dcus
False! Ie: Don't bother allowing step into system or VCL libraries.
.exe output dir

Output directory
Blank (= project home dir)
.bpl output: (package "dll"s)
Package output dir
Package output dir
.dcp output (package interface)
DCP output dir
DCP output dir
.dcu output: separate directory for dcu output files.

Unit output directory
Blank (= project home dir)
(Mentioned in Help, but where is it in the UI?) For all units in this project.

Default namespace
List of namespace prefixes, so uses clauses can use shorter names
Unit scope names
Unit scope names
All configs: Vcl; Vcl.Imaging; Vcl.Touch; Vcl.Samples; Vcl.Shell; System; Xml; Data; Datasnap; Web;Soap; Winapi
.hpp output
HPP output dir