You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
137 lines
7.3 KiB
XML
137 lines
7.3 KiB
XML
<!--
|
|
Copyright (c) 2016 OpenPOWER Foundation
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
-->
|
|
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_debug">
|
|
|
|
<title xml:id="section_template_debug_title">Debugging build failures</title>
|
|
<para>Maven/docbkx failures generally fall into these categories:</para>
|
|
<itemizedlist>
|
|
<listitem><para>Project structure errors</para></listitem>
|
|
<listitem><para>Docbook validation errors</para></listitem>
|
|
<listitem><para>Build failures</para></listitem>
|
|
</itemizedlist>
|
|
<para>Correcting the document errors starts with understanding which type of failure has occurred and
|
|
understanding where to look in your document source.</para>
|
|
|
|
<section>
|
|
<title>Project structure errors</title>
|
|
|
|
<para>Because the OpenPOWER Foundation documentation projects are not self-contained in the
|
|
GitHub repositories, forgetting to clone the <literal>Docs-Master</literal> project in addition
|
|
to the document project or cloning it in the wrong location is a common problem. Failures of this kind
|
|
produce the following error:</para>
|
|
<screen>...
|
|
[INFO] Scanning for projects...
|
|
[ERROR] The build could not read 1 project -> [Help 1]
|
|
[ERROR]
|
|
[ERROR] The project org.openpowerfoundation.docs:workgroup-pom:1.0.0-SNAPSHOT (/home/scheel/Docs-Template/pom.xml) has 1 error
|
|
[ERROR] Non-resolvable parent POM: Could not find artifact org.openpowerfoundation.docs:master-pom:pom:1.0.0-SNAPSHOT and 'parent.relativePath' points at wrong local POM @ line 6, column 11 -> [Help 2]
|
|
[ERROR]
|
|
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
|
|
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
|
|
[ERROR]
|
|
[ERROR] For more information about the errors and possible solutions, please read the following articles:
|
|
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/ProjectBuildingException
|
|
[ERROR] [Help 2] http://cwiki.apache.org/confluence/display/MAVEN/UnresolvableModelException</screen>
|
|
<para>The identifying characteristic of this error type is the message, "Non-resolvable parent POM". This occurs because the
|
|
<literal>pom.xml</literal> file in the documentation project, called the "workgroup-pom" because of a project
|
|
<literal><artifactId>workgroup-pom</artifactId></literal> declaration, expects its parent pom file to be in the
|
|
location defined by the <literal><relativePath>../Docs-Master/pom.xml</relativePath></literal>, up one directory and
|
|
then in the <literal>Docs-Master</literal> director.
|
|
</para>
|
|
|
|
<para>So, if you see the message "Non-resolvable parent POM", ensure that the <literal>Docs-Master</literal> project
|
|
and your project have been cloned
|
|
into the same parent directory. See <xref linkend="section_cloning_master_doc"/> for detailed directions on how to do this.</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Docbook validation errors</title>
|
|
|
|
<para>Validation errors are generally indicated in the build output with text like the following:
|
|
<screen>...
|
|
@@@@@@@@@@@@@@@@@@@@@@
|
|
!!!VALIDATION ERRORS!!
|
|
!!!!!!!!!!!!!!!!!!!!!!
|
|
|
|
Note: Open the temporary file:
|
|
|
|
file:/home/user1/Docs-Template/template/target//bk_main.xml-invalid.xml
|
|
|
|
to see all the errors in context.
|
|
You must correct the errors in the original
|
|
source DocBook or wadl files however.
|
|
|
|
You can control whether build fails or not by
|
|
setting failOnValidationError to no in your pom.
|
|
|
|
lineNumber: 272; columnNumber: 70; text not allowed here; expected element "address", ...
|
|
</screen></para>
|
|
<para>This error message contains three key pieces of information:</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The full path and filename that contains the context for the failure. In the message above, this is
|
|
<literal>/home/user1/Docs-Template/template/target//bk_main.xml-invalid.xml</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The location within the file of the syntax error. For the above example, the key information is "<literal>lineNumber: 272; columnNumber: 70</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>An explanation of the failure. This information in the above error reads, "text not allowed here; expected element "address", ...".</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Build failures</title>
|
|
|
|
<para>Build errors are easily identified as well. Below is an example:
|
|
<screen>...
|
|
[INFO] ------------------------------------------------------------------------
|
|
[INFO] BUILD FAILURE
|
|
[INFO] ------------------------------------------------------------------------
|
|
[INFO] Total time: 4.827s
|
|
[INFO] Finished at: Wed Jul 29 14:55:33 CDT 2015
|
|
[INFO] Final Memory: 17M/171M
|
|
[INFO] ------------------------------------------------------------------------
|
|
[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) on project openpower-template-guide: Execution generate-webhelp of goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp failed: XInclude resource error (sec_template_new_document.xml) and no fallback provided. XProc error err:XD0011: org.xml.sax.SAXParseException; systemId: file:/home/user1/openpower-foundation-docbkx-framework/doc/template/sec_template_new_document.xml; lineNumber: 55; columnNumber: 17; The element type "para" must be terminated by the matching end-tag "</para>". -> [Help 1]...
|
|
</screen></para>
|
|
|
|
<para>Like validation errors, three key pieces of information are again provided:</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The full path and filename of our failure is
|
|
<literal>/home/user1/Docs-Template/template/sec_template_new_document.xml</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The location within the file of the error is "<literal>lineNumber: 55; columnNumber: 17</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>An explanation of the failure begins with the text, "The element type "para" must be terminated by the
|
|
matching end-tag "</para>."</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>With these details in hand for either error, one simply locates the offending syntax and makes the appropriate
|
|
correction. Online resources such as those listed in <xref linkend="section_template_references"/> may be helpful.</para>
|
|
</section>
|
|
|
|
</section>
|
|
|