Note: this topic applies only to Together products with support for C++.
The file $TOGETHER_HOME&/lib/preinclude.inc provides the definitions of macros used in your C++ source code to C++ projects in Together. The macros used can be defined in the various external libraries you use, or in some internal company headers that, although external to the project structure, are still part of the source code that Together should process into diagrams.
If these library headers are not included in the Together project resources (and thus are not parsed), Together cannot perform the substitution of the macros it meets during parsing. This leads either to error messages, or to some desired visual information not showing up from the resulting diagrams.
The latter occurs if some constructs that are part of the object model have been defined with macros-- class member declarations for example. If no substitution is defined for it, Together cannot properly recognize such constructs and thus cannot properly display them in diagrams.
On the other hand, including all library sources into a Together project is not advisable because that makes the project overly large and rather clumsy, and usually leads to dramatic decrease in parsing speed. To address this problem, preinclude.inc is provided so that you can more narrowly define what macro substitutions should be used by Together when parsing the project.
The default preinclude.inc addresses the problems that can occur on parsing a number of libraries commonly used by C++ developers. Sets of defines provided for:
Microsoft Windows
Microsoft C++
Microsoft Foundation Classes (MFC) library
COM
ATL
Borland C++ version 5.0
Borland C++ Builder
There are additional wrapper macros that are used for controlling which of these sets of defines are "enabled" currently via #ifdef. These are:
TS_PREINCLUDE_MICROSOFT_WINDOWS
TS_PREINCLUDE_MICROSOFT_COM
TS_PREINCLUDE_MICROSOFT_VISUAL_C
TS_PREINCLUDE_ATL
TS_PREINCLUDE_BORLAND_CPP
TS_PREINCLUDE_BORLAND_CPP_BUILDER
(See the comments in the preinclude.inc file)
It is of course impossible to anticipate which of the above you actually use. Neither is it possible to include something for every conceivable library, or anything at all for your own company standard headers. Therefore, some resetting of C++ configuration options and some hand-tuning of the preinclude.inc will most likely be necessary before you begin using Together for C++ projects.
Note that some "widely used libraries" may use macros with identical names but different definitions. For example, MFC and OWL both define "BEGIN_MESSAGE_MAP" in completely different ways and that will cause problems with parsing.
Before using Together for C++ projects, you should make sure that the wrapper macros for the libraries you use are defined in your C++ configuration options, and those for the libraries you don't use are "un-defined". If you don't do this, some macro names will be duplicated but have different definitions, which will cause Together to display numerous error messages while parsing C++ source code files.
To define or un-define wrapper macros:
Choose Options | Default to display the Default Options dialog.
Select the Source Code page
Expand the C++ node on the options tree and click Define.
Remove the names of wrapper macros for libraries
you don't use from the value string.
If the name of the wrapper macro for a library you do
use is not present in the value string, add it to the string. Observe
the all-upper case naming convention and be sure to delimit all the
macro names with a semi-colon (;).
Click OK to close the dialog.
Note that the above configuration can be done at the Default or the Project level. See the Configuring Together topic for information about multi-level configuration.
If you encounter any problems with recognizing macros when using the default configuration, you either need to make some headers visible for Together in the search paths (File | Project Properties | Advanced - Search/Classpath tab), or write some new macro definitions in the preinclude.inc file.
You can either tune the global copy of the preinclude.inc file (in ./lib), or you can make a project-local copy of the preinclude.inc file (i.e. placed in the same directory as your project .tpr file). The project-local file is loaded after the global copy so that all defines are merged, but project-local versions may redefine (override) the global defines having the same names.
There are different approaches to writing the definitions. The first way is to use macro definitions exactly as they are used in the library. However, this is often unnecessary because the original definitions can be quite complex and yet really have no meaning for Together. Remember that your real goal is to cause Together to:
parse the sources without error messages, and
display all desired information on the diagram.
This means that macros can often be defined just to nothing if the corresponding constructs are not supposed to have any visual feedback on the diagram. Together simply skips such macro declarations.
Where you expect to get visual feedback from some macro declaration, you must be more accurate and you must define some non-empty substitution. You can use the full library definition if that's what you need to see, or you can simplify the definition to bring in only the item(s) you want displayed in the diagrams. Note that any substitution to these definitions made for Together in preinclude.inc does not affect the compilation of your sources in any way. Your compiler will use the real library headers.
To illustrate the above, refer to the macro sets provided in the default preinclude.inc file for MFC which are controllable via wrapper macro TS_PREINCLUDE_MICROSOFT_VISUAL_C:
MFC_MACROS_SHOW_EXPANDED (complete as in MFC)
MFC_MACROS_SHOW (show as functions)
Otherwise empty
The file $TOGETHER_HOME$/config/resource.config (version 3.x and above) contains definitions of file types for Together and sets of extensions corresponding to the file types.
For C++ sources and headers the following definitions are specified by default:
# -- C++ --
resource.file.cpp_source.extension.1 = "cpp"
resource.file.cpp_source.extension.2 = "c"
resource.file.cpp_source.extension.3 = "CPP"
resource.file.cpp_source.extension.4 = "C"
...
resource.file.cpp_header.extension.1 = "hpp"
resource.file.cpp_header.extension.2 = "h"
resource.file.cpp_header.extension.3 = "HPP"
resource.file.cpp_header.extension.4 = "H"
...
If you add more extensions to this section of the configuration file, corresponding files will also be recognized as C++ sources and headers.
The default file extensions for generated header and source files are declared in the following properties in $TOGETHER_HOME$/config/cpp.config:
codegen.cpp.declaration_file_ext = "h"
codegen.cpp.definition_file_ext = "cpp"
To generate files with different extensions, you need change the value for these properties. You can do this in the Options dialog: choose Options | [level] | Source Code | C++ and edit the options labelled Extension of generated C++ header file and Extension of C++ definition file respectively.
Code generation blueprints are not used any more in Together versions 4.x and higher (however, blueprints are still supported). Instead of the blueprints, Together now excercises a different approach - code templates, which are a kind of pre-defined forms to be filled in for a particular case. C++ code templates are stored in $TOGETHER_HOME$/templates/Cpp. See User's Guide: Using Code Templates and Adding Custom Code Templates.
For the sake of the backward compatibility, Together still supports codegen blueprints of the older versions. The users of the older versions can refer here for detailed information.
The above replaces the following version 2.x properties (from
config.properties file) for C++:
## parser.cpp.declaration_file_exts = ...
## parser.cpp.definition_file_exts = ...
The Blueprint options for C++ enable you to customize how Together generates C++ code for many diagram elements (such as default class naming) and modeling constructs (such as default Association). You can customize these at any of the available levels (see the Configuring Together topic for information about multi-level configuration.)
To begin configuring C++ blueprints:
Choose Options | [level] from the main menu to display the Options dialog for the configuration level you select.
Select the Source Code tab and expand the C++ node. Scroll the pane if necessary to reveal the Blurprints node.
Expand the Blueprints node for access to the codegen blueprint options.
Set the blueprint options as needed to meet your requirements. For example, the default return type for new operations added to a class is void. You can change the value to specify a different return type. Or you can change the default declaration for a class. Studying the options will quickly show you what kinds of things you can change.
Tip: Be sure that all your customizations result in valid C++ syntax for the compiler you use.
When the first symbol in a block comment is "#"... for example /*# ... */ -the parser (java/c++/idl) tries to recognize this as pure member. If it cannot find correct member declaration there it can report an error.