Maintenance

The following sections describe various iMSTK maintenance tasks

Adding a new iMSTK Dependency

For clarity the new library will be called NewLib. Depending on the use case some of the following steps may be skipped, but that is unlikely.

Superbuild

iMSTK's CMake-based build process proceeds in two stages. The first stage downloads, builds and installs all of iMSTK's dependencies. This stage is called 'Superbuild'. Superbuild allows developers to build iMSTK and its dependencies in one go. When a new dependency needs to be added, the dependency list needs to be updated so that the superbuild builds and installs it for iMSTK to use. This is described in sections below.

Innerbuild

iMSTK's code gets build in the second stage of the build process called 'Innerbuild'. The innerbuild follows the superbuild and expects all dependencies to be built, installed, and findable.

Updating the CMakeLists.txt

In the CMakeLists.txt in the root directory. While we are using ${PROJECT_NAME} to reflect the iMSTK project in this file, everywhere else iMSTK will be more appropriate.

Step 1: Define the external library as a iMSTK dependency

---

if (${PROJECT_NAME}_USE_NewLib) imstk_define_dependency(NewLib) endif()

This tells the superbuild that iMSTK depends on NewLib and will trigger all the other processes namely building, installing, finding and linking to it.

Step 2: Add find_package with the appropriate options for this library

---

if (${PROJECT_NAME}_USE_NewLib) find_package( NewLib REQUIRED ) endif()

This is executed in the innerbuild of iMSTK. It will enable the innerbuild to find the components of the library. Please note that find_package should be executed in the local FindNewLib.cmake that will be created in a later step, and not the CMake top-level script or the find scripts of the library that is being built.

Step 3: Add an option to turn the building of dependency ON/OFF (Optional)

---

Add a Setting ${PROJECT_NAME}_USE_NewLib as

option(${PROJECT_NAME}_USE_NewLib "Build with NewLib support" OFF)
mark_as_superbuild(${PROJECT_NAME}_USE_NewLib)

The state of the option (ON/OFF) should reflect whether the new library should be built by default or not. If a dependency is a required one, one may omit this. If the dependency is optional, one can conditionally execute other steps in the CMake build process by surrounding the statements with if(${PROJECT_NAME}_USE_NewLib) or if(iMSTK_USE_NewLIb).

Variables that need to be passed from the superbuild to the innerbuild need to be "marked" as such using mark_as_superbuild.

Step 4: Edit CMake\External\CMakeLists.txt

---

To enable CMake to find the library correctly if the library already provides a Config.cmake or a Find pass the path to the library into the innerbuild, so use

-DNewLib_DIR:PATH=${NewLib_DIR}  

Step 5: Add CMake/External/External_NewLib.cmake

You will need to create this file which describes what files to download from where and how to build them to support your new library in the superbuild. In general this will mean customizing imstk_add_external_project.

include(imstkAddExternalProject)

# Download options
if(NOT DEFINED iMSTK_NewLib_GIT_SHA)
  set(iMSTK_NewLib_GIT_SHA "...")
endif()
if(NOT DEFINED iMSTK_NewLib_GIT_REPOSITORY)
  set(EXTERNAL_PROJECT_DOWNLOAD_OPTIONS
    URL https://gitlab.kitware.com/iMSTK/newlib/-/archive/${iMSTK_NewLib_GIT_SHA}/newlib-${iMSTK_NewLib_GIT_SHA}.zip
    URL_HASH MD5=...
    )
else()
  set(EXTERNAL_PROJECT_DOWNLOAD_OPTIONS
    GIT_REPOSITORY ${iMSTK_NewLib_GIT_REPOSITORY}
    GIT_TAG ${iMSTK_NewLib_GIT_SHA}
    )
endif()

imstk_add_external_project(NewLib
  ${EXTERNAL_PROJECT_DOWNLOAD_OPTIONS}
  CMAKE_CACHE_ARGS
    ...
  DEPENDENCIES ${NewLib_DEPENDENCIES}
  ...
)

and customizing the build options for the new library by passing them via the CMAKE_CACHE_ARGS section. e.g.

    -DBUILD_TESTING:BOOL=OFF

There are quite a few examples for this in iMSTK now, best is to start simple and extend depending on the needs of the new library. imstk_add_external_project can be found in CMake/Utilities/imstkAddExternalProject.cmake

Step 6: CMake/FindNewLib.cmake

In case NewLib does not provide a cmake NewLibConfig.cmake or its own find you will need to create FindNewLib.cmake in the CMake directory, this will be used during the innerbuild configuration step to initialize the include directories and library files related to the new library. The general pattern is like this. imstkFind can be found in CMake/Utilities

include(imstkFind)

# Locate the header newlib.h inside the newlib subdirectory
imstk_find_header(NewLib newlib.h newlib)
# Find liba and add it to the libraries for NewLib
imstk_find_libary(NewLib liba)
# Finish the process
imstk_find_package(NewLib)

Step 7: Edit CMake/iMSTKConfig.cmake.in

To expose the state of any variables that you set in the superbuild to project that depend on iMSTK you need to store the state inside this file. At installation time, this will be written out and is used to correctly restore the state at build time. e.g.

set(iMSTK_USE_NewLib @iMSTK_USE_NewLib@)

Any find_package commands issued in the main file have to be replicated here are well so that users of iMSTK can access all of its dependencies.

Updating a Dependency in iMSTK

Updating a dependency in imstk

• Swap the url in /CMake/External/<DependencyLibraryName>.cmake to a different url.
  • Ex: https://gitlab.kitware.com/iMSTK/assimp/-/archive/fixCompilationError/assimp-fixCompilationError.zip. Pulling zips prevents git history with it which can be sizeable.
  • Alternatively git shallow would be used to avoid large git histories. But it fails when the tree gets too large, thus if the HEAD of the branch pulled from moves too far, it will fail to pull. (used to cause old version of iMSTK to fail to build until we switched to zips)
• Update the md5 hashsum in that same file (if using zips).
  • The hashsum is a nearly unique identifer generated from the files of the dependency. This mostly is a security measure that ensures you are getting the files you expect to be getting.
  • To acquire the md5 hashsum one can build iMSTK with the newly updated url. It will fail on the md5 check and report both the actual and current md5.

Updating a Remote Fork

Most dependencies in iMSTK are forked. This way we don't depend on the remote repository as it could change (rebased/amended/moved/deleted). A few forks also contain our own diffs in the rare case something like a CMake fix is introduced. To update a fork:

• Clone the fork locally: git clone <git url of fork> (all forks found in iMSTK group here: https://gitlab.kitware.com/iMSTK)
• Add upstream git remote add upstream <url of actual repo/repo forked off> (the description of the fork normally provides what it was forked from)
  • Tip: Issue git remote -v to list all remotes
• Merge upstream (or rebase): git merge upstream/<branch to update from>
• Push your changes

After updating your fork you can proceed with the beginning of this guide on how to pull a different source.

Coverage

iMSTK supports calculating the test coverage via a manual process on Linux only. As a prerequisite lcov needs to be installed. To enable coverage calcuation set iMSTK_COVERAGE to ON, make sure Debug build is selected and run the superbuild as normal. When this is completed cd into the innerbuild directory and execute <makeCommand> Coverage this will start executing the coverage calculation, this may take some time. For the process to succeed all of the tests need to succeed otherwise the command will fail and the process will be aborted. The final information will be under Coverage/index.html

Updating C# wrapping for imstk

• First, build with swig:
  • Install swig (https://www.swig.org/download.html)
  • Add swig executable directory to path
    • Windows: https://www.h3xed.com/windows/how-to-add-to-and-edit-windows-path-variable
    • Linux: https://opensource.com/article/17/6/set-path-linux
  • Modify CMake by setting the iMSTK_WRAP_CSHARP flag to true
  • Rebuild with swig
• Afer building with swig:
  • Navigate to iMSTK>Source>Wrappers>SwigInterface or open iMSTKCWrapper project under wappers
  • In the imstkCWrapper.i file:
    • Add the header to the new wrapped file in the appropriate section with the include <file.h>
    • Add the header file path to the appropriate section with the include <../../(path)/file.h>
  • In the shared_ptr_instantiation.i file:
    • Add the shared_ptr(imstk::<new_type>) in the appropriate section
• Verify that the iMSTKSharp project builds