Porting Guide: HELICS 2 to 3¶
Since HELICS 3 is a major version update, there are some breaking changes to the API for developers. This guide will try to track what breaking changes are made to the API, and what developers should use instead when updating from HELICS 2.x to 3.
Dependency changes¶
Support for some older compilers and dependencies have been removed. The new minimum version are:
C++17 compatible-compiler (minimums: GCC 7.0, Clang 5.0, MSVC 2017 15.7, XCode 10, ICC 19)
CMake 3.10+ (if using clang with libc++, use 3.18+)
ZeroMQ 4.2+
Boost 1.65.1+ (if building with Boost enabled)
Code changes¶
Changes that will require changing code are listed below based on the interface API used. A list of known PRs that made breaking changes is also provided.
PRs with breaking changes¶
Application API (C++17)¶
Federate::error(int errorcode)
andFederate::error(int errorcode, const std::string& message)
were removed, uselocalError
instead (orglobalError
to stop the entire simulation). Changed in #1363.ValueFederate::publishString
andValueFederate::publishDouble
have been removed, please use the Publication interfacepublish
methods which take a wide variety of typesThe interface object headers are now included by default when including the corresponding federate
Command line interfaces¶
The numerical value corresponding with the log levels have changed. As such entering numerical values for log levels is no longer supported (it will be again someday). For now please use the text values “none(-1)”, “no_print(-1)”, “error(0)”, “warning(1)”, “summary(2)”, “connections(3)”, “interfaces(4)”, “timing(5)”, “data(6)”, “debug(6)”, “trace(7)”. The previous values are shown in parenthesis. The new numerical values are subject to revision in a later release so are not considered stable at the moment and are not currently accepted as valid values for command line or config files.
Queries¶
Queries now return valid JSON except for
global_value
queries. Any code parsing the query return value will need to be adjusted. Error codes are reported back as HTML error codes and a message.
Libraries¶
CMake¶
All HELICS CMake variables now start with
HELICS_
#1907Projects using HELICS as a subproject or linking with the CMake targets should use
HELICS::helics
for the C API,HELICS::helicscpp
for the C++ shared library,HELICS::helicscpp98
for the C++98 API, andHELICS::helicscpp-apps
for the apps library. If you are linking with the static libraries you should know enough to be able to figure out what to do, otherwise it is not recommended.