Getting Started with QAC / QAC++

Transcription

1 Getting Started with QAC / QAC++ Table of Contents 1 Introduction Product Versions License Server Creating a Project Visual Studio Makefile Environment Eclipse/Wind River Workbench Tornado Borland C++ Builder Code Warrior Manually From Directory Structure Identifying the Source Files Creating a Project Directory Auto-Creating the Project Setting up Personalities Propagating changes to other folders Editing Personalities Configuring the Message Personality Configuring the Analyser Personality Configuring the Compiler Personality Saving the Project Analysis Reducing the number of displayed warnings Creating a Compiler Personality Introduction Compiler Personality Generator Introduction Starting The Utility Product and Output location Compiler Execution Information Search Directories Compiler Defines and Switches Resolving Syntax Errors Introduction Which syntax errors must I resolve? Using the Pre-processed Output Missing Include Files Handling Language Extension Keywords Handling #pragma blocks in QAC Handling bool and wchar_t in QAC Re-coding to eliminate syntax errors Copyright 2007 Programming Research 1

2 1 Introduction This document provides step by step tuition on how to perform project configuration for QAC and QAC++ on Microsoft Windows. Detailed descriptions are provided for some common configuration problems and the various ways in which they can be resolved. Details of how to set up a project in QAC or QAC++ for use with a compliance module such as the MISRA Compliance Module (MCM) are also provided. 2 Product Versions The document refers throughout to the Windows versions of QAC version 7.0 and QAC++ version Screenshots shown are taken from those products. Many of the steps identified in creating a project apply to earlier product versions and will continue to apply in future releases. UNIX users may also use this document as a guide for configuring QAC and QAC++. 3 License Server Before continuing with this document, please ensure that you have a FLEXlm license server configured for use with your QAC/QAC++ license. The software and details of how to configure FLEXlm can be found under the following areas: or alternatively Copyright 2007 Programming Research 2

3 4 Creating a Project 4.1 Visual Studio For the various Visual Studio environments, there are direct integration packages available from the following areas which will automate the configuration and produce analysis results inside the VS IDE. If you use Visual Studio project or solution files and/or the IDE please download the appropriate integration and refer to the help documentation. Visual Studio 6 Visual Studio.Net Visual Studio Makefile Environment If you use GCC the following script will automatically generate a gcc or g++ compiler personality for you. Please download and install the GCC integration and refer to the help documentation for use. Note this replaces the need to complete Section 5 Creating a Compiler Personality below. or alternatively The makefile integration allows you to wrap the compiler s invocation so that QAC/QAC++ analysis can be done without altering your current make environment or any manual configuration. Viewing the results of the analysis can be done through generated annotated source, or by invoking the message browser on a filelist created by the makefile integration. Please download and install the Makefile integration and refer to the help documentation for use (e.g. you will need to specify the location of the above generated gcc compiler personality in the wrapper configuration file) Eclipse/Wind River Workbench For Eclipse based users, there is a direct integration package available for the various products under the C/C++ CDT s. This integration will provide the viewing of analysis results and the help system integrated into the IDE and can be downloaded along with associated documentation from the following area: To invoke the analysis engine from the Eclipse plug-in, the Eclipse makefile needs to be edited to include a target for the analysis. This is best done utilising the wrapper program QAW which can be found along with associated documentation downloaded from the following area: or alternatively Note you will still need to create a Compiler Personality for your compiler, see Section 4.2 Makefile Environment above, or alternatively in Section 5 Creating a Compiler Personality. Copyright 2007 Programming Research 3

4 4.4 Tornado For Tornado 2.x and QAC users, there is a direct integration package available. This integration will provide the viewing of analysis results and the help system integrated into the IDE and can be downloaded along with associated documentation from the following area: Borland C++ Builder There is currently no direct integration with the Borland IDE; however a compiler personality and accompanying substitute header files can be downloaded from the following area: The installer of this integration requires the presence of Borland Builder 5 or 6 on the machine and will unpack the substitute headers and personality to the PRQA installation path. Note this replaces the need to complete Section 5 Creating a Compiler Personality below. You will still need to create a QAC/QAC++ project based on the Borland project file as described in section 4.7 below. 4.6 Code Warrior There is currently no direct integration with the Code Warrior IDE, however a project converter which builds a QAC/QAC++ project (including analyser personalities) out of an exported.mcp.xml file is available. Please contact support@programmingresearch.com for details of the converter. Note you will still need to create a Compiler Personality for the CW compiler which is described in Section 5 Creating a Compiler Personality. 4.7 Manually From Directory Structure Identifying the Source Files In Windows Explorer, locate the source files that you wish to analyse. Let us suppose that our source files live in C:\Work and have sub-folders A, B and C as shown below Creating a Project Directory Create a project directory to store the results of the analysis, the configuration files needed and the project file. For example C:\My Project Create two directories within your project directory called output and personalities. The output directory will be used to contain the output results produced by QAC or QAC++. The personalities directory will be used to contain the required configuration files. Copyright 2007 Programming Research 4

5 4.7.3 Auto-Creating the Project Now we are ready to create the QAC or QAC++ project. Select File/Auto-Create Project from the menu. Set the Starting Directory to be the location of the source directory identified (for example C:\Work\ ). Set the Root Folder Name to be the same as the project or the root directory name (e.g. My Source Code). Set the Output File Path to be the output directory created (for example C:\My Project\output). Select the extensions of the files that you wish to analyse. Note it is seldom appropriate to analyse header files directly and they should not usually be added explicitly to your project. Header files will be analysed as part of a translation unit when the source files that include them are analysed. Also make sure that the Replicate source tree structure in output paths checkbox is checked. Then press OK. Copyright 2007 Programming Research 5

6 You should now see that QAC or QAC++ has produced a project with a project folder structure matching the folders of your source file tree. The project folders will only include files with the specified file extension. For example: Copyright 2007 Programming Research 6

7 4.7.4 Setting up Personalities Three personalities are required in order to configure a project: a message personality, an analyser personality and a compiler personality. The message personality is designed to reflect your coding standard. The analyser personality represents project specific configuration about how your source code is compiled. The compiler personality represents the characteristics of your compiler. QAC and QAC++ need a compiler personality so that they can emulate the compilation that your compiler does. In circumstances where the tool has already been used within your organisation, it may be possible to acquire personalities that are already available. In the absence of such resources, personality files may be acquired from: Tool Supplied Personalities: A number of standard personalities are provided with the tools. These are located in the personalities directory of the QAC/QAC++ installation. Compliance Module Personalities: When using a compliance module, you should use the Message and Analyser Personalities provided with the compliance module as a starting point. When you install a compliance module you will find a sub-directory off the main installation directory of the tool (QAC or QAC++) with the name of the compliance module. This directory contains a subdirectory called personalities which contains a message personality and an analyser personality. So for example in MCM, you will find mcm.p_s and mcm.p_a. Note that this directory also contains a Compiler Personality (mcm.p_c). However, you should create a new one specific to your compiler by following Sections or 5. New personalities: New personalities can be created in the following way: Select Configuration from the menu bar. Select Message Personalities, Analyser Personalities or Compiler Personalities as required Copyright 2007 Programming Research 7

8 Click on the Add button Save the personality with a suitable name in the personalities directory created earlier (for example C:\My Project\personalities\configure.p_s). A new personality will consist of default settings for all the various QAC/QAC++ configuration options. A new message personality will have all messages enabled a configuration which is likely to be unhelpful without some modification. Integrations: The various integrations referred to previously, contain pre-configured compiler personalities, however a utility for creating compiler personalities is available and discussed in Section 5. Having located 3 suitable personality files, copy them into the personalities directory in your project directory. Now select the root folder of your QAC/QAC++ project and double click it to bring up the Folder Parameters dialog. Using the Browse buttons, locate the personalities you copied into your project directory Propagating changes to other folders It is possible for each folder in a QAC/QAC++ project to refer to a different message, analyser and compiler personality; however it is more usual for all the folders in a project to refer to refer to the same set of personality files. The best way to make all folders refer to the same personality file is to right click the root folder and select Propagate Changes to Sub- Folders Editing Personalities A common mistake made by new users is to use the Configuration menu to access their personalities. The Configuration menu is useful when creating a new personality or copying a personality based on the ones supplied with the tool. If you wish to edit the personalities associated with your project, select the Edit Menu and then Folder Parameters; alternatively double click on the folder itself. The Edit buttons for the three personalities are shown circled below. Copyright 2007 Programming Research 8

9 4.7.7 Configuring the Message Personality Bring up the message personality associated with the root folder using the instructions provided in section Select the Display tab and ensure that the Display Header Warnings checkbox is checked. Click OK to commit your change to the message personality. Copyright 2007 Programming Research 9

10 4.7.8 Configuring the Analyser Personality Bring up the analyser personality associated with your project using the instructions in section The analyser personality consists of various tabs, but the two most important for project configuration are the Project Headers and Project Macros tabs. These reflect the command line parameters that must be passed to your compiler in order to compile the source code that you are trying to analyse. For example, suppose you use the following command line to build your software. cc DHAVE_CONFIG_H DVERSION=12 IC:\Work\A IC:\Work\C a.c The I options are the Project Headers and must be inserted as shown below. Note that the order in which the include paths appear in this list should be the same as the order in which they appear on the command line. In the above screenshot the folder C:\Work\A has the Suppress Output flag set. This means that warnings for header files found in this directory will not be displayed. Typically you will want to see all warnings for your own header files so that problems can be fixed. However, when using a third party library to compile your code (for example Boost), you may wish to ignore warnings that are not serious because it will not be practical to modify the header files. Copyright 2007 Programming Research 10

11 The D options in this example are the Project Macros and would be inserted as shown below. It is possible that you will need to set up more than one analyser personality if all the files in your project do not share the same command line parameters. Note that for many projects, the D and I options are included in a makefile. If a makefile is included with the source, look at the makefile for the D and I options, or use the makefile integration as discussed in Section 4.2. Click OK to commit your change to the analyser personality Configuring the Compiler Personality See Section 5 for information about creating and configuring a Compiler Personality Saving the Project Before beginning the analysis of files it is recommended that you save the project by selecting File/Save Project As... from the menu. Save the project file with an appropriate name in the project directory (for example C:\My Project\My Project.prj). Copyright 2007 Programming Research 11

12 4.8 Analysis You are now in a position to analyse your code. There may be some further configuration problems that arise during analysis, so it is advisable to analyse only one file at a time to start with. Problems will often occur in header files, so by analysing one file at a time, you can ensure that configuration problems are eliminated quickly. Select the first file that you wish to analyse and press the button. This will analyse the file. Don t be concerned if the analysis status says Analysis Warning. After the analysis, close the analysis status window. You should now see that a tick has appeared to the left of the file that you have analysed as shown below. To see the results of the analysis in the Message Browser double click the analysed file. If you get a dialog that indicates you have syntax errors upon starting the message browser, you have analysis problems that must be fixed in order to ensure a complete analysis of your code. The syntax error dialog looks like this. Copyright 2007 Programming Research 12

13 When the message browser opens, you will see four tabs in the top left pane called Message Groups, Files, CMA Results and Syntax Errors. Initially we want to focus on Syntax Errors which are serious errors preventing analysis of your code. If you have syntax errors, upon opening the message browser you shall be taken directly to the Syntax Errors tab, whereas if you don t have syntax errors you shall be taken to the Message Groups tab. All syntax errors are shown in red and must be resolved. To see how to resolve the syntax error warnings see section 6. Once you have resolved the syntax errors for a file you can move onto the next file. Eventually once you are confident that you have resolved the issues you will be in a position to analyse the whole project. Copyright 2007 Programming Research 13

14 4.9 Reducing the number of displayed warnings Once you have analysed the project successfully, there is no need for re-analysis unless you change your source code. You may find that you have a lot of warnings initially and want to focus on a particular class of warnings such as Major warnings (in QAC). This can be done by editing the message personality associated with the root folder of the project. In the installation directory of QAC/QAC++, there is a critical message personality which focuses on messages of the most severe nature. QAC++ also has other personalities such as Effective C++ and Industrial Strength C++. Levels can be suppressed in the Message personality by selecting a level and pressing space. Once suppressed a red cross will appear in front of the level name as shown below. Individual messages can also be suppressed in the same manner. Closing and re-opening the message browser will pick up the changes you have made to the message personality. Copyright 2007 Programming Research 14

15 5 Creating a Compiler Personality 5.1 Introduction A compiler personality must be created for each compiler that you use. It represents the characteristics of your compiler such as Where the compiler keeps its system headers (stdio.h, iostream etc) What macros the compiler sets implicitly (_WIN32, STDC etc) What additional keywords the compiler supports (interrupt, far, near, ) What architecture the compiler is for (32 bit, 16 bit.. etc) What is the behaviour of the compiler with respect to certain aspects of the ISO C(C++) language. The C language has evolved over many years into the language we call ISO C today. ISO C is an international standard that defines the language C. Most compilers these days will be compliant to ISO C meaning that they support the ISO C language. However, there are two issues with compilers that must be addressed. Firstly compilers support ISO C, but some also support additional constructs and keywords. For example the Keil C compiler will support an interrupt keyword. Secondly when implementing a compiler for ISO C, there are certain areas of the language that must be specified by the compiler writer. These include the sizes and alignments of types as well as the resolution of particular behaviours. The same is true for the C++ language and the ISO C++ standard. 5.2 Compiler Personality Generator Introduction In order to automate the configuration of you compiler, the AutoCmpPersonGen utility can be run to extract the necessary configuration options from your environment and create a compiler personality. This particular utility requires some user input, such as the compiler executable command, the location of the compiler include directories and so forth which can be entered via the GUI as explained below. As explained in section 4 above, this utility should be used to generate compiler configurations for project environments other than: Microsoft Visual Studio GNU/GCC Borland C++Builder Starting The Utility Simply run the AutoCmpPersonGen.exe program from the installed location and you will be presented with an interface to provide the utility with the following information Product and Output location Specify QAC or QAC++ and the directory you wish the generated personality to be saved in. Note the name of the generated personality is AutoCmpPerson.p_c. Copyright 2007 Programming Research 15

16 Compiler Execution Information The compiler generator uses your compiler to run some tests and therefore needs to know how to invoke the compiler from the command line. Make sure you know the command string for invoking your compiler on a simple test.c file from the command line in order to enter the following information. Exe Command the command used to invoke the compiler. This may be as simple as lc or gcc, if your compiler recognises implicit include directories or interrogates the INCLUDE_PATH environment variable. In other cases the command may need to specify include paths explicitly, for example: lc i c:\lcc\include. Also it is possible that the compiler is wrapped into an IDE executable and requires a further command to invoke on the command line. For example Code Warrior piper.exe chc12.exe I C:\Program Files\Freescale\CW for HC12 V4.5\lib\hc12c\include. Ensure that you fully qualify the path to the compiler executable if it is not on your path. Cross Compiler If your compiler is a cross compiler and any executable generated on the command line cannot be run on the host machine, then check the option provided. Specify the Output, Define and Object flags for the compiler in question including the need for trailing whitespace if applicable. The output flag specifies the option required to generate a given.exe after compilation, the define flag specifies the option required to specify a particular pre-processor define from the command line, and the object flag is specifies the flag required to leave behind the object file created during compilation (note: this option can be blank if by default your compiler does not delete the object file). Specify the Order on the command line that these options need to be specified to the compiler. Note on some compilers the order needs to be exact, whereas others can accept options in any order. The resulting command string (including all options) will be displayed for your reference. Copyright 2007 Programming Research 16

17 Search Directories The Compiler Personality Generator will configure the include directories used by your compiler and needed during analysis. In order for the generator to discover these directories you need to provide starting points for where these will be located. The generator also looks at the compiler binary files and searches recursively through directory structures, so the best search directory to specify is the top level install directory for your compiler. The higher up the directory tree you specify, the better will be the resulting personality but also the longer it will take to generate; so avoid specifying C:\ or \usr. In the example above with the lcc compiler the directory structure is: And therefore the best specified search directories are: This can be a list of starting search directories as the include files can be located in multiple locations on disk Compiler Defines and Switches During the usage of your compiler, you may specify external defines and options so as to enforce a particular route through the pre-processing of system header files, or, for example, the enabling of exception handling or RTTI in C++. Because these options will affect the way your compiler behaves, the analysis engine needs to be aware of them so as to analyse the code in the same way. Specify any compiler defines or options either by comma separated values (note you do not need to repeat the d/-d for the defines that you specified earlier) or on separate lines. Click Next and you will see a summary screen of the options you supplied before clicking Finish. Copyright 2007 Programming Research 17

18 The generated personality should now be ready for use in your projects, however there may need to be some review or modification of it to handle very specific compiler based extensions. If you still encounter syntax errors when analysing your code, refer to Section 6 below Copyright 2007 Programming Research 18

19 6 Resolving Syntax Errors 6.1 Introduction Before attempting to review all the various analysis messages that QAC and QAC++ may generate, it is important to resolve syntax errors. Syntax errors are errors which indicate that the tool cannot perform basic parsing of the code. If the code can be successfully compiled, it is most likely that syntax errors generated by QAC or QAC++ can be resolved by further modification of the compiler or analyser personalities. Occasionally it may be necessary to resort to using substitute header files or modifying the source files themselves. 6.2 Which syntax errors must I resolve? Always address syntax errors in the order in which they occur within a translation unit. By resolving the first syntax error you will often correct subsequent syntax errors as well. Having resolved a syntax error you can re-analyse the file and reload it in the message browser using File/Refresh Warnings. 6.3 Using the Pre-processed Output When a compiler compiles, it goes through a pre-processing stage where macros and pre-processor directives are resolved. This results in a single unit of code referred to as a translation unit. Both QAC and QAC++ have the ability to send the pre-processed output to a file. Open up the Folder Parameters of the root folder and edit the Analyser personality by selecting the Edit button. This will bring up the analyser personality details. Select the Analysis Processing tab of the Analyser personality and then check the two boxes entitled Pre-Processed Output and Include filename and line numbers in preprocessed listing. Copyright 2007 Programming Research 19

20 Do not check the Only Perform Preprocessing Analysis check box for QAC++. Now, when you analyse, a.i file containing the pre-processed output will be produced in the output directory. This can be viewed by pressing the button from the toolbar or selecting View Preprocessed Source from the View menu. Preprocessed source code is particularly useful when reviewing warnings in header files and warnings which are generated within the expansion of macros. 6.4 Missing Include Files One of the most common syntax errors is the Cannot find include file warning. For QAC this is warning 818 1: #include "test.h" ^ ++ HARD ERROR ++: <=9=(0818) Cannot find test.h - Perhaps the appropriate search path was not given? and for QAC++ this is warning 34 #include "test.h" ^ ++ HARD ERROR ++: <=9=(0034) Cannot find include file 'test.h'. When this happens you need to ask yourself if this is a project header file or a system header file. If it is a project header file then the path needs to be added to the analyser personality; if it is a system header file, the compiler personality should be updated. 6.5 Handling Language Extension Keywords Many compilers, particularly embedded compilers extend the ISO C language with keywords such as interrupt, banked, sfr, export etc. in order to add extra functionality. There also some additional keywords in ISO-C99 which do not exist in ISO-C90 and are therefore not recognised by QAC (for example, inline _Bool). Various approaches are needed in order to enable such code to be parsed. In some cases, unrecognised keywords may be successfully parsed by simply ignoring them. This can be achieved by configuring a suitable macro which redefines the keyword to nothing. Here is an example of the inline keyword. This code will only compile under compilers that support the inline keyword and when we try to analyse it with QAC we get the following output. 1: inline int sum(int a, int b) ^ ++ HARD ERROR ++: <=9=(0926) [S] Expected: (, ; [ =. 2: { 3: return a + b; 4: } 5: The preprocessor can be used to remove the inline keyword completely which will have the affect of transforming the code into legal ISO C90 code. This is done by setting inline equal to nothing in the compiler personality. So in the system macros tab of the compiler personality we add inline= We can now analyse the code without any syntax errors. Copyright 2007 Programming Research 20

21 Some keywords are more complicated than the inline keyword to handle. Consider the interrupt and using keywords found in the Keil compiler. These are used as follows. unsigned int interruptcnt; unsigned char second; void timer0 (void) interrupt 1 using 2 { if (++interruptcnt == 4000) { /* count to 4000 */ second++; /* second counter */ interruptcnt = 0; /* clear int counter */ } } The additional keywords here are the interrupt and using keywords. What we need to do is to handle not just the keywords themselves but also the next token after interrupt (1) and the next token after using ( 2). This can be done using a magic macro definition called _ignore. By defining the following macros in the compiler personality interrupt=_ignore using=_ignore QAC will be able to parse the code without any problems since the pre-processor will remove the using and interrupt keywords but will also ignore the following tokens as well. You can find the details of other forms of _ignore in the QAC/QAC++ User Guide. The Compiler Personality Generator will identify potential keywords and handle as many of them as it can for you. However, there may be keywords it has not encountered before which may require extra configuration. If this is the case, please alert support@progrmamingresearch.com to the situation so that future versions of the Compiler Personality Generator can be extended to cover this case. Copyright 2007 Programming Research 21

22 6.6 Handling #pragma blocks in QAC It is possible to configure QAC to ignore code lying between certain types of #pragma. Suppose your compiler supports the following syntax: #pragma beginasm mov eax,ebx #pragma endasm In the analyser personality you will find a tab called Pragma Blocks where you can insert beginasm,endasm. This will make QAC ignore the embedded assembler and prevent problematic syntax errors. Copyright 2007 Programming Research 22

23 6.7 Handling bool and wchar_t in QAC++ bool and wchar_t are recognised as types in the ISO C++ standard. A problem can arise with QAC++ since it always treats bool and wchar_t as keywords, whereas some compilers do not. Take for example a compiler that does not treat bool as a keyword. You may find a definition of bool as a typedef in the system headers. typedef unsigned char bool; If we try to analyse this code using QAC++ we will get a syntax error as shown. 1: typedef unsigned char bool; ^ ++ HARD ERROR ++: <=9=(0014) Syntax error before ;. QAC++ thinks that you are trying to create a typedef for a basic type. The way to resolve this issue is to use the preprocessor of QAC++ to redefine bool into something else, for example bool. Since bool is not a keyword, the typedef is now valid ISO C++. Similarly wchar_t is treated in QAC++ as a keyword by default, but this can be tailored in the Compiler Personality, Data Types tab. Copyright 2007 Programming Research 23

24 Copyright 2007 Programming Research 24

25 6.8 Re-coding to eliminate syntax errors Sometimes you will come across a language construct that QAC or QAC++ can not handle. In this case it is necessary to re-code the problematic code or encapsulate it in a macro. For example, suppose your compiler supports a syntax similar to operator but using an exclamation mark (!) instead. int x! 0x QAC will not be able to parse this code and there is no way of getting rid of the exclamation mark using the preprocessor. Trying!=_ignore will not work. In these circumstances it may be necessary to introduce some alternative coding of the form: #ifndef NO_SUPPORT_FOR_AT_SYNTAX #define VAR_AT_ADDRESS(m)! m #else #define VAR_AT_ADDRESS(m) #endif int x VAR_AT_ADDRESS(0x ); Now all we need do is to define the macro NO_SUPPORT_FOR_AT_SYNTAX in the QAC compiler personality. The problematic language extension disappear when analysing but will still be used when compiling. This method of fixing syntax errors is a last resort, but it is always wise to encapsulate compiler extensions in this way as good programming practice. Copyright 2007 Programming Research 25