Commit 397b7661 authored by Kristof Szabados's avatar Kristof Szabados
Browse files

change to asciidoc.


Signed-off-by: Kristof Szabados's avatarKristof Szabados <Kristof.Szabados@ericsson.com>
parent e511b148
......@@ -6,5 +6,7 @@ bin.includes = META-INF/,\
icons/,\
toc.xml,\
docs/,\
bin/
bin/,\
schema/
bin.excludes = docs/Eclipse_Designer_userguide/
\ No newline at end of file
= Introduction
:toc:
:figure-number: 0
== Overview
This document describes the general workflow and use of the TITAN Designer for the Eclipse IDE plug-in.
The TITAN Designer plug-in provides support for:
* creating and managing projects;
* creating and working with source files;
* building executable code;
* automatic analysis of the build results;
* remote build.
== Target Groups
This document is intended for system administrators and users who intend to use the TITAN Designer plug-in for the Eclipse IDE.
== Typographical Conventions
This document uses the following typographical conventions:
* *Bold* is used to represent graphical user interface (GUI) components such as buttons, menus, menu items, dialog box options, fields and keywords, as well as menu commands. Bold is also used with ’+’ to represent key combinations. For example, *Ctrl+Click*
* The "/" character is used to denote a menu and sub-menu sequence. For example, *File / Open*.
* `Monospaced` font is used represent system elements such as command and parameter names, program names, path names, URLs, directory names and code examples.
* `*Bold monospaced font*` is used for commands that must be entered at the Command Line Interface (CLI), For example, `*mctr_gui*`
== Installation
For details on installing the TITAN Designer for the Eclipse IDE plug-in, see the Installation Guide for TITAN Designer and TITAN Executor for the Eclipse IDE.
== Reporting Errors
The following information should be included into trouble reports:
* Short description of the problem.
* What seems to have caused it, or how it can be reproduced.
* If the problem is graphical in some way (displaying something wrong), screenshots should also be included.
* If the problem generates some output to:
* TITAN Console
* TITAN Debug Console
* If the Error view contains some related information, that should be copied too.
Before reporting a trouble, try to identify if the trouble really belongs to the TITAN Designer for the Eclipse IDE plug-in. It might be caused by other third party plug-ins, or by Eclipse itself.
Reporting the contents of the Consoles and the Error log is important as TITAN consoles display the commands executed and their results and the Error log may contain stack traces for some errors. To identify relevant log entries the easiest way is to search for classes whose name starts with "org.eclipse.titan". The location on which the Error Log view can be opened can change with Eclipse versions, but it is usually found at *Window / Show View / Other… / PDE Runtime / Error Log* or *Window / Show View / Other… / General / Error Log*.
= Contents of the Outline View
:toc:
:figure-number: 121
This section presents how TITAN Designer plugin is integrated in the Outline view.
It is often useful to get a higher level view of the actual TTCN-3/ASN.1 module, especially if the module is thousands of lines long. The Outline view provides a solution to this problem and makes it easy to navigate inside TTCN-3/ASN.1 modules. If an element is selected in the Outline view the editor jumps to the position of the selected element in the source code.
The Outline view consists of two main parts. The toolbar and the actual tree view.
== The Tree
The Outline view contains a tree, representing the structure of the current TTCN-3/ASN.1 module. Each element is represented in the Outline view by an icon that makes the type of the item easily recognizable and by a text that shows the name and the type of the element or in case of structures with formal parameters their calling convention.
image::images/10_F107.png[title="Outline view"]
The root of the tree always represents the current TTCN-3/ASN.1 module and optionally the list of module importations if there were any. The structure of the underlying levels shows data structure hierarchies, type definition groupings etc.
== The Toolbar
With the functionality available through the toolbar buttons, the elements of the Outline view can be ordered, restructured or the visibility of specific elements can be changed. In the following subsections these toolbar actions will be described.
=== Sorting Elements
By default the elements in the Outline view are in the order of their position in the TTCN-3/ASN.1 module.
image::images/10_F108.png[title="Sorted by position"]
The elements can be sorted alphabetically with toggling the image:images/sortalphabetically.png[sort_alphabetically] icon.
image::images/10_F109.png[title="Sorted alphabetically"]
=== Categorizing Elements
It is possible to order the outline view t categorizes the elements to be displayed before sorting them. This function is useful if one is only interested records, or functions as this way functions, types, module parameters will be found together in the outline view.
Categorizing of the outline elements is possible with toggling the image:images/icon_01.png[sort_alphabetically] icon.
image::images/10_F110.png[title="Categorized and sorted alphabetically"]
=== Grouping
By default the Outline view does not show the group hierarchies in the module, as the groups do not have any effect on scoping. However they can be used to group semantically similar functions, type definitions etc. To make group hierarchies visible in the Outline view the image:images/outlinegroup.png[outline_group] button can be used.
image::images/10_F111.png[title="Grouping"]
=== Filtering Elements
If there are lots of elements in the Outline view it can be hard to find the appropriate one, so it is possible to filter the elements based on their types, using the filtering buttons in the toolbar. Filtering is additive, more filters can be active at the same time.
Filters for TTCN-3:
Hide functions (image:images/filterfunctions.png[filter_functions])
Hide templates (image:images/icon_02.png[filter_02])
Hide types (image:images/icon_03.png[filter_03])
== Outline View Icons
image::images/10_F112.png[title="Outline view icons for TTCN-3 and ASN.1"]
Pitfalls
NOTE: As long we have to re-parse the whole TTCN-3 and ASN.1 modules on a change the outline view will always have to reinitialize all of its contents. This means, that all structures actually open at such a change will b closed (in fact the old structure will be deleted and a new will be created).
= Extensions to the Project Explorer
:toc:
:figure-number: 128
[[filtering-resources-from-the-view]]
== Filtering Resources from the View
It is possible to hide excluded resources from the Project explorer view.
To achieve this go to *View Menu* / select *Customize View…*
image::images/11_F113.png[title="View Menu"]
image::images/11_F114.png[title="Customize View…"]
image::images/11_F115.png[title="The Available Customizations window"]
On the *Available Customizations* window there are two exclusion filters provided by the Designer plug-in:
* TITAN working directory.
+
When selected the working directories of the projects will be filtered from the *Project Explorer* view.
* TITAN excluded resources.
+
When selected all resources excluded from the build on some way, will be filtered from the view. For more information on how a resource can be excluded from build please refer <<2-getting_started.adoc#enabling-titan-decorations, here>>.
By default the "TITAN working directory" filter is selected.
= References
[[_1]]
* [1] link:https://github.com/eclipse/titan.core/blob/master/usrguide/installationguide.adoc[Installation guide for TITAN TTCN-3 Test Executor]
[[_2]]
* link:https://github.com/eclipse/titan.EclipsePlug-ins/blob/master/Eclipse_installationguide.adoc[Installation Guide for TITAN Designer and TITAN Executor for the Eclipse IDE]
[[_3]]
* [3] link:https://github.com/eclipse/titan.core/blob/master/usrguide/userguide/README.adoc[User Guide for TITAN TTCN-3 Test Executor]
[[_4]]
* [4] link:https://github.com/eclipse/titan.core/blob/master/usrguide/referenceguide/README.adoc[Programmers Technical Reference for TITAN TTCN-3 Test Executor]
[[_5]]
* [5] link:https://github.com/eclipse/titan.core/blob/master/usrguide/releasenotes.adoc[Release Notes for TITAN TTCN-3 Test Executor]
[[_6]]
* [6] TTCN–3 Style Guide 1/0113-FCPCA 101 35
[[_8]]
* [8] TTCN–3 Naming Convention ETH/R-04:000010
[[_9]]
* [9] link:https://www.etsi.org/deliver/etsi_es/201800_201899/20187310/04.05.01_60/es_20187310v040501p.pdf[Methods for Testing and Specification (MTS);The Testing and Test Control Notation version 3.Part 1: Core Language European Telecommunications Standards Institute. ES 201 873-1 Version 4.5.1, April 2013]
[[_10]]
* [10] link:https://www.etsi.org/deliver/etsi_es/201800_201899/20187304/04.04.01_60/es_20187304v040401p.pdf[Methods for Testing and Specification (MTS);The Testing and Test Control Notation version 3.Part 4: TTCN–3 Operational Semantics European Telecommunications Standards Institute. ES 201 873-4 Version 4.4.1, April 2012]
[[_11]]
* [11] link:https://www.etsi.org/deliver/etsi_es/201800_201899/20187307/04.05.01_60/es_20187307v040501p.pdf[Methods for Testing and Specification (MTS);The Testing and Test Control Notation version 3.Part 7: Using ASN.1 with TTCN–3 European Telecommunications Standards Institute. ES 201 873-7 Version 4.5.1, April 2013]
= Abbreviations
ASN.1:: Abstract Syntax Notation One
GCC:: GNU Compiler Collection
GUI:: Graphical User Interface
HC:: Host Controller
IDE:: Integrated Development Environment
IP:: Internet Protocol
MC:: Main Controller
MTC:: Main Test Component
PTC:: Parallel Test Component
SUT:: System Under Test
TCP:: Transmission Control Protocol
TTCN–3:: Tree and Tabular Combined Notation version 3 (formerly)Testing and Test Control Notation (new resolution)
TTCNPP:: TTCN Preprocessable (file)
TTCNIN:: TTCN Includable (file)
URL:: Universal Resource Locator
= Getting started
:toc:
:figure-number: 0
This section explains how to setup Eclipse to access every feature provided by TITAN Designer.
== The TITAN Editing Perspective
TITAN Designer provides its own perspective to Eclipse. This is a layout of visual elements that provides a good environment for working with TITAN. This layout is a starting point, since users can create their own layout in Eclipse, to set the best working environment for themselves.
Open the TITAN Designer perspective by opening *Window / Open Perspective / Other…*.
In the pop-up window select *TITAN Editing*.
image::images/2_F1.png[title="Opening a perspective"]
image::images/2_F2.png[title="Selecting the TITAN Editing perspective"]
The perspective is divided in three fields. Figure 3 TITAN Editing Perspective shows the default layout.
The tab on the left side is the Project Explorer view. This is a navigator where projects can be managed; for example, opened, renamed, or closed. Files can be added or removed from a project and so on.
The biggest pane of the perspective is the editing area (upper right). Here the code can be edited using the provided source code editors (or built-in text editors), once a file had been opened.
The four tabs at the bottom of the picture open the following views:
* The Problems view (see <<7-editing_with_titan_designer_plugin.adoc#mark-occurrences, here>>) displays information about problems found in the project. The problems reported can be ordered using several criteria (see <<8-contents_of_the_problems_view.adoc#grouping-of-problems, here>>).
* The Console view contains the commands executed and their output; Consoles only appear if there is something to display. The Console view has two sub views (TITAN console and TITAN Debug console, respectively); by default only one of both is displayed in the pane. The hidden sub view can be displayed by clicking on the display icon on the right of the pane.
* The TITAN console displays the commands executed by the parts of TITAN Designer and their results.
* The TITAN Debug console holds special debug related information for the plug-in developers. If something strange happens this might hold additional information that the user can include in his trouble report.
+
NOTE: The contents of this view have no effect on the work of the user.
* The Progress view contains information about the progresses of Eclipse related operations. Lengthy operations (for example building, remote building or the first on-the-fly build pass) always provide information to the user about their progress. Operations in general can be canceled in this view, provided that cancellation is allowed.
* The Tasks view contains information extracted from the projects in a sorted manner. The contents of this view differ from the contents of the Problems view in that they are usually not errors, but TODO or FIXME like notations. This view is described in detail <<9-contents_of_the_tasks_view.adoc, here>>.
image::images/2_F3.png[title="TITAN Editing Perspective"]
== Enabling TITAN Actions on the Toolbar
TITAN Actions or Change Set Operations are commands (apart from those used in the build process) that can be executed on TTCN-3 files.
The TITAN Actions are enabled by checking the *Change Set Operations* submenu on the tab *Tool Bar Visibility* after selecting *Windows / Customize Perspective* (see Figure 4).
image::images/2_F4.png[title="Enabling Titan Actions or ChangeSet Operations on the Toolbar"]
Enabling TITAN Actions will add a new toolbar with the TITAN Actions commands described below to the available ones:
image::images/2_F5.png[title="TITAN Actions commands"]
The command `Check syntax` checks the selected files for syntactical errors; no other operation is performed. When a folder is selected, the check is performed for all the files in the folder. The command is only available if at least one file is selected.
The command `Check semantics` checks the selected files both syntactically and semantically; no other operation is performed. When a folder is selected, the check is performed for all the files in the folder. The command is only available if at least one file is selected.
The command `Check compiler version` displays the version of the compiler.
The command `Generate Test Port skeleton` generates a test port skeleton from the selected TTCN-3 file. The command is only available if there is exactly one selected file in the project.
The command Convert XSD files to TTCN-3 takes as input the files selected by the user, and converts them into TTCN-3 files. As for the output the user is asked to select a folder, where the newly created files will be written to.
The output of the commands is written to the TITAN Console. Commands are executed regardless of the file properties; for example, the selected file will be syntactically or semantically checked even if it is excluded from the build process.
== Enabling TITAN Shortcuts
TITAN Shortcuts appear in the *File/New* menu and are used to open a new ASN.1 module, a configuration file, a TITAN project or a TTCN-3 module, respectively.
The TITAN Shortcuts are enabled by checking the appropriate box on the right pane of the Shortcuts tab after selecting *Windows / Customize Perspective* (*Figure 6*). The boxes are checked by default.
image::images/2_F6.png[title="Enabling the TITAN Shortcuts"]
[[enabling-titan-decorations]]
== Enabling TITAN Decorations
Decoration here means a string added to a project, folder or file name or a picture overlapping the icon of the resource to provide the reader with additional information.
The image:images/check.png[check] mark on the top right corner of a project’s icon means the project has been built and the binaries are up to date. If the plug-in detects the modification of a non-excluded file or folder inside the project, the check mark will disappear.
Decoration after a project name shows whether the `Makefile` has been automatically generated. If it has, the corresponding command line switches are displayed between brackets; for example, `[ -s ]` for single mode. No additional text is displayed if the `Makefile` has been manually generated (not even the brackets).
Decoration after a folder name indicates that the folder is used as a central storage (`[ centralstorage ]`) or the folder is excluded from build (`[ excluded by X]`). If both are true, `[ excluded by X centralstorage ]` is displayed.
Decoration after a file name denotes exclusion from build. Files excluded from build are marked `[ excluded ]`.
Decoration is enabled by checking the *TITAN Decorator* box after selecting *Windows / Preferences / General / Appearance / Label decorations*; see the figure below.
image::images/2_F7.png[title="Enabling TITAN Decoration"]
NOTE: Decorations are extending the information displayed for elements. As there can be several decorations extending an element, the texts shown above might not be the only ones displayed.
== Excluding resources
The possible reasons for a resource being excluded from build are as follows:
* Excluded by user:
+
These resources were explicitly excluded from the build by the user. (For more information refer <<4-managing_projects.adoc#excluding-files-and-folders-from-the-build-process, here>>)
* Excluded as working directory:
+
The working directory by definition is excluded from the build process, in order to make sure, that source files and generated file do not mix.
* Excluded by regexp:
+
The names of these resources was matching one or more exclusion regular expressions provided on the *Excluded resources* preference page (for more information refer <<3-setting_workbench_preferences.adoc#excluded-resources,here>>.)
* Excluded by convention:
+
On the Eclipse platform if the name of a resource (either a file or a folder) starts with a dot, it indicates that the resource is some special resource used by one of the plug-ins exclusively. All other plug-ins should exclude these files from their operation; they should not be regarded as part of the project by any plug-in other than its creator.
NOTE: When either the excluded resources or the working directory filter is active, it is indicated by the projects being decorated with the "[filtered]" decoration too. For more information on these filters please refer <<11-extensions_to_the_project_explorer.adoc#filtering-resources-from-the-view, here>>.
= Converting Existing Projects
:toc:
:figure-number: 87
In the TITAN toolset we are supporting 3 different tools/project handling principles at this time: Makefiles, mctr_gui projects and Eclipse projects. Before going into detail on how to convert one of the first two into an Eclipse project, we should review the features offered by these tools to work with projects.
== The Construction Principles of Projects
=== Makefile
Makefiles support the following ways of working with projects:
* Direct access:
+
The files are in the same folder as the Makefile.
* Central storage:
+
Some of the files are in a different folder, which also has its own Makefile. The actual Makefile will call the Makefile of this folder, if needed to build the binary files, instead of building them itself. This efficiently reduces build times even for a single user scenario, and can also be used where several users refer to the same already built folder.
* Anything else:
+
The Makefile is available for the users to modify, so any kind of project structure can be created. It is also possible to add new commands, new build rules, new behaviors.
[[mctr-gui]]
=== Mctr_gui
The mctr_gui supports the following ways of working with projects:
* Referring to files directly anywhere in the file system:
+
when the project is built, symbolic links are created for all of these files in the working directory of the project. Practically this maps to the direct access feature of the Makefile mode.
* Referring to file groups:
+
file groups recursively declare a list of files and file groups that they represent. When a file group is used, all files and other file groups it references are also automatically used. The files included in a group do not have to be in the same folder or be related any other way. For each file added to the project this way the build system creates symbolic links in the working directory.
* Included projects:
+
it is possible to refer to a whole project, instead of referring to files or file groups one-by-one. In this case at build time the working directories of the included projects are used as central storages for the actual project.In this mode, if something is changed in a project (build mode, additional files) all projects including that one will also see that change, at the next build, as it will go differently.
=== Eclipse
In Eclipse the fundamental difference to all previous systems is that in this case Eclipse as the platform provides all of the options for structuring the projects. Our IDE only extends the platform with TTCN-3 related features (and doesn’t define the whole platform).
On one side this is a limitation, on the other side this means, that anyone can extend his projects with additional capabilities, either by developing his Eclipse extensions (for example a builder that converts some 3rd party file format into TTCN-3 files), or by using existing 3rd party tools (for example CDT for working with C/C++ and Makefiles, JDT for Java, documentation supporting tools, supporting writing command line scripts easier … and the list goes on).
The following ways of structuring are provided by Eclipsefootnote:[There is one more dimension of structuring in Eclipse when several plug-ins are used on the same project /_by default all plug-ins are active on all projects _/.If there are several plug-ins active in/on a given project, this can create several ``layers'' of responsibilities. This is an important feature, as this makes it possible to mix plug-ins that each provide some separate functionality into a working environment that best supports the user’s daily work routine. For example on a parallel cooperation the Designer supports editing TTCN-3, ASN.1 and configuration files, while CDT support editing C/C++ and Makefiles practically covering all aspects of working with TITAN by default. For an example of sequential cooperation we can say, that the working directory we use to output the final product of TITAN (the executable test system), can be viewed by CDT as the source of information for debugging/profiling the generated executable.]:
* Each file and folder below the project’s folder is part of the project, and by default should be used to operate the project. However, plug-ins working on the project can choose to ignore some of them on their own. For folders this is very much like file groups in mctr_gui, but in this case all files/folders in a given folder are part of that project by default.
* Linked resources can be used to refer to files/folders that are not contained within the folder of the actual project. This way the linked files/folders will also be members of the project in the resource system of Eclipse. It is important to understand that linked resources are only represented in Eclipse as the path they point to. When such a project is moved (or checked out on a different location), the contents of the linked resources are not moved together.
* Linked folders can be marked to be central storages. In this case the contents of the folder are not built with the actual project, but used as central storages.
* Linked files/folders can be set to use Path variables to refer to the target location. Using this method, it is possible to refer to files/folders that are outside the project in the local file system, in a semi-transportable way. In this case the contents of the files are not moved together with the project, but if the receiving user has the same folder structure as the sending one, and has the same path variables set, the linked resources will point to valid locations at his site too.
* Referenced projects:
+
the projects in Eclipse can reference any other project inside the same workspace (Figure 81).Similar to included projects in the mctr_gui this feature also maps the working directories of the referenced projects as central storages. However there is difference between the two features: If a setting or file is changed in the mctr_gui project, the projects including it will only notice the change when they are being loaded / built the next time. As in Eclipse most of the time all projects are available and interactively worked with, if something changes in a project, all accessible projects referring to that one will automatically (and supposedly instantly) react. For example if a function is removed from the source code in one project, all of its call sites will notice and report the error, even if they are located in different projects. Also the internal Makefile generator is able to make use of settings of the referenced projects, to make its own job better: for example if a library is set to be used at linking time for a project, all projects referencing that one (either directly or indirectly), will also include that library in the Makefiles they generate.
+
NOTE: Referenced projects are represented with their name only. As long as there is a project in the workspace with the same name it will be ok to use, without regard to where it might be located, how it is version controlled, or if it really exists or is just emulated by a 3rd party plug-in.
Additional information related to Eclipse:
It is important to note, that using referenced projects is also a good way to manage complex projects, and the possibly large load of build and analysis. In such a hierarchy if something changes the command line build, and the on-the-fly analysis will only reanalyze only those projects, that might be affected by the change, usually only a small part of all of the sources.
As Eclipse defines the base folder of the project as the folder where the ".project" file resides, it comes naturally, that in a single folder we can only have one Eclipse project.
No matter where they are originating from, in the workbench of Eclipse all projects are located on the same level: directly below the root of the workbench. For this reason, creating connections between projects, by any means other than "project references" is not really recommended, as even importing, or joining such a project can create a structure different from the one seen in the native file system of the projects involved.
Referring outside, the project should be discouraged in case of files and folders, as those methods are not always transportable. In those cases, the project might not be transferable as it is not the contents of these references that will be transferred, but the reference itself. In case of referenced projects this is not that much of a problem, as in that case it is natural, that in order to transport a project, we also need to transport all projects that it builds onto. As long as each project can be transferred on its own their referencing sets will be transferable also.
== Manually Converting an Existing Project to Eclipse Format
=== Small Project
If the project is so small that all of its files are located in one place (in or below one folder) it can be converted easily.
If done from Eclipse one just has to create a new project, setting the location of the project to be linked to the folder where the sources are located infootnote:[In case the original project has some kind of structure like src, doc folders the new project should also be created in this base directory instead of using the src folder directly.]. This will create the project in Eclipse, and all of the files needed to store the settings of the project (which are set to default values at this time). For more information, please refer to section <<4-managing_projects.adoc#creating-a-new-project>>.
If it is needed to perform this step from the command line, one needs to place a default ".project" and ".TITAN_properties" file in the base folder of this project.
In the ""project" the name of the project has to be set. Eclipse should be able to import the project and all further configurations can be done from there.
=== Large Project Sets Consisting of Several Included Projects or Logically Separate Parts
This can be easily mapped to referenced projects inside Eclipse. For each separate project or logically separate part there should be one project created, and the proper referring relation between each one should be set. It is recommended to set this attribute in Eclipse, so that all needed modifications are done in the internal representation. For more information, please refer <<4-managing_projects.adoc#using-project-references, here>>.
If we have to do the changes externally the ".project" file has to be extended with the following code:
[source]
----
<projects>
<project>included_project_name</project>
</projects>
----
As Eclipse will use the name of the project as reference, this will be a transportable solution, as neither local file system paths, nor the relation between the actual and the referenced project is fixed (with symbolic links we would be forced to build the same project structure which is not possible in Eclipse, as all projects have to be on the same level).
Figure 81 gives an example on how it might look if 2 large projects are separated into smaller referring project.
image::images/5_F82.png[title="Two large projects"]
=== Large Projects Using Central Storage Folders
If the project uses central storage folders there are two good solutions possible:
* If it is possible these cases should be solved by converting the central storage relation into a referencing relation between 2 projects.As such the folder declared to be a central storage should be converted into a project on its own, and the original project should be set to reference this project. For more information, please refer to section 4.6.
* A second solution is to create a folder in the project for each such reference and set it as central storage. It is recommended to do this change from Eclipse by a single right click on the folder. If this has to be done from the command line, the ".TITAN_properties" file’s "FolderProperties" section has to be extended with the following code:
[source]
----
<FolderResource>
<FolderPath>path_of_the_folder_in_the_project</FolderPath>
<FolderProperties>
<CentralStorage>true</CentralStorage>
</FolderProperties>
</FolderResource>
----
When loading this project the Designer plug-in will know, that that folder is not to be handled as a normal folder, but instead as a central storage. This solution will also let the user/converter chose whether he wishes to have the central storage inside the project, or use Eclipse linked resources to refer to places outside the project no matter whether the folder is inside or outside the project.
NOTE: Even though the second solution sounds to be the better one at first, because of the similar terminology, actually it is not.
Creating referencing relations between projects reflects the logical structure of such folders better, promotes reuse of projects (and so source code) and in the longer run could be used to validate the relations between projects in a hierarchy.
=== Project Referring to Specific Files Outside its Own Jurisdiction
In some cases, it might have happened, that people did break logical relations and either created symbolic links to files in other projects, or referred to them in the mctr_gui one-by-one specifically.
If it is not possible to map this relation to referring projects or central storages the only solution left is to create a linked resource. This new resource should be placed in the actual project, but setting its location as a link to the original file.
NOTE: It is not recommended to have symbolic links in a project pointing to some other location as those projects are typically not transportable, and also this introduces a hidden dependency between projects, that cannot be validated automatically.
[[convert-an-existing-mctr-gui-project-using-an-import-wizard]]
== Convert an Existing mctr_gui Project Using an Import Wizard
The Designer feature comes with an import wizard, which is able to create an Eclipse project out of an existing mctr_gui project automatically. For information on how to find this wizard, and what its steps are please refer <<4-managing_projects.adoc#importing-an-existing-mctr-gui-project,here>>.
As this wizard has no knowledge about the internal semantic structure of the project to be loaded (the mctr_gui did not helped the organization of project parts too well), the conversion is rather simple:
Projects mentioned as included project in the input project file will be converted to references to Eclipse project.
File referred to directly will be linked in the base folder of the newly created project, with Eclipse links.
Group files are read, but as such an automated wizard is not allowed to create arbitrary folder structures, the files in each group will be linked to the base folder of the project, just like directly referenced files.
In the last two cases if the location of the project directly contains any of the files to be imported, instead of creating Eclipse links, the original files will be used.
Although it might be possible to work with the project created, it is recommended to fine tune it by hand afterwards (or for large projects do the conversion by hand to start with). As the generated out is known to have serious flows: not structured, not easy to version handle and contains links to all files … even if it would be possible to create a project hierarchy using existing projects.
= Contents of the Problems View
:toc:
:figure-number: 109
This section presents how TITAN Designer plugin is integrated in the Problems view.
Whenever a problem is found in a project related resource, a marker is placed on that resource in the TITAN Designer.
In general, when any part of the TITAN Designer plugin checks a given file for problems, it first removes the markers from the resource then does the checking; and if any problems were found new markers are placed on the resource. The only exception to this is that the on-the-fly parser cannot remove markers generated by the compiler; but instead it turns them grey, this was designed so because the checks of the compiler are much more precise than the checks of the on-the-fly parser. The compiler overwrites also the markers of the on-the-fly parser, of course.
== Types of Markers
There are three error marker types indicating:
* issues reported by the compiler;
* syntactic errors reported by the onthefly parser;
* semantic errors reported by the onthefly checker.
Issues are reported as warnings (minuscule issues) or errors (severe issues that must be repaired as soon as possible).
[[eclipse-provided-features]]
== Eclipse Provided Features
Every time a marker is created the TITAN plugin tries to provide as much information about the issue as possible to fully profit from the Eclipse features.
The TITAN plugin makes use of the following features:
* Collecting of markers:
+
Eclipse collects all of the markers in the *Problems view*, so that they can be handled together in a single place.
* Jumping to a given position:
+
The TITAN plugin provides Eclipse sufficient information to make Eclipse jump to the exact problem location when the user *double clicks* a marker. If the file is not opened in the editor Eclipse will first open it and then jump to the location.
* User configurable presentation:
+
The users can configure the presentation of the problems by selecting *Window / Preferences / General / Editors / Text Editors / Annotations*. Here the presentation of errors and warnings can be configured (for example, whether they should be underlined and shown on the side rulers, what color to use).
* Grouping of markers:
+
These markers can be grouped in several, semantically different ways. This will be shown <<grouping-of-problems, here>>.
* Displaying the error text:
+
Every editor provided by the TITAN plug-in is able to show the error texts of markers placed on a line. The mouse pointer must be placed over a marker to activate this functionality. If several errors were found in the same line, each of their texts is displayed on a new line.
[[grouping-of-problems]]
== Grouping of Problems
Grouping of markers can be activated by selecting *Triangle / Group By*.
image::images/8_F102.png[title="Grouping problems"]
Other elements of Eclipse can also report problems; these issues will be called other problems. General problems, for example not being able to execute a program, are reported as general Problems by both the local and the remote build procedures.
Groupings supported by TITAN plugin are described in the following sections.
=== Group by Severity
Here the markers are grouped by their severity, that is, whether they are representing errors or warnings. This grouping is preferable when treating errors first. Other problems are mixed into the problems reported by TITAN plugin.
image::images/8_F103.png[title="Grouping by severity"]
=== Group by Type
Here the problems are grouped by the reporting entity. The following groups are composed by the TITAN plugin: