[Lazarus] UPDATED: Re: documentation snapshot

Marco van de Voort marcov at stack.nl
Sun Apr 21 13:45:19 CEST 2013


On Sun, Apr 21, 2013 at 09:28:41AM +0100, Graeme Geldenhuys wrote:
> On 2013-04-20 23:47, Marco van de Voort wrote:
> > 
> > P.s. I used script build_lcl_chm.sh, not buildchm.sh
> 
> So what did you change? fpdoc and the *.lpr in Lazarus repository
> (docs/html/ directory)? As noted in a message a few days ago, I couldn't
> build any LCL docs. I wanted to supply and INF version of LCL, but couldn't.

I mostly checked the html backend for regressions since the last major build
(just before the 2.6.0 release, fpdoc sources december 2011). Quite a lot
was merged in after that. I did a similar session last summer too (for
2.6.2RC1), but that lead to acceptable docs, not perfect docs.

I don't understand how Michael was able to generate the 2.6.2 online docs
fully linked, unless he also used something known good fpdoc (from dec 2011
or so).

Anyway, what I did in detail. 

- First, don't start with the LCL, but with the FCL.
    1) it is much smaller (and thus quicker) and easier to debug
    2) it still has external dependencies (to rtl)
   
   only when it compiles under gdb with all the debugoptions below
    enabled, AND sizeof(fcl)>= sizeof(last good fcl, dec2011) continue with
    lcl

- Compile FPC trunk and install it.

- Compile only the fpdoc parts (fcl-passrc and fpdoc) with as much
  runtime debug options as you can find 
( I used " -Sa -gttt -CROriot -dHEAPTRC_EXTRA -gw2l -viwn -Sg  -Cppentiumm
	-dinheritancewarnings"  under freebsd/32)

- get the fpdoc commandline from running the script (the above
  build_lcl_chm.sh or fixdocs.sh in
   FPCs case). In LCL's case we also reuse the output of this script
	 (generated as docs/html/lcl/inputfile.txt )
- set up a ~/.gdbinit as follows:

file <path to binary fpdoc>
set language pascal
set args  <fpdoc arguments>
b fpc_raiseexception

- In LCL's case, copy the fpcdoc content files (.xct) to docs/html
	infs too if the inf backend needs them present.
- Change to the correct directory (fpcdocs/ or docs/html/lcl (or lazautils)
- run gdb and go directly to (r)un.
- if exceptions pop up, do a backtrace(bt) and fix them. Not all exceptions
   are catastrophic (i.e.  abort program), seems fpdoc writers like to open
   files without checking first and handling the exception if needed.  I
   fixed some of those, and also in gettext. If you find non catastrophic
   exceptions, root them out, it will make debugging easier in the future.

The main reason to do it this way is that the runtime checks (specially
-gttt and -CR) are more likely to cause it to happen nearer to where the
problem is, as opposed to where the corruption causes an exception of its
 own. It is very, very powerful, and whoever implemented this (Jonas for
-gttt I believe) did extremely good work. I would wish I had it in Delphi.
It also makes unittesting much more worthwhile, since it also uncovers
 errors that generally make no problems.

In my case the problems were twofold:

- In fcl-pastree, classes have been separated into baseclasses and
  descendents. However the backend code still checks like aclass.classtype=
   TSomeClass, but TSomeClass now also has descendents. So it should be 
      aclass.classtype.inheritsfrom(TSomeClass).
  Check all TPasModule and TPasClasstype occurances not in declarations or
  casts.
- In some places the original class is now one of the baseclass
  descendents, but the whole family (baseclass+descendents) is still
  casted to the original class. In most cases this is no problem,
  but in some it access fields on in the descendent.  The classtree
  code in particular suffered from this. (probably because it is the
  newest)

beside this there were common programming errors (like variables that are
used unintialized in some codepaths) -gttt again....
 
There was also the already mentioned (on fpc-devel) weird non-error:

procedure xxx(out sss :someclass);

begin
 // sss not assigned.
end;

var t : someclass;

t:=someclass.create
xx(t);
// xx is now randomized due to -gttt while without it, it still points to t.





More information about the Lazarus mailing list