Skip to content

Using BioGears

Jump to bottom
Steven A White edited this page Aug 5, 2020 · 29 revisions

Running BioGears

This article focuses on running the core components built by the BioGears build system. The BioGears build system consist of several parallel projects which are mostly used for internal testing. We divide the outputs of the build system in to code generation, shared library, and binary or executable targets. Each of these target types have different goals based on if you are a developer, integrator, or user of BioGears.

Note that for all use cases you must first create a runtime directory

Code Generation

The Code Generation targets are for users who which to extend BioGears by adding additional types to the CDM. They regenerate all of our serialization files using CodeSynthesis XSD 4.0 based on the contents of ${BioGears_ROOT}/share/xsd/. After modifying files in this folder they should be rerun before recompiling BioGears.

Target Purpose Notes
xsd_gen_schema__* Regenerate h,cpp files from share/xsd/*.xsd files Designed to allow changing of the CDM to be caught by the build system. will automatically run the first time building and not needed by most users, but useful for the development of new XSD types. One folder for each file in the xsd tree

Libraries

The first results of BioGears are the libBioGears shared libraries. Most users will be interested in libBioGears and libBiogears_cdm for integration purposes. These libraries included all the serialization subroutines and the BioGears abstraction and implementation layers. Along with additional utilities for running BioGears scenarios. Additionally, we are in development of several language hooks for Java,C#, and Python and will be expanding additional libraries in the future.

Target Purpose Notes
libBioGears main biogears shared library Depends on libBioGears_cdm
libBioGears_cdm Library for Biogears serialization types Depends on xerces-c and XSD Code Synthesis 4.0
libBioGears_circuit_test Debugging Library with Circuit Unit Test Functions Biogears_BUILD_CIRCUIT_TEST
Used in Circuit performance testing. Speeds up build to skip this component
libBioGears_jni Java Runtime layer for libBiogears Biogears_BUILD_JAVATOOLS
Deprecated : Was supported for the Java based GUI tool

Programs

Target Purpose Notes
howto_* API Examples Biogears_BUILD_HOWTOS
Targets automatically created based on folder structure. Each test has an additional control value BUILD_EX_howto-${NAME} example BUILD_EX_howto-Smoke. Which can be used to toggle off sets of unneeded examples and speed up build times.
bg_cli Command Line executable for interacting with libBiogears Biogears_BUILD_TOOLS
Supports multiple ways to run XML scenarios including bulk parallel simulations. Additionally supports the generation of data files absed on csv components
bg_cli Simple EXE to run a single Scenario XML file using libBioGears Biogears_BUILD_TOOLS

Working with BioGears

BioGears is part framework, part SDK, and Platform. Most integrators will be interested in using the libBioGears libraries as a SDK to write third party applications that can benfit from the whole body physiology engine classes included in the libBioGears binaries. To achive this an integrator can take two appraoches.

  1. Add a subproject to the BioGears CMake system
  2. Create a third party application which depends on BioGears

Both approaches are valid. The first would be a good place to start if you are new to CMake or are uncomfertable with maintaing your own build system. The second is the more traditional approach for hosting downstream projects which may or which you would want to host in a seprate source repository yand release under your own licesing restrictions. We detail examples of both approaches below.

Adding Projects to BioGears

The BioGears build system has the following layout

core/
|--cmake    <cmake build scripts>
|--projects <Build targets>
|  |-CMakeLists.txt <CMake file which includes sub directories>
|  |-biogears-common
|  |-biogears
|  |-... <other Projects>
|  `- cli
`--share    <Runtime files and python scripts>
   | -- data  <Runtime files specific to the BioGears release>
   | --- ...
   ` --- xsd  <XML Schemal definition files for the cdm format

Each build target is stored in a subfolder of the projects folder. THe CMakeLists.txt file in projects has one include_subdirectory(dir) line for each dir in projects Each subdirectory has its own CMakeLists.txt file which are written using basic meta programing techniques avaliable in CMake and are mostly identical. To create your own new subproject simply use bg-cli as a template and copy it to a new directyory of your choice then make a few edits to projects/CMakeLists.txt and projects//CMakeLists.txt and rerun cmake.

Example

Lets assume you want to create a new subproject called showcase. With the goal of running a few scenario files that showcase features in the BioGears SDK.

  1. Copy bg-cli/ to showcase/
  2. Edit projects/CMakeLists.txt and insert include_subdirectory(showcase) around line 160
154 add_subdirectory(biogears-common)
155 add_subdirectory(biogears)
156 add_subdirectory(scenario_driver)
157 add_subdirectory(test_driver)
158 add_subdirectory(howto)
159 add_subdirectory(unit)
160 add_subdirectory(bg-cli)
161 add_subdirectory(showcase)  #Added New Showcase project to CMakleLists
162 add_subdirectory(circuit_profiler)
  1. Edit projects/showcase/CMakeLists.txt
    1. Find and Replace BUILD_TOOLS with SHOWCASE
    2. Edit line 14 bg-cli -> showcase
    3. Edit line 15 bio -> sc
  2. Modify the source files in projects/showcase/src/ as you see fit
  3. Rerun CMake and the project should start building

That is the complete process for adding a new subproject to BioGears. bg-cli links against all BioGears libraries so you should be able to use any funciton in the BioGears SDK if you include the appropriate headers. Using these instructions the project will automatically added to the INSTALL and STAGE targets once they are built. You can add additional dependeincies for your subproject by adding find_package statments to the Requirments section of CMakeLists.txt in your subproject folder.

Building against BioGears with CMake

Now most integrators will want to make their own project as indepdent from BioGears as possible. Using this method it is easy to maintain a clone of BioGears and update it as major release come out indepdent of your own projects code revision system. For this project you would clone and build biogears using the instructions avaliable on this wiki. Next update your CMakeCache and set the CMAKE_INSTALL_PREFIX variable

cmake -DCMAKE_INSTALL_PREFIX D:\BioGears\install ..
cmake --build . --target  install

This will create the following folder struction in D:\BioGears. You can change the value of CMAKE_INSTALL_PREFIX to fit your needs.

|--inlcude    <Header files for biogears>
|--lib <biogears librariess>
`--share    <Runtime files and python scripts>

If you have followed the build instructions to this point you should have two directories with libraries in them. D:\BioGears\install and D:\BioGears\external. These directories could be merged if you wish to simplify things to the Include directory or you could install BioGears directly in to external.

Now lets create a new project VitalSign using cmake that will depend on BioGears. To do this you will need to complete the following steps.

  1. Create a directory D:\VitalSigns

  2. Setup an initial folder structure

    a. mkdir src
    b. mkdir cmake
    c. mkdir build

  3. Optional: Setup a git repository

    b. git init D:\VitalSigns c. cat build/ > .gitignore

  4. Create an Initial Test Main File src/main.cpp

   #include <iostream>
   #include <biogears/version.h>
   int main(int args, char* argv[]){
        std::cout << biogears::version_string();
        std::cout << std::endl;
        return 0;   
    }
   }
  1. Create a CMakeLists.txt for the project
cmake_minimum_required(VERSION 3.12)
project (VitalSigns)


file(GLOB HEADERS "src/*.h")
file(GLOB SOURCES "src/*.cpp")

find_package(Biogears REQUIRED)
stage_biogears_schema(DESTINATION ${CMAKE_CURRENT_BINARY_DIR} RESULTS_VAR BIOGEARS_SCHEMA_FILES)
stage_biogears_data(DESTINATION ${CMAKE_CURRENT_BINARY_DIR}   RESULTS_VAR BIOGEARS_DATA_FILES)

add_executable(vitals ${SOURCES} ${HEADERS})
target_link_libraries(vitals Biogears::libbiogears)
add_dependencies(vitals stage_biogears_schema stage_biogears_data)

##############################################
#   Macros to assist in finding runtime dlls
##############################################

  set(CacheForScript ${CMAKE_BINARY_DIR}/stage_$<CONFIG>_script.cmake )
  
  file(GENERATE OUTPUT  ${CacheForScript} 
    CONTENT "
    include(BundleUtilities)
  
    set(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH})

    foreach(_dir IN LISTS CMAKE_PREFIX_PATH)
      list(APPEND THIRD_PARTY  \${_dir})
      list(APPEND THIRD_PARTY_LIB \${_dir}/lib)
      list(APPEND THIRD_PARTY_BIN \${_dir}/bin)
    endforeach()

    fixup_bundle(
	    $<TARGET_FILE:vitals>
        \"\"
        \"${THIRD_PARTY_LIB};${THIRD_PARTY_BIN}\"
	)
    "
  )

add_custom_target(STAGE 
  ${CMAKE_COMMAND} 
  -DCMAKE_INSTALL_CONFIG_NAME=$<CONFIG> -P ${CMAKE_BINARY_DIR}/stage_$<CONFIG>_script.cmake
  )
set_target_properties(STAGE
    PROPERTIES
    FOLDER "CMakePredefinedTargets"
    PROJECT_LABEL "STAGE"
)

add_dependencies(STAGE vitals)

########################################
  1. Setup a build directory and initialize CMake. Based on the installation instructions so far this would look like the following
cmake -DCMAKE_PREFIX_PATH='D:\Biogears\external;D:\BioGears\install' ..
Clone this wiki locally