+ Updated Readme

# T3Tools

Welcome to the T3Q project! T3Q is a guideline checking tool for TTCN-3 test specifications.

A critical issue for ETSI in developing test suites is the readability, consistency, maintainability, and documentation of the TTCN-3 code. Automating the code analysis for these properties increases the level of confidence regarding code quality. It can also help to make sure that agreed upon coding guidelines are met. ETSI provided funding for the initial development and subsequent maintenance of the T3Tools, which currently include T3Q and supporting tools. The documentation generation tool T3D is no longer actively maintained, some of its functionality has been merged into T3Q.

## Download

Recent versions:

* T3Q v2.1.1 ([Release](https://labs.etsi.org/rep/mts/ttcn3/t3q/-/releases/20260324.17.21) / [Direct download](https://labs.etsi.org/rep/mts/ttcn3/t3q/-/releases/20260324.17.21/downloads/release-archive) / [Release notes](https://labs.etsi.org/rep/mts/ttcn3/t3q/-/wikis/Release-Notes))

* T3Q v2.1.0b5 ([Release](https://labs.etsi.org/rep/mts/ttcn3/t3q/-/releases/20260324.17.21) / [Direct download](https://labs.etsi.org/rep/mts/ttcn3/t3q/-/releases/20260324.17.21/downloads/release-archive) / [Release notes](https://labs.etsi.org/rep/mts/ttcn3/t3q/-/wikis/Release-Notes))

See also the [Releases Page](https://labs.etsi.org/rep/mts/ttcn3/t3q/-/releases) for a full list of the releases, including beta releases.

For overview of the changes in each release, see the [Release Notes](https://labs.etsi.org/rep/mts/ttcn3/t3q/-/wikis/Release-Notes) wiki page.

## Setup

See wiki.

Although the T3Tools package is primarily intended to be used as a console tool, it can also be used as an Eclipse Plugin

### Console Tool

Java 21 (or newer) is required to run the T3Tools as console / command line tool. Once it is setup and working, download the latest release of the T3Tools and unpack the archive. The tool can be started with one of the provided scripts or using Java directly:

```

java -jar t3q.jar [options] ( path | filename )+ 

```

See also wiki pages for further details.

### Installing as Eclipse Plugins

The T3Tools are available as a set of Eclipse plug-ins. You need to first be able to run Eclipse. The Eclipse Java and DSL distribution package contains most of the necessary prerequisites for the T3tools. 

Once Eclipse is up and running, the easiest way to install the T3Tools is from the Eclipse Marketplace - simply search for T3Tools in the Eclipse Marketplace client within Eclipse, or go to the TOP Marketplace Listing and drag the install button into the Eclipse window.

Alternatively, you can install the plug-ins manually from an update site. In this case, you need to add the update site for the T3Tools:

```

https://mts.etsi.org/ttcn3/t3q/updatesite/stable

```

A beta-channel is available at the development update site for the latest development versions of the TDL tools:

```

https://mts.etsi.org/ttcn3/t3q/updatesite/beta

```

After the update site is added, the list of plug-ins and features shall be shown in the installation dialog (menu item Help->Install New Software..). Select the desired features and proceed with the installation, which will require Eclipse to be restarted once the installation is finished.

Interim snapshot builds are also available from the Packages / Releases areas on GitLab. These can be downloaded and installed in Eclipse by adding a new update site from a local archive. Please note that these snapshot builds may not be stable as they reflect the development at a certain point in time between stable releases and while certain issues may be addressed, new ones may not yet have been identified.

## Usage

TODO: add and rename launch configurations

### Requirements and getting started

### Requirements and Getting Started

* The project can be built using Maven or Eclipse (or also Maven in Eclipse (M2E))

    * For development it is recommended to setup an Eclipse environment

    * Maven is best used for Continuous Integration (CI) and testing as it takes a while to resolve dependencies upon every build

* To get started and make sure everything is set up and running:

    * download and setup Java 21 or newer (if missing): []([https://adoptium.net/en-GB/marketplace/)

    * download and setup Eclipse Java and DSL Package (2024-09 or newer): [](https://www.eclipse.org/downloads/packages/release/2024-09/r/eclipse-ide-java-and-dsl-developers)

    * clone t3q repo: [](https://gitlab.gwdg.de/swe/tools/t3tools/t3q)

    * clone t3q repo: [](https://labs.etsi.org/rep/mts/ttcn3/t3q)

        * can also be done in Eclipse, which can streamline the subsequent project import

    * start Eclipse and click on “Import projects…” in the “Project Explorer” (or via File -> Import in the menu)

        * select “General” -> “Existing Projects into Workspace”

            * right click -> “Run as” -> “MWE2 Workflow”

            * an automated build should start after the script is finished, otherwise build the workspace manually ("Build All" from the "Project" menu)

### Running and testing

### Running and Testing

* Console tool

    * run “T3Q” to make sure everything works

        * select “Java Application” -> “T3Q”

        * press “Run”

        * you should get an Error in the console that no input was provided, you can customise the launch configuration to your needs as suggested below

    * clone t3q-resources repo: [](https://gitlab.gwdg.de/swe/tools/t3tools/t3q-resources)

    * clone t3q-resources repo: [](https://labs.etsi.org/rep/mts/ttcn3/t3q-resources)

    * run “T3Q” with the input location

        * same as above, but select the “T3Q (sample)” launch configuration

        * before pressing “Run”, select the “Arguments” tab and append the path to where the t3q-resources repo was cloned

    * it is recommended to use the Xtext Tools from Oliver Libutzki [](https://github.com/OLibutzki/xtext.tools) which provide synchronised views for the Node Model and Semantic Model to understand the parsed structures

        * the tools are included in the development target platform, but may need to be enabled in the launch configuration

### Extension and modification

### Extension and Modification

* To update the grammar to support newer versions:

    * update the `TTCN3.xtext` file with the desired changes

        * ambiguities or other may cause the script to fail, address these issues immediately, or roll-back

    * address any immediate issues in the different projects (likely scoping, validation, etc.)

    * test extensively for more subtle problems, e.g. with reference resolution / scoping, etc.

    * in general, check the differences and dependencies in the BNF at [](http://www.trex.informatik.uni-goettingen.de/trac/wiki/ttcn3-bnf)

    * in general, check the differences and dependencies in the BNF at [](https://labs.etsi.org/rep/mts/ttcn3/ttcn-3-bnf-history)

* To extend the quality checker:

    * create examples of what should be checked