Developer manual

From sygnm
Jump to: navigation, search

Information for sygnm developers.

Code formatting

The sygnm project uses the astyle (Artistic Style) code formatter to format C/C++ source code. All code must be formatted before committing. sygnm-codegen can call astyle (if installed) with the correct options, see sygnm-codegen --help for more information.

Platform-specific code and porting sygnm to other OSes

It should be easy to port sygnm to other platforms. All platform-specific functions are declared in platform.h. To port sygnm to another OS, first add a define to CMake which is set automatically if the target platform is detected (see the existing code for how it's done). It should be named SYGNM_OS_OSNAME. Currently SYGNM_OS_{WINDOWS,LINUX,HAIKU} is defined if the corresponding OS is detected. This define can be used in packages and clients to identify the current platform. In sygnm core, all platform-specific functionality should go to platform.h and a corresponding platform_osname.cpp should be added for the implementations (for example, Linux-specific functions are implemented in platform_linux.cpp and only there). Do not forget to update the build system so that the correct platform_osname.cpp file gets compiled on the target platform. Generally, and especially in packages, the amount of platform-specific code should be kept minimal, however some platform-specific packages can be acceptable if the functionality is needed and there is no platform-independent way to implement it (this should be extremely rare).

Translation and localization

TODO

Logging and error handling in sygnm code

Logging

Log messages can be used in all sygnm code. A message has a severity (info, warning, error, critical), a text description (this should be translatable), a message type identifier (like an error code, so the message can be identified even if the text is translated) and optionally an object identifier (if the message is related to some specific instance of some object). See existing code for examples.

Error handling in packages

To handle mathematical and other user-facing errors in sygnm functions, use the error package to construct an error object, then throw a sygnm::function_error initialized with the constructed error object. Error messages should be translatable. See existing code for examples.

There is a special sygnm::empty_result exception. Use this in cases where the input is invalid for the current function, but it is possible that another overload can use the same input successfully (this is to handle cases where there are multiple overloads and the type system is not powerful enough to select the right one first, but otherwise no error happened). This should be rarely used. Do not use this for completely invalid input or other error conditions.

Error handling in sygnm core

For unrecoverable errors, use sygnm::throw_fatal_runtime_error. Errors visible for users should always be translatable, while errors meant only for (package) developers should not be translatable. Fatal errors are automatically logged, so do not log them separately.

For non-fatal errors use the log with an appropiate severity level.

Running sygnm core as a standalone process (for UIs and other client software)

The sygnm executable starts the sygnm core process, which initializes the sygnm framework and loads packages according to the configuration. After initialization, an I/O interface will be started (by default binary_stdio_io_interface, this can be changed in the configuration). This way, other processes can start, stop, interact with and control sygnm without any compile or link-time dependencies. binary_stdio_io_interface implements a simple binary protocol and uses the standard input and output to communicate with other processes. In addition to the configuration file, arbitrary configuration options can be specified on the command line. See sygnm --help for more information.

API documentation

See the automatically generated doxygen documentation. TODO

Building Arb on Ubuntu 17.10

With arb 2.11, the -no-pie and -nostartfiles options must be added to the Makefile.