itchi 9.21.315.1

TASKING itchi

iTCHi Developer Readme

This document explains how to start working with iTCHi. To get started use Visual Studio Code and open itchi.code-workspace.

If you are planning to use PyCharm, nothing special has to be done, just specify correct venv and you are good to go. Note that there are no pre-made PyCharm run configurations, but tests can be executed directly.

Consult the TASKING Python development guidelines, to make sure your code is compliant with the company policies.

Getting Started With iTCHi

Prepare the Python Virtual Environment

You can use existing venv or, even better, create a brand-new instance of venv for this project. Using separate venv will ensure that there is no clashing of packages, and all necessary requirements are specified in this project, making it self-contained. Make sure that you are using the most recent version of python that is used in TASKING development.

Creating venv can be done using:

<path to python interpreter> -m venv <desired venv location>

To use this venv, we need to activate it. The location of activate script is os dependent. On Linux it is source <venv root dir>/bin/activate and on Windows <venv root dir>/Scripts/activate.<ps1, bat, ...>.

Once the venv is activated for the first time, it is recommended to upgrade pip by running python -m pip install --upgrade pip.

Installing the iTCHi Package

Once the venv is created, we need to install iTCHi package. If you plan do modify iTCHi sources, make sure that you install iTCHi in the editable mode using -e flag for pip.

Installing iTCHi is simple:

• Activate venv
• Make sure that the ISYSTEM_APPS environment variable is configured.
• Navigate into the iTCHi root directory (where pyproject.toml is located)
• iTCHi requires the isys_setup tools; install them:
  • pip wheel -w dist ..\..\..\Utils\isys_setup
• Then, install iTCHi itself:
  • pip install -e . --find-links dist

Launching iTCHi

Once iTCHi package is installed in the venv, we can launch it using python -m itchi.itchi_cli or call itchi-cli<.exe> directly, since pip created an executable and added it into the PATH on venv activation. Because we installed iTCHi in venv, we can call this command from anywhere when iTCHi venv is active.

There is also a gui version itchi-gui, which imports cli version under the hood.

Dependencies

iTCHi requires some third party packages, which are listed in pyproject.toml. They are automatically installed once iTCHi is installed. If new dependency is needed, it can be added to the pyproject.toml section dependencies.

Tests

All tests are located in the tests directory. If new tests are created, make sure that you are not importing the iTCHi components relative to the tests, but rather import it as installed package (no leading dots should be present in the imports!). This will ensure that the tests are testing what will be deployed and not what we have in the editable mode.

If some custom files are needed, specify them relative to the test file, for example:

import os
file_of_interest = os.path.normpath(os.path.join(os.path.dirname(__file__),
                                                 'file_of_interest.png'))

This will ensure that test can be executed from arbitrary location, and we do not need to change current working directory.

Run pytest . in the itchi/tests directory to execute all tests. See pytest manual for more info how to execute them.

fitIDEA Examples

The directory examples/fitIDEA/testVectors contain fitIDEA Profiler Unit Test files. These YAML files contain a specific stimulus vector consisting of writes to variables and executed functions, and an output timeline. With this approach, Profiler XMLs generated by iTCHi can be tested in the winIDEA Analyzer itself.

To run the test vectors:

1. Setup fitIDEA
2. Open examples/fitIDEA/sample.xjrf in winIDEA.
3. Open a YAML file from the testVectors directory.
4. Run the YAML file like a Python script with F6 or ctrl+F6.

Adding a New Command

To add a new command, make sure to add it at the following locations:

1. The command parser in src/itchi/itchi_cli.py.
2. The launch configuration in itchi.code-workspace (for easier development).
3. The regression tests in examples/test_examples.
4. The documentation in docs/readme.md.