View Issue Details

IDProjectCategoryView StatusLast Update
0036349FPCDocumentationpublic2019-11-26 12:36
ReporterAbou Al MontacirAssigned ToMichael Van Canneyt 
PrioritynormalSeverityminorReproducibilityalways
Status resolvedResolutionfixed 
Platformx86_64OSDebian GNU/LinuxOS VersionStretch
Product Version3.0.4Product Build3.0.4+dfsg-22 
Target VersionFixed in Version3.3.1 
Summary0036349: Building HTML documentation causes fpdoc to crash
DescriptionThe issue was identified when trying to debug Debian bug https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=939414.
The reason of that bug is that fpdoc fails is called with missing options.
It was hided by an other bug causing fpdoc to crash silently and does not return a non zero exit code.
Steps To ReproduceJust try to build html doces using hevea.
$ make hevea
...
FPDoc - Free Pascal Documentation Tool
Version 3.0.4 [2019/01/24]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org
(c) 2005 - 2012 various FPC contributors

Exception at 000000000047F415: EInOutError:
File not found: rtl.xct.
make[2]: *** [Makefile:2729: fcl.chk] Error 1
Additional InformationThe missing file rtl.xct is normally created by fpdoc itself when processing the RTL project and is used by fpdoc when processing FCL project.
However this file is not created because --content option is missing.
This option is added to RTLOPTS but that variable is not used when calling fpdoc for building fcl.chk (see Makefile.fpc:928).

The same issue with FCLOPT not called when calling fpdoc for building fcl.chk (see Makefile.fpc:941) which will lead to crash when building fclres.chk.
TagsNo tags attached.
Fixed in Revision1672
FPCOldBugId
FPCTarget3.2.0
Attached Files
  • Fix-documentation-causing-fpdoc-to-crash.patch (545 bytes)
    Description: Fixed a bug causing fpdoc to crahs when building documentation.
    Author: Abou Al Montacir <abou.almontacir@sfr.fr>
    Bug-Debian: http://bugs.debian.org/939414
    diff --git a/fpcdocs/linux.xml b/fpcdocs/linux.xml
    index 8a5ebe4a..8927e3d3 100644
    --- a/fpcdocs/linux.xml
    +++ b/fpcdocs/linux.xml
    @@ -225,7 +225,6 @@ On error, -1 is returned to the parent, and no child is created.
     <seealso>
     <link id="#rtl.baseunix.FpFork"/>
     </seealso>
    -<example file="linuxex/ex71"/>
     </element>
     
     <!-- unresolved type reference Visibility: default -->
    

Activities

Michael Van Canneyt

2019-11-23 16:17

administrator   ~0119456

Fixed. The variable is indeed not added, because the command-line becomes too long, it uses the project file instead.
The full solution is of course to add the content command to the project file, I'll look into that because it may be that we still need to add this to fpdoc.

Abou Al Montacir

2019-11-23 16:24

manager   ~0119457

OK, so please let me know when this is done and on which revision so that I can port the patch to Debian and close the Debian ticket then.

Michael Van Canneyt

2019-11-23 17:39

administrator   ~0119465

The option was already there, and the project file was also correct, it had the option.
You probably experienced a problem because the fcl documentation was built before the rtl documentation.
I corrected the dependencies in rev. 1673, and removed the --content option, it is not necessary.

Abou Al Montacir

2019-11-23 22:24

manager   ~0119469

Thanks for the hint.
I looked again more carefully at the logs at
https://buildd.debian.org/status/fetch.php?pkg=fpc&arch=all&ver=3.0.4+dfsg-22&stamp=1548969051&raw=0
and I discovered that the issue comes from the following error happening when building the RTL docuementation:

No documentation node found for identifier : #rtl.Linux.clone.flags
No documentation node found for idFPDoc - Free Pascal Documentation Tool
Version 3.0.4 [2019/01/16]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org
(c) 2005 - 2012 various FPC contributors

Exception at 00000000004A104E: EInOutError:
[example] File not found.
entifier : #rtl.Linux.clone.args
No documentation node found for identifier : #rtl.Linux.clone.Result

It is not clear what this error is but it is likely the root cause of why the rtl.xct file is not created.

Also please note that I'm not using truck but 3.0.4 for building Debian packages. So it may be that the issue is not present on trunk.

Abou Al Montacir

2019-11-25 22:57

manager   ~0119496

The root cause of this issue was identified as being a reference to missing example file. This reference was dropped from trunk but still in the documenation of 3.0.4.
Attached patch fixes the crash.

Fix-documentation-causing-fpdoc-to-crash.patch (545 bytes)
Description: Fixed a bug causing fpdoc to crahs when building documentation.
Author: Abou Al Montacir <abou.almontacir@sfr.fr>
Bug-Debian: http://bugs.debian.org/939414
diff --git a/fpcdocs/linux.xml b/fpcdocs/linux.xml
index 8a5ebe4a..8927e3d3 100644
--- a/fpcdocs/linux.xml
+++ b/fpcdocs/linux.xml
@@ -225,7 +225,6 @@ On error, -1 is returned to the parent, and no child is created.
 <seealso>
 <link id="#rtl.baseunix.FpFork"/>
 </seealso>
-<example file="linuxex/ex71"/>
 </element>
 
 <!-- unresolved type reference Visibility: default -->

Michael Van Canneyt

2019-11-25 23:09

administrator   ~0119497

There are no branches for the documentation ?

Abou Al Montacir

2019-11-26 12:36

manager   ~0119506

Unfortunately on Debian, we have a very strict rule, that only upstream released code can be used. Also we need to rebuild everything that can be rebuilt.
So we are obliged to generate doc from sources that are released by FPC team. We can not use trunk, but can patch branch with patches from trunk.

Issue History

Date Modified Username Field Change
2019-11-23 16:03 Abou Al Montacir New Issue
2019-11-23 16:03 Abou Al Montacir Status new => assigned
2019-11-23 16:03 Abou Al Montacir Assigned To => Michael Van Canneyt
2019-11-23 16:17 Michael Van Canneyt Status assigned => resolved
2019-11-23 16:17 Michael Van Canneyt Resolution open => fixed
2019-11-23 16:17 Michael Van Canneyt Fixed in Version => 3.3.1
2019-11-23 16:17 Michael Van Canneyt Fixed in Revision => 1672
2019-11-23 16:17 Michael Van Canneyt FPCTarget => 3.2.0
2019-11-23 16:17 Michael Van Canneyt Note Added: 0119456
2019-11-23 16:24 Abou Al Montacir Note Added: 0119457
2019-11-23 17:39 Michael Van Canneyt Note Added: 0119465
2019-11-23 22:24 Abou Al Montacir Note Added: 0119469
2019-11-25 22:57 Abou Al Montacir File Added: Fix-documentation-causing-fpdoc-to-crash.patch
2019-11-25 22:57 Abou Al Montacir Note Added: 0119496
2019-11-25 23:09 Michael Van Canneyt Note Added: 0119497
2019-11-26 12:36 Abou Al Montacir Note Added: 0119506