![]() |
![]() |
![]() |
![]() |
![]() |
Executing CPP2SDL
Normally, CPP2SDL is automatically invoked by the SDL Analyzer as part of the make process. Input header files and tool options are then specified in the Organizer. However, CPP2SDL may also be executed as a stand-alone tool from a command shell, and in that case input headers and tool options are given as command line options.
This section begins with a description of the integration with the Organizer and the Analyzer. Then how to execute CPP2SDL from the command line is described. Finally, follows a section on how to run the tool through the PostMaster.
Execution from the Organizer
The most common way to execute CPP2SDL should be from the Organizer. In fact CPP2SDL will be started automatically by the Analyzer once for each import specification symbol it finds in the Organizer view (see Import Specifications to learn about import specifications). The Analyzer executes CPP2SDL by means of the PostMaster as described in Execution from the PostMaster. All messages that are output during the execution will be printed in the Organizer Log Window.
Example 80 : Executing CPP2SDL from the Organizer
Consider a simple SDL system with one block and one process that needs to access some C++ declarations. At system level certain declarations of the C++ header file general.h is used, and at process level declarations of the files f1.h and f2.h are needed. Figure 167 below shows how the Organizer view of this SDL system could look like.
When this system is analyzed, the Analyzer will execute CPP2SDL once for the file general.h, and once for the files f1.h and f2.h. The result of the first translation is a set of SDL declarations that are injected at system level, and thus will be accessible in all scopes. The result of the second translation is a set of SDL declarations that are injected at process level and thus are not accessible in the system or in the block scope.
Adding Import Specifications to the Organizer view
The first step in accessing C/C++ declarations from SDL is to insert a PR symbol at the place in the SDL specification where the C/C++ declarations are to be used. The PR symbol represents the inclusion of the SDL PR that is the translation of the C/C++ declarations.
To specify that this should be an import specification, double-click the PR symbol either in the Organizer or in the SDL Editor to open the Edit Document dialog. In the dialog it is possible to select either C Import Specification or C++ Import Specification.
An import specification can be edited manually by means of the Text Editor (see Import Specifications to learn about import specifications). However, an import specification can also be edited in the CPP2SDL Options dialog described below.
After adding an import specification it is necessary to specify which C/C++ header files are to be translated. This is done by selecting the import specification in the Organizer and then use the Add Existing and Add New commands to select or create C/C++ header files respectively.
Setting CPP2SDL Options in the Organizer
Required options to CPP2SDL may be specified in the Organizer for each import specification by using the CPP2SDL Options dialog. This dialog may be opened from the menu that appears when the right mouse button is pressed on an import specification symbol. Figure 168 shows this dialog.
The fields and buttons of the CPP2SDL Options dialog correspond directly to the command line options described in Command Line Options:
- Language
- These radio buttons select the input language. If C is selected, CPP2SDL will be executed in C mode, i.e. as with the -c command line option.
- Dialect
- These check boxes determine what dialects to support in the input, and correspond to the -dialects command line option. If no check-boxes are marked, the ANSI C/C++ dialect is supported.
- Run-Time Type Information
- This check box should be set if Run-Time Type Information (RTTI) is available in C++ and should be supported in the SDL translation. It corresponds to the -rtti command line option.
- Allow object slicing
- This check box should be set if object slicing should be supported in the SDL translation. It corresponds to the -slicing command line option.
- Recognize SDL sorts in input
- This check box should be set if SDL sorts should be recognized in the input. It corresponds to the -sdlsorts command line option.
- Preprocessor
- This field is used to specify the preprocessor to use for preprocessing the input. It corresponds to the -preprocessor command line option. This field also has a browse button that makes it possible to select the preprocessor from a file selection dialog.
- Preprocessor options
- This field should contain the options to the preprocessor. It corresponds to the -cppoptions command line option.
- Pointer, Array, Template, Keyword, Incomplete, Underscore
- Do not use full path in include in generated header file
- Checking the box will prevent usage of path in the includes and make it easier to move files to other directory locations. It corresponds to the -noabsolutepath command line option.
- Generate SDL representations for fundamental types
- This check box should be set if SDL representations for fundamental C/C++ types should be included in the translation. It corresponds to the -generatecpptypes command line option.
- Only generate class pointer types when necessary
- If this check box is set, CPP2SDL will optimize the generation of class pointer types. It corresponds to the -optclasspointers command line option.
Execution from Command Line
CPP2SDL is invoked from the command prompt by the command:
cpp2sdl [options] <C/C++ header files>Unless the -post option is set, all messages that are output by the tool, e.g. errors and warnings, will be printed on the standard error stream (stderr).
CPP2SDL will translate the declarations in the specified C/C++ header files, or a subset of these declarations if a suitable import specification is used (see Import Specifications). The resulting SDL declarations will be saved in a file called name.pr, where name is the name of the import specification used. If no import specification is used, name will be the name of the first input header file.The output file will be placed in the same directory from where CPP2SDL is executed.
There is a possibility when running in batch mode to be able to change the CPP2SDL options used in an SDL system. See Batch Facilities.
Normally CPP2SDL options are saved in an import (".is") file. These options will in batch be superseded by CPP2SDL options given in a batch ".sdt" option file.
Command Line Options
The command line options recognized by CPP2SDL are listed and explained below. Note that an option may be abbreviated as indicated by the underlined part of the option name.
- -append
- Append the generated SDL declarations to the file that is specified with the -output option. If that file does not exist, this option will be ignored and CPP2SDL will create a new file for the output as usual.
- -c
- Execute in C mode. CPP2SDL will assume that no C++ specific constructs are encountered in the input headers. If this assumption does not hold, the result of the translation is undefined. See Special Translation Rules for C Compilers for a detailed description of translation rule modifications that are caused by using this option.
- -cppoptions <optionsstring>
- -dialects <dialect> <dialect> ... <dialect>
- -errorlimit <number>
- -extsyn
- -generatecpptypes
- Include SDL representations for fundamental C/C++ types in the translation. See SDL Library for Fundamental C/C++ Types for more information about what actually is generated when this option is used.
- -help
- -importspecification <file>
- Use the specified file as import specification for the translation. Import specifications are described in Import Specifications.
- -noabsolutepath
- -nocheckinput
- -nodepend
- Do not translate depending declarations when using an import specification. Only the identifiers that are explicitly present in the import specification will be translated. If this option is set, CPP2SDL cannot guarantee that the resulting set of SDL declarations is complete and consistent. See Import Specifications for more information.
- -noinclude
- Ignore definitions #included into imported header file by the preprocessor. Only definitions that are explicitly present in the original header file will be translated, and may be some others if the -nodepend option is not set.
- This option allows having several separate import specifications for several imported header files, even if these files include each other. Although, conflicts in SDL are still possible if the same depending definitions are imported for different import specifications. So, to achieve the best result, the -noinclude option should often be used together with the -nodepend option. Both options are not present in "CPP2SDL Options..." dialog window and should be specified directly in the *.is file.
- To avoid build errors when using several import specifications for several header files that include each other, do not forget to use protection macros #ifndef-#define-#endif in the header files.
- -novariables
- Do not generate external variables. This option is needed since the rules for where SDL allows declarations of external variables are more restrictive than for other declarations. For example, SDL does not allow external variables declared at system or block level. If this option is used, CPP2SDL will output a warning if it finds a construct that otherwise would be translated to an external variable.
- -optclasspointers
- Optimize the generation of class pointer types so that they are only generated when they appear in the input headers. If this option is not used, CPP2SDL will automatically generate a pointer type to all translated classes. Read more about this in Classes, Structs and Unions.
- -output <file>
- Write the resulting SDL declarations to the specified file. If the
-append option is set, the result will be appended to the file. Otherwise a new file will be created, overwriting an existing file with the same name, if any.- Note that all files that CPP2SDL generates will be placed in the same directory as the generated SDL/PR file.
- -post
- Start CPP2SDL as a PostMaster client waiting for requests from the PostMaster. The PostMaster messages that are handled by CPP2SDL are described in Execution from the PostMaster.
- -prefix "ptr=<string> arr=<string> keyword=<string> incomplete=<string> tpl=<string>"
- -preprocessor <executable>
- Use the specified executable for preprocessing the input headers. The executable should be a preprocessor or C/C++ compiler that is supported by CPP2SDL:
- `cl' (Microsoft Visual C/C++ Compiler), in Windows.
- `cpp' (C/C++ Preprocessor), on Unix.
- `cc' and `CC' (Sun Workshop C and C++ Compilers), on Unix.
- `gcc' and `g++' (GNU C and C++ Compilers), on Unix.
- If this option is not used, CPP2SDL will attempt to use `cl' in Windows, and `cpp' on Unix.
- Note that CPP2SDL uses name matching of the specified filename, with the file name extension stripped, to determine what preprocessor or compiler to use for preprocessing. If the specified name does not match the name of any supported preprocessor or compiler on the current platform, CPP2SDL will attempt to call the executable like this:
<executable> <options> <input file> <output file>
<options> are the option string specified with the -cppoptions options.
If this call fails, CPP2SDL does not know how to preprocess the input headers and terminates.
If you want to preprocess the input headers using a preprocessor that is not supported by CPP2SDL, you can write a simple shell script that wraps the call to the desired preprocessor. The script should conform to the call style that CPP2SDL uses for unknown preprocessors. Then execute CPP2SDL, using the -preprocessor option to specify the script as the preprocessor to use.
- -ref
- Include source references in the generated SDL. The format of these source references is described in Source and Error References.
- -rtti
- Assume Run-Time Type Information, and support dynamic casting. See Run-Time Type Information and Dynamic Cast for more information what this means.
- -sdlsorts
- Recognize SDL sorts in input. CPP2SDL will translate C/C++ types that are prefixed with `SDL_' to the corresponding SDL sort. Refer to SDL Sorts in C/C++ for an example on how this feature can be used.
- -slicing
- Generate SDL cast operators to support slicing of C++ objects. See Type Compatibility between Inherited Classes for more information.
- -sortmembers
- -suffix "uscore=<string>"
- -targetdir <directory>
- Set the target directory for generated files. CPP2SDL produces one single header file which includes all the header files that are to be translated. If this option is used, this generated header file is placed in the specified target directory. Otherwise the file will be placed in the same directory as the generated SDL/PR file.
- -version
Example 81 : Executing CPP2SDL from the command line
% cpp2sdl -preprocessor /usr/ccs/lib/cpp -output result.pr -prefix "ptr=p arr=a" -rtti -ref input.hThis command will translate the input header input.h to SDL and write the resulting SDL declarations to the file result.pr. The specified preprocessor `cpp' will be used to preprocess the input. If the input contains pointer or array types, the corresponding SDL names will be prefixed with `p' and `a' respectively. Source references to the declarations in input.h will be generated by CPP2SDL, and Run-Time Type Information is assumed so that dynamic cast operators are generated.
Execution from the PostMaster
As mentioned above, CPP2SDL may be started as a PostMaster client by using the -post option at the command line. As a PostMaster client, CPP2SDL will handle two different PostMaster events.
The reception of a SESTOP event has the expected behavior; CPP2SDL ceases to be a PostMaster client and terminates.
The SECPP2SDLCOMMAND event has an option string as argument. The event will cause CPP2SDL to execute according to the options specified in that string. The format of the option string is the same as when CPP2SDL is executed from the command line (see Execution from Command Line). All messages that are output by the tool will be broadcast to the PostMaster.
After the execution of a SECPP2SDLCOMMAND event a reply is sent:
SECPP2SDLCOMMANDREPLY <#errors> <#warnings> <status>
The <#errors> and <#warnings> arguments tell the number of errors and warnings that occurred during the translation, and <status> is a text string with the same information in a more readable form.
Example 82 : Executing CPP2SDL from the PostMaster
A single PostMaster may be started with this command:
% sdt -noclientsThen CPP2SDL is started as a PostMaster client:
% cpp2sdl -post &CPP2SDL is now waiting for requests to come from the PostMaster. By using for example the SERVERPC application, events can be sent to it.
% serverpc 58000 58101 "-rtti -ref input.h"58000 is the tool id of CPP2SDL, and 58101 is the event id for the SECPP2SDLCOMMAND event. As a result the following reply event could for example be received:
SECPP2SDLCOMMANDREPLY 0 2 "0 errors and 2 warnings"
Finally, CPP2SDL is terminated using the SESTOP event (id 58303):
% serverpc 58000 58303
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |