-
Notifications
You must be signed in to change notification settings - Fork 35
Building Kactus2 from source
- 1. Building on Windows
- 2. Linux build, install and run
- 3. Troubleshooting for Python API
- 4. Building on distros with no Qt6 packages
- 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.
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.
- 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
- If you get errors relating to the Python API, check troubleshooting tips below
- 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.
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/
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
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.
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).
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.
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
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/'])
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.
On distros such as Centos7 with no Qt6 packages available, Kactus2 can be built inside a docker container. More information in here.