Building Kactus2 from source - kactus2/kactus2dev GitHub Wiki

1. Building on Windows

1.1 Prerequisites

  • Visual Studio 2022
  • SWIG, tested on version 4.0.1
  • Python version 3.8.x or greater, tested on 3.10.6
  • Qt6 (tested on version 6.2.4, but newer versions should also work)
  • Qt VS Tools for Visual Studio (tested on version 2.10.1.2)

Install SWIG, and add the path to the SWIG executable in the PATH environment variable. Download the Windows version (swigwin) to include the prebuilt executable.

Install Python for windows and make sure to check the following advanced options in the installer:

  • Add Python to environment variables
  • Download debugging symbols
  • Download debug binaries

Set the environment variable PYTHON_DIR to the installation directory containing the Python executable.

To install Qt, download and run the online installer from https://www.qt.io/download. After Qt is installed, set the QTDIR environment variable to point to the Qt include directory, e.g. C:\Qt\6.2.4\msvc2019_64\include. Also, make sure that the Qt binaries are added to PATH, e.g. C:\Qt\6.2.4\msvc2019_64\bin.

Install Qt VS Tools using the Visual Studio extension marketplace. The recommended version is the legacy version 2.10.1.2, because newer versions removed exporting .pro/.pri files. Newer versions should work fine otherwise. Point Qt VS Tools to the correct Qt installation directory in the extension settings. Take note of the Qt version set in the 'Version' field, it will be needed later.

1.2 Obtaining the source code

Kactus2 source code can be cloned from the repository using git clone https://github.com/kactus2/kactus2dev.

You may want to clone using HTTPS. Also remember to choose the desired directory on cloning. Alternatively, if you do not need to make commits, you may download the source code as a zip file.

1.3 Building and running Kactus2 with Visual Studio 2022

  • Open the Kactus2 root project Kactus2.vcxproj located in the root of the repository. Visual Studio should load all necessary solution sub-projects automatically
  • Check that the Qt version in the Qt project properties of each project in the solution (Project properties -> Qt project properties -> Qt installation) matches the version set in the Qt VS Tools settings. Kactus is built and tested on Qt 6.2.4, which is also set as the default value
  • Check that the Python library dependency versions match the installed Python version in the properties of each project being built (Project properties -> Linker -> Input -> Additional Dependencies), e.g. python310_d.lib and python310.lib for Python 3.10.x in debug and release modes respectively
  • Build the Kactus2 project. This should also build its dependencies (IPXACTmodels, KactusAPI and PythonAPI), but they can also be built manually beforehand
  • Run Kactus2 in GUI mode by default, or on command line by setting the command line argument -c/--no-gui

The included plugins for Kactus2 won't be built automatically and need to be built manually. This can be done by building the corresponding project in Visual Studio. The plugins should automatically be detected in Kactus2 when built.

2. Linux build, install and run

2.1 Install Qt6

To build and run Kactus2, Qt6 must be installed on your system. If you already have Qt installed, you can skip to step 2. Otherwise, install Qt with either using a package manager (option a) or manually (option b):

a) Install Qt6 packages using a package manager (requires admin privileges). The following packages are required (on Ubuntu 22.04 LTS):

  • qt6-base-dev
  • qt6-tools-dev
  • qt6-tools-dev-tools
  • qt6-documentation-tools
  • libqt6svg6-dev

Install other dependencies:

  • libpython3.8-dev or newer
  • swig, version 3.0.12 or newer
  • libgl-dev

Example with all dependencies:

sudo apt-get install qt6-base-dev qt6-tools-dev qt6-tools-dev-tools qt6-documentation-tools libqt6svg6-dev libpython3.8-dev swig libgl-dev

b) Manually download and install from https://www.qt.io/download/

2.2 Build the sources

First, get the Kactus2 source files. We recommend using the release tar-package (SourceForge) which has all Windows-specific files removed. Extract the files and navigate to the Kactus2 root directory.

Example:

mkdir ~/kactus2
tar -xvf kactus2-3.11.0.tar.gz -C ~/kactus2
cd ~/kactus2

Build configuration

Open the file configure in the Kactus2 root directory and set the path to Qt6 binaries in the variable QTBIN_PATH.

Example:

QTBIN_PATH="/lib/qt6/bin/"

Please do note the slash at the end of the path.

Open the file .qmake.conf and check that the paths are compatible with your Linux distribution. The defaults should work with Ubuntu 64-bit, Debian and CentOS 7 64-bit, but on some systems you may have to change lib_path from /usr/lib to /usr/lib64. Next, check that the PYTHON_CONFIG variable has been set correctly and matches the installed Python version.

Example for Python version 3.10:

PYTHON_CONFIG=python3.10-config

Now run the following command to apply the configuration:

./configure

Please note, if you run ./configure with the wrong configuration, you will have to delete the generated makefiles before configuring again. The easiest way to do this, is to run command make distclean.

Build and install

Select installation either for all users (option a) or customized target (option b) below:

a) Default installation for all users (requires admin privileges).

Now run following commands:

make
sudo make install

After the installation, skip to section 3.

b) Customized installation target. This option can be used for a local installation for the current user (e.g. in ~/kactus2) as well as shared installation in a specific directory (e.g. /opt/edatools/kactus2).

Open file .qmake.conf and set the installation directory in variable LOCAL_INSTALL_DIR.

Example:

LOCAL_INSTALL_DIR="~/kactus2"

By default, the shared libraries are installed in the same directory, but can be configured by setting the lib_path on line 60.

Now run the following commands:

make
make install

Run sudo make install, if the current user has no write permissions to the target directory (e.g. /opt/edatools/kactus2).

Shared library setup

Finally, make sure the shared libraries can be found by the program loader. If the installation is shared between multiple users, consider listing the libraries in /etc/ld.so.conf.

Example for Ubuntu 22.04 LTS: Create the file /etc/ld.so.conf.d/kactus2.conf and add a single line that contains the target installation path (e.g. /opt/edatools/kactus2). Run ldconfig to update the paths in the loader.

2.3 Running Kactus2

2.3a Run Kactus2 GUI

There are three ways to run Kactus2 depending on your system and installation setup.

a) A default installation shared between users. Run:

/usr/bin/kactus2

b) A local installation from the installation directory. Run:

LD_LIBRARY_PATH=. ./kactus2

If the library paths are set in /etc/ld.so.conf, the binary can be run directly. Example:

/opt/edatools/kactus2

c) In some systems, a link to the executable is created, if Kactus2 was installed for all users. Run:

kactus2

2.3b Run Kactus2 on command-line

Kactus2 can be run in the command-line without the GUI. Run:

kactus2 -c

This will start an interactive Python® interpreter for executing series of commands.

Kactus2 supports the following command-line options:

  • -c, --no-gui: Run in command-line mode without the GUI.
  • -h, --help: Show the application usage help and exit.
  • -v, --version: Show the application version and exit.

On command-line the IP-XACT data is readable and modifiable through the provided interafaces. Interface documentation will be added later. Example script files can be found in PythonAPI/ExampleScripts directory. The API module is imported at startup and instantiated as kactus2.

Example usage showing importing a verilog file to IP-XACT component and generating an equivalent VHDL file:

$kactus2 -c
...
Python 3.8.3 (tags/v3.8.3:6f8c832, May 13 2020, 22:20:16) [MSC v.1925 64 bit (AMD64)]
>>> kactus2.importFile('D:/Data/ipxactexamplelib/wb_sum_buffer.v', 'tuni.fi:peripheral.logic:wb_sum_buffer:1.0')
1
>>> kactus2.generate('VHDL', 'tuni.fi:peripheral.logic:wb_sum_buffer:1.0', 'flat_verilog', 'D:/Data/ipxactexamplelib/generated')
Running VHDL Generator 1.3.
Running generation for tuni.fi:peripheral.logic:wb_sum_buffer:1.0 and view 'flat_verilog'.
Target directory: D:/Data/ipxactexamplelib/generated
Parsing the IP-Xact models...
Writing the vhdl file...
Done writing the vhdl file.
VHDL generation complete.
>>> exit()

The Python interface can be used without running Kactus2 by importing the pythonAPI module and instantiating the API:

Python 3.8.3 (tags/v3.8.3:6f8c832, May 13 2020, 22:20:16) [MSC v.1925 64 bit (AMD64)]
>>> import pythonAPI
>>> kactus2 = pythonAPI.PythonAPI()
...

Please note the following when using the module independent of Kactus2:

  • The API is dependent on a shared library named KactusAPI. It must be found at import time.
  • Kactus2 settings, such as library paths, are not loaded with the module. You must set them manually. An example is shown below:
>>> kactus2.setLibraryPaths(['/home/me/ipxact', '/home/me/ip/uart/'])

3. Troubleshooting for Python API:

sh: 1: python3-config: not found

Running ./configure gives this error when the Python 3 configuration utilities cannot be found. Set the variable PYTHON_CONFIG in .qmake.conf.

Could not import Kactus2 PythonAPI.
ModuleNotFoundError: No module named 'pythonAPI'

The Python module (pythonAPI, no underscore prefix) for the API could not be found. Make sure the directory PythonAPI is in your PYTHONPATH environment variable. For non-persistent setup you can set PYTHONPATH at Kactus2 startup by running e.g. PYTHONPATH=~/kactus2/PythonAPI kactus2 -c

ModuleNotFoundError: No module named '_pythonAPI'

File _pythonAPI.so (with underscore) could not be found. Check that PythonAPI project was compiled succesfully and libPythonAPI.so was created in the PythonAPI directory. SWIG requires the library name to match _pythonAPI.so, so create the link manually with ln -s -f PythonAPI/libPythonAPI.so.1.0.0 PythonAPI/_pythonAPI.so

ImportError: libKactus2.so: cannot open shared object file: No such file or directory

File libKactus2.so could not be found. Check that Kactus2 project was compiled succesfully and libKactus2.so was created in /usr/lib, /usr/lib64 or your local install directory. Running make install copies the .so file in the target install directory. Also make sure the library can be found run-time. See the end of section 2 for details on library path loading.

4. Building on distros with no Qt6 packages

On distros such as Centos7 with no Qt6 packages available, Kactus2 can be built inside a docker container. More information in here.