Basic to Creating Packages on Delphi
unknow - Date: ?
unknow - Date: ?
[SHOWTOGROUPS=4,20]
After you have created a few components you probably want to put them into their own package rather than having them all in the dclusr package.
Here are a few hints about packages:
Types of Packages
Delphi knows two different types of packages, runtime packages and designtime packages.
Runtime Packages
Runtime packages are meant to be distributed with applications, just like dlls are, to keep down the executable size and prevent distributing lots of duplicate code.
Designtime Packages
Designtime packages are meant to be loaded by the Delphi IDE. They contain code to register components with the component palette, also they usually contain the component's icon since that also is only needed for the IDE.
Creating a package
Creating a new package is as simple as creating a new application. From the File menu select New -> Package - Delphi for Win32. In the Project Manager, you will now find a tree node called "package1.bpl" which has the sub nodes "Contains" and "Requires". If you expand the "Requires" node, you will find that Delphi has automatically added "rtl.dcp" to that.
Setting up a runtime package
Now that we have created a package, let's tell Delphi that it is a runtime package: Open the project options (either from the main Project menu or from the context menu of the Project Manager, shortcut: Alt+P, O). On the "Description" page do the following:
So, what have we done?
If you open an explorer window and open the folder into which you just saved your package, you will find the following files:
MyPackage.dof (Delphi <=7), MyPackage.bdsproj (Delphi 2005/2006), MyPackage.dproj (Delphi >=2007)contains your settings; as with any Delphi project, it is in XML format (INI format with Delphi <=7)MyPackage.bdsproj.locala copy of the first one (I have no idea for what purposes, but the IDE recreates it every time a project is loaded; ignore it for now)MyPackage.cfgcontains the settings from MyPackage.bdsproj in a different format suitable for use with the commandline compiler, you can ignore it for nowMyPackage.resyour project's resources, pretty much emptyMyPackage.dpkyour project's main source file, you may notice that it has a .dpk extension rather than .dpr that is normal for an application. dpk stands for Delphi PacKage.jjj
Compile your new package, we will need that for the next step.
Setting up a Design-time Package
As pointed out above, a designtime package is meant to be loaded into the Delphi IDE. You should always keep your designtime code separated from your runtime code, so it is best to always create two packages for your components from the start.
To create a designtime package you just create a new package as described above. The only difference is in the project options:
There is another difference to a runtime package: A designtime package must interact with the IDE and therefore needs to know about its internals. To make that possible, it needs the package "DesignIDE", which comes with any Delphi version. So we must add this package to the Requires section:
Right click on the "Requires" node of your new package and select "Add Reference". You get a dialog for entering or selecting the package. It is easier to just type in "DesignIDE" rather than using the file select dialog to find it, but just for the record: It is located in "c:\program files\borland\bds\4.0\lib" and called "designide.dcp".
Also, since we want to use this package to install the components that will be put into our runtime package, it must reference that package as well. So repeat the above to add "MyPackage" to the list of Required packages. Note that here you do not include the LIB suffix ("100"), but just the package name. When you press OK you will get an error message "File MyPackage.dcp not found.". The IDE does not know where to look for it, so this time we need the browse button. Normally the .dcp files the IDE generates are put into "<my documents>\Borland Studio Projects\bpl".
Now save your new package into the same directory as the runtime package. You could give it any name you like, but the convention here is to use the runtime package's name with a "Dcl" prefix. I guess the D stands for designtime but I haven't got a clue what the prefix means. But Borland does it and pretty much any component vendor does, so why not follow that example and call it "DclMyPackage"?
(My guess is: DCL = Designtime Component Library --Dummzeuch 15:43, 1 July 2007 (UTC))
Saving the Project Group
Since we are at it, let's save the project group as well. From its context menu select "Save Project Group" and save it to the same directory as your packages. You can call it whatever you like, maybe "MyPackageGroup"?
Now you can open both, the runtime and the designtime package, by just opening the project group.
Adding a component - the right way
If you haven't created a package before, but have created your own component(s), you have probably added them to the default dclusr package. If you haven't created any component, yet, here is how to do it:
Adding a component using the wizard
First, make the runtime package the current project by double clicking on it in the Project Manager.
From the context menu select "Add New -> Other" to open the "New Items" dialog. Since you are adding to a package, the possibilities are limited. Select the "Delphi Files" category and double click the "Component" icon.
You now get yet another dialog, the "New VCL Component" wizard. We don't want to make it difficult, so let's just create a new component based on TButton. Select it from the list (it supports incremental search, btw.) and click "Next".
On the next page, give your new button a class name. It must be unique within the whole IDE, including any 3rd party components. Use your imagination (I haven't got much of that, so I'll call it "TMyButton" for now). Select a palette page, or rather enter a new name like "MyComponents".
The Unit name also must be unique within all run- and designtime packages loaded by the IDE. From Delphi 7 on, a unit name can contain dots, so let's follow the Java tradition and use your domain name as a prefix, to make sure we don't get any clashes. (You haven't got any domain? Right, then let's just assume one like http://www.dummzeuch.de [That's my own domain, so please don't distribute any packages with that prefix!], so the unit would be called "de.dummzeuch.MyButton.pas".)
Save it to the same directory as your packages. Click "Finish" to close the wizard.
Select "Save All" from the "File" menu to save your work.
[/SHOWTOGROUPS]
After you have created a few components you probably want to put them into their own package rather than having them all in the dclusr package.
Here are a few hints about packages:
Types of Packages
Delphi knows two different types of packages, runtime packages and designtime packages.
Runtime Packages
Runtime packages are meant to be distributed with applications, just like dlls are, to keep down the executable size and prevent distributing lots of duplicate code.
Designtime Packages
Designtime packages are meant to be loaded by the Delphi IDE. They contain code to register components with the component palette, also they usually contain the component's icon since that also is only needed for the IDE.
Creating a package
Creating a new package is as simple as creating a new application. From the File menu select New -> Package - Delphi for Win32. In the Project Manager, you will now find a tree node called "package1.bpl" which has the sub nodes "Contains" and "Requires". If you expand the "Requires" node, you will find that Delphi has automatically added "rtl.dcp" to that.
Setting up a runtime package
Now that we have created a package, let's tell Delphi that it is a runtime package: Open the project options (either from the main Project menu or from the context menu of the Project Manager, shortcut: Alt+P, O). On the "Description" page do the following:
- Into the field called "Description" enter a short description of the package like "My first package".
- Under "Usage options" select "Runtime only"
- Under "Build control" select "Explicit rebuild"
- In the "Package name" group box, enter a LIB Suffix that corresponds to your Delphi version:
- Delphi 2006: "100"
- Delphi 2005: "90"
- etc; you get the picture (See Package Suffixes for a list of Delphi versions and the package suffixes they use)
So, what have we done?
- We have set a description for the package. This description will never really show up for a runtime package, but give one anyway just to get into the habit. It is more important for a designtime package.
- We set the package to be a runtime only package. This means that the IDE will tell you that it is a runtime package and refuse to install it. That's a good thing.
- We set the package to be built only explicitly. That's actually a matter of taste. I for one don't like the IDE trying to rebuild every bloody package if I only change one line in another package.
- We set the LIB Suffix to e.g. 100 which will make the package file always have a compiler version dependant suffix to help users to determine which package to use for their version of Dephi. This is not a requirement, but Borland does it for their own packages so why shouldn't we? If you look closely at the Project Manager, you will find that the new package is no longer called "Package1.bpl" but "Package1100.bpl". There's the suffix we just added.
If you open an explorer window and open the folder into which you just saved your package, you will find the following files:
MyPackage.dof (Delphi <=7), MyPackage.bdsproj (Delphi 2005/2006), MyPackage.dproj (Delphi >=2007)contains your settings; as with any Delphi project, it is in XML format (INI format with Delphi <=7)MyPackage.bdsproj.locala copy of the first one (I have no idea for what purposes, but the IDE recreates it every time a project is loaded; ignore it for now)MyPackage.cfgcontains the settings from MyPackage.bdsproj in a different format suitable for use with the commandline compiler, you can ignore it for nowMyPackage.resyour project's resources, pretty much emptyMyPackage.dpkyour project's main source file, you may notice that it has a .dpk extension rather than .dpr that is normal for an application. dpk stands for Delphi PacKage.jjj
Compile your new package, we will need that for the next step.
Setting up a Design-time Package
As pointed out above, a designtime package is meant to be loaded into the Delphi IDE. You should always keep your designtime code separated from your runtime code, so it is best to always create two packages for your components from the start.
To create a designtime package you just create a new package as described above. The only difference is in the project options:
- Under "Usage options" select "Designtime only"
There is another difference to a runtime package: A designtime package must interact with the IDE and therefore needs to know about its internals. To make that possible, it needs the package "DesignIDE", which comes with any Delphi version. So we must add this package to the Requires section:
Right click on the "Requires" node of your new package and select "Add Reference". You get a dialog for entering or selecting the package. It is easier to just type in "DesignIDE" rather than using the file select dialog to find it, but just for the record: It is located in "c:\program files\borland\bds\4.0\lib" and called "designide.dcp".
Also, since we want to use this package to install the components that will be put into our runtime package, it must reference that package as well. So repeat the above to add "MyPackage" to the list of Required packages. Note that here you do not include the LIB suffix ("100"), but just the package name. When you press OK you will get an error message "File MyPackage.dcp not found.". The IDE does not know where to look for it, so this time we need the browse button. Normally the .dcp files the IDE generates are put into "<my documents>\Borland Studio Projects\bpl".
Now save your new package into the same directory as the runtime package. You could give it any name you like, but the convention here is to use the runtime package's name with a "Dcl" prefix. I guess the D stands for designtime but I haven't got a clue what the prefix means. But Borland does it and pretty much any component vendor does, so why not follow that example and call it "DclMyPackage"?
(My guess is: DCL = Designtime Component Library --Dummzeuch 15:43, 1 July 2007 (UTC))
Saving the Project Group
Since we are at it, let's save the project group as well. From its context menu select "Save Project Group" and save it to the same directory as your packages. You can call it whatever you like, maybe "MyPackageGroup"?
Now you can open both, the runtime and the designtime package, by just opening the project group.
Adding a component - the right way
If you haven't created a package before, but have created your own component(s), you have probably added them to the default dclusr package. If you haven't created any component, yet, here is how to do it:
Adding a component using the wizard
First, make the runtime package the current project by double clicking on it in the Project Manager.
From the context menu select "Add New -> Other" to open the "New Items" dialog. Since you are adding to a package, the possibilities are limited. Select the "Delphi Files" category and double click the "Component" icon.
You now get yet another dialog, the "New VCL Component" wizard. We don't want to make it difficult, so let's just create a new component based on TButton. Select it from the list (it supports incremental search, btw.) and click "Next".
On the next page, give your new button a class name. It must be unique within the whole IDE, including any 3rd party components. Use your imagination (I haven't got much of that, so I'll call it "TMyButton" for now). Select a palette page, or rather enter a new name like "MyComponents".
The Unit name also must be unique within all run- and designtime packages loaded by the IDE. From Delphi 7 on, a unit name can contain dots, so let's follow the Java tradition and use your domain name as a prefix, to make sure we don't get any clashes. (You haven't got any domain? Right, then let's just assume one like http://www.dummzeuch.de [That's my own domain, so please don't distribute any packages with that prefix!], so the unit would be called "de.dummzeuch.MyButton.pas".)
Save it to the same directory as your packages. Click "Finish" to close the wizard.
Select "Save All" from the "File" menu to save your work.
[/SHOWTOGROUPS]