[Lazarus] Create a package - how?

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:

>> The package contains an docking manager (LDockTree replacement),
>> useful in every application.
> 
> Then it should be moved to components.

I have to leave that move to the maintainers, I only have SVN write 
access to the examples/ tree. I also would suggest a copy, not a move, 
so that I can continue updating the code while maintaining my own naming 
conventions and style. The "official" version can/should be adopted to 
fully conform to the Lazarus style guide.


>> IMO this difference between Delphi and Lazarus packages should be 
>> mentioned in the documentation about creating Lazarus packages. I've 
>> tried to collect all the issues, that currently are not clear to a 
>> Lazarus package newbie, so that the documentation can be updated 
>> accordingly.
> 
> I hope you collected them on our wiki site:
> http://wiki.lazarus.freepascal.org/Lazarus_Packages

You mean: I should update the wiki myself?

The consequences, resulting from the Delphi/Lazarus differences, are not 
always obvious. Reading the page(s) again, after being more familiar 
with packages, the gaps found in the first read will be hidden by the 
knowledge from other sources and experience.


The wording "Create standard package" suggests to me, that there can 
exist non-standard packages - for what special needs? Perhaps two 
entries should be provided, for component packages with IDE integration, 
and runtime-only packages. The intial settings will differ for both 
package types.

The Quick Start paragraph just doesn't handle the case of adding 
existing files to the package. This case may look as self-explaining to 
the experienced user, but not to the newbie. E.g. the IDE Integration 
has to be changed for runtime packages. It also doesn't explain where 
the Unit files go by default, and more such background information. IMO 
links should be added to the other major wiki entries, related to 
packages, and links back to the Package "main" page.

The path delimiter bug will bite the user when following the "Creating a 
new package" instructions, when "Use the Save button...". Create a new 
package and look at the Units path. If the delimiter isn't there, add 
one manually.


> I wrote this many times in the wiki and the IDE has some checks.
> Maybe some more warnings should be added.

Just the need for mentioning something "many times" suggests to me, that 
the documentation structure is bad. Important details IMO should be 
explained in one place, which the reader *must* have seen. That's a 
special wiki problem, since printed documentation can be assumed to be 
read sequentially, and the reader may have to look back to preceding 
chapters for missing information. As long as the announced book about 
Lazarus doesn't exist, the wiki IMO should be restructured from time to 
time, so that it can be read in an intended sequential order, just like 
a book is read.



>> As with the other pathes, the documentation does not shed enough
>> light on the purpose of the different pathes. Eventually the option
>> dialogs should show according hints for the various edit fields.
> 
> You are welcome to improve the wiki and make proposals for the hint
> texts.

Aha! ;-)



>> The wording "Unit Files" or "Other Unit Files" is very misleading, 
>> because "unit" is associated with *source* files in the first place,
>> not with *compiled* files. 
> 
> We could do a multiple choice test when starting the IDE to find out the
> expectation of a user and personalize the IDE. ;)

The personalization of the IDE seems to be implemented already. 
Everybody else can use packages and frames, except me :-(


>> I already noticed that the Lazarus project
>> has several unit/ directories for compiled files, where a Delphi user
>> would expect that these directories contain source files (for e.g.
>> packages).
> 
> Can you give an example?

Look into Delphi component packages, and into the lazarus/ tree...

I accept that unit/ directories have their own meaning, by tradition. A 
newcomer from Delphi should have to pass the Units test, before s/he is 
allowed to proceed ;-)

But I disagree about package "projects". The .lpk file IMO *is* the 
package project file (Delphi: .dpk), distinct from the package main file 
(.pas).


>> Descriptions like:
>>  >>
>> The unit path is used by the IDE and the compiler to search for
>> pascal units (.pas, .pp, .ppu).
>> <<
>> are very confusing, because the locations for .pas and .ppu files are 
>> (should be) different for packages, and the IDE will not have much
>> use for .ppu files, I think.
> 
> Now I'm confused that you are confused.
> Of course the compiler can do more with ppu files than the IDE. But the
> IDE needs the path to the ppu as well.

A separation would clarify much. The PkgDir is needed for opening the 
source files, and is automatically added to the search path. The 
PkgOutDir may become interesting only when a project or package is built 
(linked).

BTW, the PkgOutDir is initialized to lib/, not to unit/. What 
immediately raises the question about the meaning and naming of the 
Library path...



> It's hard as developer to step back and see the things as beginner.
> We need non developers that structure the documentation for beginners.

True. Unfortunately a beginner (or non-developer) only can ask questions 
or suggest improvements, but cannot fill in the facts. After he 
understands the facts, he isn't a beginner any more :-(


>> Yes and no. The path delimiter should be added *before* the path is 
>> shown in the dialog, when a new package is created. (see below)
> 
> Please create a bug report.

Just about...


>>>> Should I check "Add package unit to uses section" - what's the
>>>> purpose or benefit of this option?
>>> I added some info to the wiki. Press F1.
>> Where?
>>
>> This option should be listed as item 1.3 in
>> <http://wiki.lazarus.freepascal.org/IDE_Window:_Package_Options>, but
>> no such item exists there :-(
> 
> Ah, I misunderstood.
> Added.

I see :-)

As I've learned now, the package main file also contains the procedure 
Register, when a designtime package is created. In this case the package 
file *must* be added? Or is this not required?



>> The package creation wizard should add the missing path delimiter, to 
>> prevent such misleading compiler errors.
> 
> There is a probably misunderstanding.
> There is a path delimiter (\ under windows) and there is a search path
> delimiter (semicolon).

AFAIR the semicolon is the path *separator*.

> The IDE automatically appends path delimiters.

Not at the right time :-(

> It never automatically adds search path delimiters.
> Of course when concatenating two search paths it adds a search path
> delimiter.
> Please try to reproduce the error and get some more details.

Either the problem will be fixed soon, or I'll create an bug report with 
instructions. Dont worry :-)

DoDi