1 ..  ============================================================================ 

     2     Name        : debugging.rst

     3     Part of     : Helium 

     4     

     5     Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     6     All rights reserved.

     7     This component and the accompanying materials are made available

     8     under the terms of the License "Eclipse Public License v1.0"

     9     which accompanies this distribution, and is available

    10     at the URL "http://www.eclipse.org/legal/epl-v10.html".

    11     

    12     Initial Contributors:

    13     Nokia Corporation - initial contribution.

    14     

    15     Contributors:

    16     

    17     Description:

    18     

    19     ============================================================================

    20 

    21 .. index::

    22   module: Debugging

    23 

    24 #########

    25 Debugging

    26 #########

    27 

    28 

    29 .. contents::

    30    

    31    

    32 .. _Troubleshooting-label:

    33 

    34 Troubleshooting

    35 ===============

    36 

    37 This section contains details on how to find errors and problems within helium itself (for helium contributors) and within the configuration files

    38 and ANT tasks etc. for the build managers and subcons.

    39 

    40 .. index::

    41   single: Output Logs

    42 

    43 .. index::

    44   single: Logs

    45 

    46 Output Logs

    47 -----------

    48 

    49 When running Helium there are a large number of output logs created to assist with debugging and determining what has been performed and what has not. All of the log files are generated in the build area, usually under the ``output\logs`` folder. Many of the logs are created in different formats, e.g. the Bill Of Materials log file exists as .html, .xml and .txt (all the same information). Some of the logs exist as different file formats giving different information at various stages of the activity, e.g. the cenrep logs in which case generally the .html files are a summary of the whole activity.

    50 For mc product builds the following log files are created 

    51 where xx is the name of the build + build id e.g. 12.030_ant_env.log

    52 where nn is the variant number(s):

    53 

    54 .. csv-table:: build logs

    55    :header: "Log name", "File type", "Purpose"

    56 

    57     "xx_ant_env.log", "Ant environment Log", "Lists all the environment varaibles"

    58     "xx_ant_build.log", "Ant build Log", "Lists all the ANT tasks that have been executed"

    59     "xx_BOM.html", "BOM listing", "lists all the projects and tasks included in the build"

    60     "xx_bom_delta.html", "BOM delta listing", "lists all the delta projects and tasks included in the build"

    61     "xx.roms.log", "ROM creation log", "lists all the .iby, .txt, etc. files included in the ROM creation, including missing files"

    62     "xx_scan2.html", "Compilation summary", "Lists all the components built with their errors (0 if no errors)"

    63     "xx_zips_scan2.html", "zips creation log", "lists all the zip files created and whether there are any errors"

    64     "hlm_listener.log", "Helium debug log", "Helium debug log for internal data [Helium runtime information] and it can be found inside HELIUM_CACHE_DIR folder"

    65     "hlm_debug.log", "Helium debug log", "Helium debug log for all other debug log (all java logs) and it can be found inside HELIUM_CACHE_DIR folder"

    66        

    67 Targets and their logs

    68 ;;;;;;;;;;;;;;;;;;;;;;

    69 

    70 .. image:: dependencies_log.grph.png

    71 

    72 .. index::

    73   single: Troubleshooting

    74 

    75 

    76 Troubleshooting - Helium

    77 ------------------------

    78 

    79 Use the :hlm-t:`diagnostics` command provide debugging information when reporting problems. It lists all the environment variables and all the Ant 

    80 properties and all the Ant targets within Helium so you might find it useful to pipe it to a log file so that you can read all of the output at your leisure::

    81 

    82     hlm diagnostics > diag.log

    83 

    84 .. index::

    85   single: Failing early in the build

    86 

    87 Failing early in the build

    88 ;;;;;;;;;;;;;;;;;;;;;;;;;;;

    89 

    90 The :hlm-p:`failonerror` property is defined in ``helium.ant.xml`` and has the default value ``false``. It is used to control whether the ``<exec>`` 

    91 tasks fail when errors occur or the build execution just continues. The build can be configured to "fail fast" if this is set to ``true``, 

    92 either on the command line or in a build configuration before importing ``helium.ant.xml``. Given that many ``exec`` tasks will return an 

    93 error code due to build errors, it is not recommended to set this to true for regular builds.

    94