Language Hooks : C# SWIG Bindings

Introduction

BioGears now supports C# Language hooks through the use of SWIG Bindings Generator. (http://www.swig.org/). This page details how to build SWIG Bindings on Windows based platforms. The initial procedure will be the same on all platforms, but you will need to ensure you have a C# compiler and runtime environment supported by CMAKE to build the resulting project

CMAKE controls the building of SWING bindings through the use of

Warning our bindings work with SWIG 4.0.2 and will fail to generate properly with a swing compiler of 3.X or earlier.

Name	Note
Biogears_BUILD_SWIG_BINDINGS	Turns on detection of SWIG and language support
Biogears_BUILD_SWIG_CSHARP_BINDINGS	When SWIG is found and CHARP development environment exist this will be true and bindings automatically built.

We plan to add support for RUST and Python using our existing SWIG Template files. Some work is needed to make sure that no CSHARP specific directives are applied to the other languages, but as support for other languages grow additional CMake flags will allow you to enable and disable the binding outputs of each language.

Obtaining SWIG

The Simplified Wrapper and Interface Generator (SWIG) is an open source project that provides a cross language interface code generator for a multitude of languages based off a SWIG template language. SWIG templates reference C/C++ files directly reducing the amount of code maintenance needed to keep bindings update and eliminating the need to write boiler plate code when providing cross language hooks. The BioGears team can not thank the SWIG team enough for this project please check it out.

You can obtain SWIG as source or binaries in a number of ways http://www.swig.org/download.html. BioGears currently requires a version of the 4.X line to support all features. As CMake has native support for generating SWIG bindings the implementation of our bindings is fairly straight forward provided CMake can detect the requirements for the target language and the SWIG code generator.

#Example installation on Ubuntu 20.04
sudo apt install swig

#Example installation on MacOS using Brew
brew install swig

#For Windows simply download the pre built binaries and extract SWIG.exe and Libs in a bin directly CMAKE Can find. 
http://www.swig.org/download.html

Configuring CMAKE

These instructions assume you have already built BioGears and would like to enable SWIG bindings for the first time. If you do not know how to build BioGears please refer to our build instruction pages for your OS. Assuming the same layout as those pages the following is an example of rerunning CMake with additional directives to toggle on the SWIG Bindings

cd /opt/biogears/core/build
cmake \
               -Biogears_BUILD_SWIG_BINDINGS=ON \
               -Biogears_BUILD_SWIG_CSHARP_BINDINGS=ON \
               ..
cmake --build . --config Release --target libbiogears-csharp

Biogears provides a demonstration test of the bindings which has been primarily tested using Visual Studio 2021. This target is unittest_charp and will test many of the major calls such as creation of engines, stabilization, loading of serialized states, and the application of most patient actions along with referring to DataTracks to poll data between time advancements. These bindings are in active development and considered EXPERIMENTAL. Please file issues for any errant behaviors noticed while interacting with them and feel free to push change request for improvements.

#Results Upon using SWIG bindings you will notice an additional language hook library libbiogears_csharp This library depends on all other libbiogears dynamic libraries in the outputs directory. In addition to this directory a new folder is created along side the usual Release and Debug output sub directories the chsarp directory. This directory contains all language hooks which should be included in your C# Biogears application. The code contains all the appropriate dynamic library hot loading code to refer to the required dynamic libraries at runtime. Your project simply needs to include the language hooks as its own code and then provide all BioGears DLLs and libxerces-c in its runtime directory in order to work.

outputs/
├── Release
│   ├── lib
│   └── bin        #Release dynamic libraries to be included in your projects runtime directory. Additionally xerces-c will be needed as well
├── Debug
│   ├── lib
│   └── bin
├── RelWithDebInfo
│   ├── lib
│   └── bin
└── csharp          #Language Binding Code to be used in your project. Copy all files

BioGears embedded its IO files by default in libbiogears_io to avoid the need of having physical reference files at runtime. As a user of BioGears you can either embedded your own language files in this library at compile time or read them directly from disk at runtime all file loading in BioGears will fallback to embeeded files if one exist transparently. Please refer to our biogears_io documentation for more details.